@base-ui-components/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.
115 lines • 6.1 kB
TypeScript
import * as React from 'react';
import { AriaCombobox } from "../../combobox/root/AriaCombobox.js";
/**
* Groups all parts of the autocomplete.
* Doesn't render its own HTML element.
*
* Documentation: [Base UI Autocomplete](https://base-ui.com/react/components/autocomplete)
*/
export declare function AutocompleteRoot<Items extends readonly {
items: readonly any[];
}[]>(props: Omit<AutocompleteRoot.Props<Items[number]['items'][number]>, 'items'> & {
/**
* The items to be displayed in the list.
* Can be either a flat array of items or an array of groups with items.
*/
items: Items;
}): React.JSX.Element;
export declare function AutocompleteRoot<ItemValue>(props: Omit<AutocompleteRoot.Props<ItemValue>, 'items'> & {
/**
* 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 ItemValue[];
}): React.JSX.Element;
export type AutocompleteRootState = AriaCombobox.State;
export interface AutocompleteRootActions {
unmount: () => void;
}
export type AutocompleteRootChangeEventReason = AriaCombobox.ChangeEventReason;
export type AutocompleteRootChangeEventDetails = AriaCombobox.ChangeEventDetails;
export type AutocompleteRootHighlightEventReason = AriaCombobox.HighlightEventReason;
export type AutocompleteRootHighlightEventDetails = AriaCombobox.HighlightEventDetails;
export interface AutocompleteRootProps<ItemValue> extends Omit<AriaCombobox.Props<ItemValue, 'none'>, 'selectionMode' | 'selectedValue' | 'defaultSelectedValue' | 'onSelectedValueChange' | 'fillInputOnItemPress' | 'itemToStringValue' | 'isItemEqualToValue' | 'inputValue' | 'defaultInputValue' | 'onInputValueChange' | 'autoComplete' | 'itemToStringLabel' | 'autoHighlight' | 'keepHighlight' | 'highlightItemOnHover' | 'actionsRef' | 'onOpenChange'> {
/**
* Controls how the autocomplete 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'
*/
mode?: 'list' | 'both' | 'inline' | 'none';
/**
* Whether the first matching item is highlighted automatically.
* - `true`: highlight after the user types and keep the highlight while the query changes.
* - `'always'`: always highlight the first item.
* @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.
* @default true
*/
highlightItemOnHover?: boolean;
/**
* The uncontrolled input value of the autocomplete when it's initially rendered.
*
* To render a controlled autocomplete, use the `value` prop instead.
*/
defaultValue?: AriaCombobox.Props<React.ComponentProps<'input'>['defaultValue'], 'none'>['defaultInputValue'];
/**
* The input value of the autocomplete. Use when controlled.
*/
value?: AriaCombobox.Props<React.ComponentProps<'input'>['value'], 'none'>['inputValue'];
/**
* Event handler called when the input value of the autocomplete changes.
*/
onValueChange?: (value: string, eventDetails: AutocompleteRootChangeEventDetails) => void;
/**
* Whether clicking an item should submit the autocomplete's owning form.
* By default, clicking an item via a pointer or <kbd>Enter</kbd> key does not submit the owning form.
* Useful when the autocomplete is used as a single-field form search input.
* @default false
*/
submitOnItemClick?: AriaCombobox.Props<ItemValue, 'none'>['submitOnItemClick'];
/**
* When the item values are objects (`<Autocomplete.Item value={object}>`), this function converts the object value to a string representation for both display in the input and form submission.
* If the shape of the object is `{ value, label }`, the label will be used automatically without needing to specify this prop.
*/
itemToStringValue?: (itemValue: ItemValue) => string;
/**
* A ref to imperative actions.
* - `unmount`: When specified, the autocomplete will not be unmounted when closed.
* Instead, the `unmount` function must be called to unmount the autocomplete manually.
* Useful when the autocomplete's animation is controlled by an external library.
*/
actionsRef?: React.RefObject<AutocompleteRootActions>;
/**
* Event handler called when the popup is opened or closed.
*/
onOpenChange?: (open: boolean, eventDetails: AutocompleteRootChangeEventDetails) => void;
/**
* 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?: (highlightedValue: ItemValue | undefined, eventDetails: AutocompleteRootHighlightEventDetails) => void;
}
export declare namespace AutocompleteRoot {
type Props<ItemValue> = AutocompleteRootProps<ItemValue>;
type State = AutocompleteRootState;
type Actions = AutocompleteRootActions;
type ChangeEventReason = AutocompleteRootChangeEventReason;
type ChangeEventDetails = AutocompleteRootChangeEventDetails;
type HighlightEventReason = AutocompleteRootHighlightEventReason;
type HighlightEventDetails = AutocompleteRootHighlightEventDetails;
}