@base-ui/react
Version:
Base UI is a library of headless ('unstyled') React components and low-level hooks. You gain complete control over your app's CSS and accessibility features.
244 lines • 10.6 kB
TypeScript
import * as React from 'react';
import { type BaseUIChangeEventDetails, type BaseUIGenericEventDetails } from "../../utils/createBaseUIEventDetails.js";
import { REASONS } from "../../utils/reasons.js";
import { Group } from "../../utils/resolveValueLabel.js";
/**
* @internal
*/
export declare function AriaCombobox<Value, Mode extends SelectionMode = 'none'>(props: Omit<ComboboxRootConditionalProps<Value, Mode>, 'items'> & {
items: readonly Group<any>[];
}): React.JSX.Element;
export declare function AriaCombobox<Value, Mode extends SelectionMode = 'none'>(props: Omit<ComboboxRootConditionalProps<Value, Mode>, 'items'> & {
items?: readonly any[];
}): React.JSX.Element;
type SelectionMode = 'single' | 'multiple' | 'none';
type ComboboxItemValueType<ItemValue, Mode extends SelectionMode> = Mode extends 'multiple' ? ItemValue[] : ItemValue;
interface ComboboxRootProps<ItemValue> {
children?: React.ReactNode;
/**
* Identifies the field when a form is submitted.
*/
name?: string;
/**
* The id of the component.
*/
id?: string;
/**
* Whether the user must choose a value before submitting a form.
* @default false
*/
required?: boolean;
/**
* Whether the user should be unable to choose a different option from the popup.
* @default false
*/
readOnly?: boolean;
/**
* Whether the component should ignore user interaction.
* @default false
*/
disabled?: boolean;
/**
* Whether the popup is initially open.
*
* To render a controlled popup, use the `open` prop instead.
* @default false
*/
defaultOpen?: boolean;
/**
* Whether the popup is currently open. Use when controlled.
*/
open?: boolean;
/**
* Event handler called when the popup is opened or closed.
*/
onOpenChange?: (open: boolean, eventDetails: AriaCombobox.ChangeEventDetails) => void;
/**
* Event handler called after any animations complete when the popup is opened or closed.
*/
onOpenChangeComplete?: (open: boolean) => void;
/**
* Whether the popup opens when clicking the input.
* @default true
*/
openOnInputClick?: boolean;
/**
* Whether the first matching item is highlighted automatically.
* - `false`: do not highlight automatically.
* - `true`: highlight after the user types and keep the highlight while the query changes.
* - `'always'`: highlight the first item as soon as the list opens.
* @default false
*/
autoHighlight?: boolean | 'always';
/**
* Whether the highlighted item should be preserved when the pointer leaves the list.
* @default false
*/
keepHighlight?: boolean;
/**
* Whether moving the pointer over items should highlight them.
* Disabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state.
* @default true
*/
highlightItemOnHover?: boolean;
/**
* Whether to loop keyboard focus back to the input when the end of the list is reached while using the arrow keys. The first item can then be reached by pressing <kbd>ArrowDown</kbd> again from the input, or the last item can be reached by pressing <kbd>ArrowUp</kbd> from the input.
* The input is always included in the focus loop per [ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/).
* When disabled, focus does not move when on the last element and the user presses <kbd>ArrowDown</kbd>, or when on the first element and the user presses <kbd>ArrowUp</kbd>.
* @default true
*/
loopFocus?: boolean;
/**
* The input value of the combobox. Use when controlled.
*/
inputValue?: React.ComponentProps<'input'>['value'];
/**
* Callback fired when the input value of the combobox changes.
*/
onInputValueChange?: (value: string, eventDetails: AriaCombobox.ChangeEventDetails) => void;
/**
* The uncontrolled input value when initially rendered.
*
* To render a controlled input, use the `inputValue` prop instead.
*/
defaultInputValue?: React.ComponentProps<'input'>['defaultValue'];
/**
* A ref to imperative actions.
* - `unmount`: When specified, the combobox will not be unmounted when closed.
* Instead, the `unmount` function must be called to unmount the combobox manually.
* Useful when the combobox's animation is controlled by an external library.
*/
actionsRef?: React.RefObject<AriaCombobox.Actions | null>;
/**
* Callback fired when an item is highlighted or unhighlighted.
* Receives the highlighted item value (or `undefined` if no item is highlighted) and event details with a `reason` property describing why the highlight changed.
* The `reason` can be:
* - `'keyboard'`: the highlight changed due to keyboard navigation.
* - `'pointer'`: the highlight changed due to pointer hovering.
* - `'none'`: the highlight changed programmatically.
*/
onItemHighlighted?: (itemValue: ItemValue | undefined, eventDetails: AriaCombobox.HighlightEventDetails) => void;
/**
* A ref to the hidden input element.
*/
inputRef?: React.Ref<HTMLInputElement>;
/**
* Whether list items are presented in a grid layout.
* When enabled, arrow keys navigate across rows and columns inferred from DOM rows.
* @default false
*/
grid?: boolean;
/**
* The items to be displayed in the list.
* Can be either a flat array of items or an array of groups with items.
*/
items?: readonly any[] | readonly Group<any>[];
/**
* Filtered items to display in the list.
* When provided, the list will use these items instead of filtering the `items` prop internally.
* Use when you want to control filtering logic externally with the `useFilter()` hook.
*/
filteredItems?: readonly any[] | readonly Group<any>[];
/**
* Filter function used to match items vs input query.
*/
filter?: null | ((itemValue: ItemValue, query: string, itemToString?: (itemValue: ItemValue) => string) => boolean);
/**
* When the item values are objects (`<Combobox.Item value={object}>`), this function converts the object value to a string representation for display in the input.
* If the shape of the object is `{ value, label }`, the label will be used automatically without needing to specify this prop.
*/
itemToStringLabel?: (itemValue: ItemValue) => string;
/**
* When the item values are objects (`<Combobox.Item value={object}>`), this function converts the object value to a string representation for form submission.
* If the shape of the object is `{ value, label }`, the value will be used automatically without needing to specify this prop.
*/
itemToStringValue?: (itemValue: ItemValue) => string;
/**
* Custom comparison logic used to determine if a combobox item value matches the current selected value. Useful when item values are objects without matching referentially.
* Defaults to `Object.is` comparison.
*/
isItemEqualToValue?: (itemValue: ItemValue, selectedValue: ItemValue) => boolean;
/**
* Whether the items are being externally virtualized.
* @default false
*/
virtualized?: boolean;
/**
* Whether the list is rendered inline without using the popup.
* @default false
*/
inline?: boolean;
/**
* Determines if the popup enters a modal state when open.
* - `true`: user interaction is limited to the popup: document page scroll is locked and pointer interactions on outside elements are disabled.
* - `false`: user interaction with the rest of the document is allowed.
* @default false
*/
modal?: boolean;
/**
* The maximum number of items to display in the list.
* @default -1
*/
limit?: number;
/**
* Controls how the component behaves with respect to list filtering and inline autocompletion.
* - `list` (default): items are dynamically filtered based on the input value. The input value does not change based on the active item.
* - `both`: items are dynamically filtered based on the input value, which will temporarily change based on the active item (inline autocompletion).
* - `inline`: items are static (not filtered), and the input value will temporarily change based on the active item (inline autocompletion).
* - `none`: items are static (not filtered), and the input value will not change based on the active item.
* @default 'list'
*/
autoComplete?: 'list' | 'both' | 'inline' | 'none';
/**
* The locale to use for string comparison.
* Defaults to the user's runtime locale.
*/
locale?: Intl.LocalesArgument;
/**
* Whether clicking an item should submit the owning form.
* @default false
*/
submitOnItemClick?: boolean;
/**
* INTERNAL: When `selectionMode` is `none`, controls whether selecting an item fills the input.
*/
fillInputOnItemPress?: boolean;
}
export type ComboboxRootConditionalProps<Value, Mode extends SelectionMode = 'none'> = Omit<ComboboxRootProps<Value>, 'selectionMode' | 'selectedValue' | 'defaultSelectedValue' | 'onSelectedValueChange'> & {
/**
* How the combobox should remember the selected value.
* - `single`: Remembers the last selected value.
* - `multiple`: Remember all selected values.
* - `none`: Do not remember the selected value.
* @default 'none'
*/
selectionMode?: Mode;
/**
* The selected value of the combobox. Use when controlled.
*/
selectedValue?: ComboboxItemValueType<Value, Mode>;
/**
* The uncontrolled selected value of the combobox when it's initially rendered.
*
* To render a controlled combobox, use the `selectedValue` prop instead.
*/
defaultSelectedValue?: ComboboxItemValueType<Value, Mode> | null;
/**
* Callback fired when the selected value of the combobox changes.
*/
onSelectedValueChange?: (value: ComboboxItemValueType<Value, Mode>, eventDetails: AriaCombobox.ChangeEventDetails) => void;
};
export declare namespace AriaCombobox {
type Props<Value, Mode extends SelectionMode = 'none'> = ComboboxRootConditionalProps<Value, Mode>;
interface State {}
interface Actions {
unmount: () => void;
}
type HighlightEventReason = 'keyboard' | 'pointer' | 'none';
type HighlightEventDetails = BaseUIGenericEventDetails<HighlightEventReason, {
index: number;
}>;
type ChangeEventReason = typeof REASONS.triggerPress | typeof REASONS.outsidePress | typeof REASONS.itemPress | typeof REASONS.escapeKey | typeof REASONS.listNavigation | typeof REASONS.focusOut | typeof REASONS.inputChange | typeof REASONS.inputClear | typeof REASONS.clearPress | typeof REASONS.chipRemovePress | typeof REASONS.none;
type ChangeEventDetails = BaseUIChangeEventDetails<ChangeEventReason>;
}
export {};