@itwin/itwinui-react/cjs/core/ComboBox/ComboBox.d.ts

A react component library for iTwinUI

import * as React from 'react';
import type { SelectOption } from '../Select/Select.js';
import type { Input } from '../Input/Input.js';
import { usePopover } from '../Popover/Popover.js';
import type { InputContainerProps, CommonProps, PortalProps } from '../../utils/index.js';
import { ComboBoxEndIcon } from './ComboBoxEndIcon.js';
type ActionType = 'added' | 'removed';
type MultipleOnChangeProps<T> = {
    value: T;
    type: ActionType;
};
export type ComboboxMultipleTypeProps<T> = {
    /**
     * Enable multiple selection.
     * @default false
     */
    multiple?: false;
    /**
     * Controlled value of ComboBox.
     * If `multiple` is enabled, it is an array of values.
     *
     * Pass `null` or `undefined` to reset the value. Apart from resetting the value:
     * * `value={null}` will switch to/remain in the *controlled* state.
     * * `value={undefined}` will switch to/remain in the *uncontrolled* state.
     */
    value?: T | null | undefined;
    /**
     * Default value of `value` that is set on initial render. This is useful when you don't want to
     * maintain your own state but still want to control the initial `value`.
     */
    defaultValue?: T | null;
    /**
     * Callback fired when selected value changes.
     */
    onChange?: (value: T) => void;
    /**
     * Only applicable when `multiple` is enabled.
     *
     * If `true`, toggling an option will clear the filter.
     * Useful when users would likely want to re-filter after toggling an option.
     *
     * If `false`, the filter will remain as-is after toggling an option.
     * Useful when users would likely want to toggle multiple options from the _same_ filtered results.
     *
     * @default true
     */
    clearFilterOnOptionToggle?: never;
} | {
    multiple: true;
    value?: T[] | null | undefined;
    defaultValue?: T[] | null;
    onChange?: (value: T[], event: MultipleOnChangeProps<T>) => void;
    clearFilterOnOptionToggle?: boolean;
};
export type ComboBoxProps<T> = {
    /**
     * Array of options that populate the dropdown list.
     */
    options: SelectOption<T>[];
    /**
     * Message shown below the combobox.
     * Use `StatusMessage` component.
     */
    message?: React.ReactNode;
    /**
     * Function to customize the default filtering logic.
     */
    filterFunction?: (options: SelectOption<T>[], inputValue: string) => SelectOption<T>[];
    /**
     * Native input element props.
     */
    inputProps?: React.ComponentProps<typeof Input>;
    /**
     * Props to customize dropdown menu behavior.
     */
    dropdownMenuProps?: React.ComponentProps<'div'> & Pick<Parameters<typeof usePopover>['0'], 'middleware'> & Pick<PortalProps, 'portal'>;
    /**
     * End icon props.
     */
    endIconProps?: React.ComponentProps<typeof ComboBoxEndIcon>;
    /**
     * Message shown when no options are available.
     * If `React.JSX.Element` is provided, it will be rendered as is and won't be wrapped with `MenuExtraContent`.
     * @default 'No options found'
     */
    emptyStateMessage?: React.ReactNode;
    /**
     * A custom item renderer can be specified to control the rendering.
     *
     * For keyboard navigation to work, the returned element should use the `id` provided by this function.
     * The `isFocused` state is calculated using this `id` and can be used for specifying the focus styling.
     * If a `MenuItem` is returned, then focus styling is automatically handled.
     */
    itemRenderer?: (option: SelectOption<T>, states: {
        isSelected: boolean;
        isFocused: boolean;
        id: string;
        index: number;
    }) => React.JSX.Element;
    /**
     * If enabled, virtualization is used for the scrollable dropdown list.
     * Use it if you expect a very long list of items.
     * @default false
     * @beta
     */
    enableVirtualization?: boolean;
    /**
     * Callback fired when dropdown menu is opened.
     */
    onShow?: () => void;
    /**
     * Callback fired when dropdown menu is closed.
     */
    onHide?: () => void;
} & ComboboxMultipleTypeProps<T> & Pick<InputContainerProps, 'status'> & CommonProps;
/**
 * ComboBox component that allows typing a value to filter the options in dropdown list.
 * Values can be selected either using mouse clicks or using the Enter key.
 * @example
 * <ComboBox
 *   options={[
 *     { label: 'Item 1', value: 1 },
 *     { label: 'Item 2', value: 2 },
 *     { label: 'Item 3', value: 3 },
 *   ]}
 *   onChange={() => {}}
 * />
 */
export declare const ComboBox: <T>(props: ComboBoxProps<T> & {
    ref?: React.ForwardedRef<HTMLElement>;
}) => React.JSX.Element;
export {};