@diceui/combobox/dist/index.d.ts

Combobox is a component that allows users to select an option from a list of options.

import { Primitive, AnchorPositionerProps, PointerDownOutsideEvent, WithDisplayName, Direction, WithForwardedRef, PortalProps } from '@diceui/shared';
import * as React from 'react';

interface ComboboxAnchorProps extends React.ComponentPropsWithoutRef<typeof Primitive.div> {
    /**
     * Whether the combobox input should be focused when the anchor is clicked.
     * @default false
     */
    preventInputFocus?: boolean;
}
declare const ComboboxAnchor: React.ForwardRefExoticComponent<ComboboxAnchorProps & React.RefAttributes<HTMLDivElement>>;
declare const Anchor: React.ForwardRefExoticComponent<ComboboxAnchorProps & React.RefAttributes<HTMLDivElement>>;

interface ComboboxContentProps extends AnchorPositionerProps, React.ComponentPropsWithoutRef<typeof Primitive.div> {
    /**
     * Event handler called when the `Escape` key is pressed.
     *
     * Can be used to prevent input value from being reset on `Escape` key press.
     */
    onEscapeKeyDown?: (event: KeyboardEvent) => void;
    /**
     * Event handler called when a `pointerdown` event happens outside of the content.
     *
     * Can be used to prevent the popover from closing when the pointer is outside of the content.
     */
    onPointerDownOutside?: (event: PointerDownOutsideEvent) => void;
}
declare const ComboboxContent: React.ForwardRefExoticComponent<ComboboxContentProps & React.RefAttributes<HTMLDivElement>>;
declare const Content: React.ForwardRefExoticComponent<ComboboxContentProps & React.RefAttributes<HTMLDivElement>>;

interface ComboboxInputProps extends React.ComponentPropsWithoutRef<typeof Primitive.input> {
}
declare const ComboboxInput: React.ForwardRefExoticComponent<ComboboxInputProps & React.RefAttributes<HTMLInputElement>>;
declare const Input: React.ForwardRefExoticComponent<ComboboxInputProps & React.RefAttributes<HTMLInputElement>>;

interface ComboboxItemTextProps extends React.ComponentPropsWithoutRef<typeof Primitive.span> {
}
declare const ComboboxItemText: React.ForwardRefExoticComponent<ComboboxItemTextProps & React.RefAttributes<HTMLSpanElement>>;
declare const ItemText: React.ForwardRefExoticComponent<ComboboxItemTextProps & React.RefAttributes<HTMLSpanElement>>;

interface ComboboxItemProps extends Omit<React.ComponentPropsWithoutRef<typeof Primitive.div>, "onSelect"> {
    /**
     * The value of the item.
     *
     * Cannot be an empty string.
     */
    value: string;
    /**
     * The label of the item. By default, value is used as the label.
     *
     * Override the text value for the selected item in the input.
     */
    label?: string;
    /** Whether the item is disabled. */
    disabled?: boolean;
    /** Callback called when the item is selected. */
    onSelect?: (value: string) => void;
}
declare const ComboboxItem: React.ForwardRefExoticComponent<ComboboxItemProps & React.RefAttributes<HTMLDivElement>>;
declare const Item: React.ForwardRefExoticComponent<ComboboxItemProps & React.RefAttributes<HTMLDivElement>>;

type Value<Multiple extends boolean = false> = Multiple extends true ? string[] : string;
type RootElement = React.ElementRef<typeof Primitive.div>;
interface ComboboxRootProps<Multiple extends boolean = false> extends Omit<React.ComponentPropsWithoutRef<typeof Primitive.div>, "value" | "defaultValue" | "onValueChange"> {
    /**
     * The current value of the combobox.
     *
     * - When multiple is false: `string`
     * - When multiple is true: `string[]`
     */
    value?: Value<Multiple>;
    /**
     * The default value of the combobox.
     *
     * - When multiple is false: `string`
     * - When multiple is true: `string[]`
     */
    defaultValue?: Value<Multiple>;
    /**
     * Event handler called when the value changes.
     *
     * - When multiple is false: `(value: string) => void`
     * - When multiple is true: `(value: string[]) => void`
     */
    onValueChange?: (value: Value<Multiple>) => void;
    /** Whether the combobox is open. */
    open?: boolean;
    /**
     * Whether the combobox is open by default.
     * @default false
     */
    defaultOpen?: boolean;
    /** Event handler called when the open state of the combobox changes. */
    onOpenChange?: (open: boolean) => void;
    /** The current input value of the combobox. */
    inputValue?: string;
    /** Event handler called when the input value changes. */
    onInputValueChange?: (value: string) => void;
    /**
     * Event handler called when the filter is applied.
     *
     * Can be used to prevent the default filtering behavior.
     */
    onFilter?: (options: string[], inputValue: string) => string[];
    /**
     * The reading direction of the combobox.
     * @default "ltr"
     */
    dir?: Direction;
    /**
     * Whether to automatically highlight the first visible item when filtering.
     * @default false
     */
    autoHighlight?: boolean;
    /** Whether the combobox is disabled. */
    disabled?: boolean;
    /**
     * Whether the combobox uses exact string matching or fuzzy matching.
     *
     * When `manualFiltering` is true, this prop is ignored.
     * When `onFilter` is provided, the combobox will use the provided filter function instead.
     *
     * @default false
     */
    exactMatch?: boolean;
    /**
     * Whether the combobox should filter items externally.
     * @default false
     */
    manualFiltering?: boolean;
    /**
     * Whether the combobox loops through items.
     * @default false
     */
    loop?: boolean;
    /**
     * Whether the combobox is modal.
     * @default false
     */
    modal?: boolean;
    /**
     * Whether the combobox allows multiple values.
     * @default false
     */
    multiple?: Multiple;
    /**
     * Whether the combobox opens on input focus.
     * @default false
     */
    openOnFocus?: boolean;
    /**
     * Whether to preserve the input value when the input is blurred and no item is selected.
     *
     * Only applicable when items are not selected.
     * @default false
     */
    preserveInputOnBlur?: boolean;
    /**
     * Whether the combobox is read-only.
     * @default false
     */
    readOnly?: boolean;
    /**
     * Whether the combobox is required in a form context.
     * @default false
     */
    required?: boolean;
    /** The name of the combobox for form submission. */
    name?: string;
}
declare function ComboboxRootImpl<Multiple extends boolean = false>(props: ComboboxRootProps<Multiple>, forwardedRef: React.ForwardedRef<RootElement>): React.JSX.Element;
interface ComboboxRootComponentProps extends WithDisplayName {
    <Multiple extends boolean = false>(props: ComboboxRootProps<Multiple> & WithForwardedRef<typeof ComboboxRootImpl>): React.JSX.Element;
}
declare const ComboboxRoot: ComboboxRootComponentProps;
declare const Root: ComboboxRootComponentProps;

interface ComboboxLabelProps extends React.ComponentPropsWithoutRef<typeof Primitive.label> {
}
declare const ComboboxLabel: React.ForwardRefExoticComponent<ComboboxLabelProps & React.RefAttributes<HTMLLabelElement>>;
declare const Label: React.ForwardRefExoticComponent<ComboboxLabelProps & React.RefAttributes<HTMLLabelElement>>;

interface ComboboxTriggerProps extends React.ComponentPropsWithoutRef<typeof Primitive.button> {
}
declare const ComboboxTrigger: React.ForwardRefExoticComponent<ComboboxTriggerProps & React.RefAttributes<HTMLButtonElement>>;
declare const Trigger: React.ForwardRefExoticComponent<ComboboxTriggerProps & React.RefAttributes<HTMLButtonElement>>;

interface ComboboxBadgeListProps extends React.ComponentPropsWithoutRef<typeof Primitive.div> {
    /**
     * Whether to force mount the badge list even if there is no selected item.
     * @default false
     */
    forceMount?: boolean;
    /**
     * The orientation of the badge list.
     * @default "horizontal"
     */
    orientation?: "horizontal" | "vertical";
}
declare const ComboboxBadgeList: React.ForwardRefExoticComponent<ComboboxBadgeListProps & React.RefAttributes<HTMLDivElement>>;
declare const BadgeList: React.ForwardRefExoticComponent<ComboboxBadgeListProps & React.RefAttributes<HTMLDivElement>>;

interface ComboboxBadgeItemProps extends React.ComponentPropsWithoutRef<typeof Primitive.div> {
    /** The value of the badge item. */
    value: string;
    /**
     * Whether the badge item is disabled.
     * @default false
     */
    disabled?: boolean;
}
declare const ComboboxBadgeItem: React.ForwardRefExoticComponent<ComboboxBadgeItemProps & React.RefAttributes<HTMLDivElement>>;
declare const BadgeItem: React.ForwardRefExoticComponent<ComboboxBadgeItemProps & React.RefAttributes<HTMLDivElement>>;

interface ComboboxBadgeItemDeleteProps extends React.ComponentPropsWithoutRef<typeof Primitive.button> {
}
declare const ComboboxBadgeItemDelete: React.ForwardRefExoticComponent<ComboboxBadgeItemDeleteProps & React.RefAttributes<HTMLButtonElement>>;
declare const BadgeItemDelete: React.ForwardRefExoticComponent<ComboboxBadgeItemDeleteProps & React.RefAttributes<HTMLButtonElement>>;

interface ComboboxCancelProps extends React.ComponentPropsWithoutRef<typeof Primitive.button> {
    /**
     * Whether the cancel button should always be rendered.
     *
     * By default, the cancel button is only rendered when the input has a value.
     * @default false
     */
    forceMount?: boolean;
}
declare const ComboboxCancel: React.ForwardRefExoticComponent<ComboboxCancelProps & React.RefAttributes<HTMLButtonElement>>;
declare const Cancel: React.ForwardRefExoticComponent<ComboboxCancelProps & React.RefAttributes<HTMLButtonElement>>;

interface ComboboxPortalProps extends Pick<PortalProps, "container" | "children"> {
}
declare const ComboboxPortal: React.ForwardRefExoticComponent<ComboboxPortalProps & React.RefAttributes<HTMLDivElement>>;
declare const Portal: React.ForwardRefExoticComponent<ComboboxPortalProps & React.RefAttributes<HTMLDivElement>>;

interface ComboboxArrowProps extends React.ComponentPropsWithoutRef<typeof Primitive.svg> {
    /**
     * The width of the arrow in pixels.
     * @default 10
     */
    width?: number;
    /**
     * The height of the arrow in pixels.
     * @default 5
     */
    height?: number;
}
declare const ComboboxArrow: React.ForwardRefExoticComponent<ComboboxArrowProps & React.RefAttributes<SVGSVGElement>>;
declare const Arrow: React.ForwardRefExoticComponent<ComboboxArrowProps & React.RefAttributes<SVGSVGElement>>;

interface ComboboxLoadingProps extends React.ComponentPropsWithoutRef<typeof Primitive.div> {
    /**
     * The current progress value.
     * @default null
     */
    value?: number | null;
    /**
     * The maximum progress value.
     * @default 100
     */
    max?: number;
    /** The accessible label for the progress bar. */
    label?: string;
}
declare const ComboboxLoading: React.ForwardRefExoticComponent<ComboboxLoadingProps & React.RefAttributes<HTMLDivElement>>;
declare const Loading: React.ForwardRefExoticComponent<ComboboxLoadingProps & React.RefAttributes<HTMLDivElement>>;

interface ComboboxEmptyProps extends React.ComponentPropsWithoutRef<typeof Primitive.div> {
    /**
     * Whether to render the empty state even when search filtering is active.
     *
     * Can be used for `manualFiltering` comboboxes to show the empty state.
     * @default false
     */
    keepVisible?: boolean;
}
declare const ComboboxEmpty: React.ForwardRefExoticComponent<ComboboxEmptyProps & React.RefAttributes<HTMLDivElement>>;
declare const Empty: React.ForwardRefExoticComponent<ComboboxEmptyProps & React.RefAttributes<HTMLDivElement>>;

interface ComboboxGroupProps extends React.ComponentPropsWithoutRef<typeof Primitive.div> {
    /**
     * Whether to render the group even if it's not visible during filtering.
     * @default false
     */
    forceMount?: boolean;
}
declare const ComboboxGroup: React.ForwardRefExoticComponent<ComboboxGroupProps & React.RefAttributes<HTMLDivElement>>;
declare const Group: React.ForwardRefExoticComponent<ComboboxGroupProps & React.RefAttributes<HTMLDivElement>>;

interface ComboboxGroupLabelProps extends React.ComponentPropsWithoutRef<typeof Primitive.div> {
}
declare const ComboboxGroupLabel: React.ForwardRefExoticComponent<ComboboxGroupLabelProps & React.RefAttributes<HTMLDivElement>>;
declare const GroupLabel: React.ForwardRefExoticComponent<ComboboxGroupLabelProps & React.RefAttributes<HTMLDivElement>>;

interface ComboboxItemIndicatorProps extends React.ComponentPropsWithoutRef<typeof Primitive.span> {
    /**
     * Whether to render the indicator even if the item is not selected.
     * @default false
     */
    forceMount?: boolean;
}
declare const ComboboxItemIndicator: React.ForwardRefExoticComponent<ComboboxItemIndicatorProps & React.RefAttributes<HTMLSpanElement>>;
declare const ItemIndicator: React.ForwardRefExoticComponent<ComboboxItemIndicatorProps & React.RefAttributes<HTMLSpanElement>>;

interface ComboboxSeparatorProps extends React.ComponentPropsWithoutRef<typeof Primitive.div> {
    /**
     * Whether the separator should remain visible when search filtering is active.
     * @default false
     */
    keepVisible?: boolean;
}
declare const ComboboxSeparator: React.ForwardRefExoticComponent<ComboboxSeparatorProps & React.RefAttributes<HTMLDivElement>>;
declare const Separator: React.ForwardRefExoticComponent<ComboboxSeparatorProps & React.RefAttributes<HTMLDivElement>>;

export { Anchor, Arrow, BadgeItem, BadgeItemDelete, BadgeList, Cancel, ComboboxAnchor, type ComboboxAnchorProps, ComboboxArrow, type ComboboxArrowProps, ComboboxBadgeItem, ComboboxBadgeItemDelete, type ComboboxBadgeItemDeleteProps, type ComboboxBadgeItemProps, ComboboxBadgeList, type ComboboxBadgeListProps, ComboboxCancel, type ComboboxCancelProps, ComboboxContent, type ComboboxContentProps, ComboboxEmpty, type ComboboxEmptyProps, ComboboxGroup, ComboboxGroupLabel, type ComboboxGroupLabelProps, type ComboboxGroupProps, ComboboxInput, type ComboboxInputProps, ComboboxItem, ComboboxItemIndicator, type ComboboxItemIndicatorProps, type ComboboxItemProps, ComboboxItemText, type ComboboxItemTextProps, ComboboxLabel, type ComboboxLabelProps, ComboboxLoading, type ComboboxLoadingProps, ComboboxPortal, type ComboboxPortalProps, ComboboxRoot, type ComboboxRootComponentProps, type ComboboxRootProps, ComboboxSeparator, type ComboboxSeparatorProps, ComboboxTrigger, type ComboboxTriggerProps, Content, Empty, Group, GroupLabel, Input, Item, ItemIndicator, ItemText, Label, Loading, Portal, Root, Separator, Trigger };