AutoComplete

An unstyled autocomplete input component with real-time search, keyboard navigation, and popup positioning.

Build fully custom autocomplete inputs with complete control over layout and styling.

basic-demo

Pre-styled Versions

Choose a pre-styled library to use AutoComplete with ready-made designs.

Styled

Theme-based styling with CSS variables

Tailwind

Utility-first styling with Tailwind CSS

For hook-based usage without components, see the Headless API.

Features#

Compound component API with sub-components: Root, Input, Trigger, Indicator, Clear, Portal, Positioner, Popup, List, Option, OptionIndicator, Arrow, Header, Footer, Empty, Value
Real-time search via onComplete callback with configurable delay and minimum length
Force selection mode that clears unmatched input on blur
Option grouping with optionGroupLabel and optionGroupChildren
Built-in clear button and trigger toggle support

Usage#

import { AutoComplete } from 'primereact/autocomplete';

<AutoComplete.Root>
    <AutoComplete.Input />
    <AutoComplete.Trigger>
        <AutoComplete.Indicator />
    </AutoComplete.Trigger>
    <AutoComplete.Clear />
    <AutoComplete.Portal>
        <AutoComplete.Positioner>
            <AutoComplete.Popup>
                <AutoComplete.Header />
                <AutoComplete.List>
                    <AutoComplete.Option>
                        <AutoComplete.OptionIndicator />
                    </AutoComplete.Option>
                </AutoComplete.List>
                <AutoComplete.Empty />
                <AutoComplete.Footer />
            </AutoComplete.Popup>
        </AutoComplete.Positioner>
    </AutoComplete.Portal>
</AutoComplete.Root>

Behavior#

Motion Animation#

<AutoComplete.Popup motionProps={{ name: 'p-autocomplete' }}>...</AutoComplete.Popup>

See Motion for animation phases, CSS variables, and hide strategies.

Polymorphic Rendering#

Use as on any sub-component to change the rendered HTML element.

<AutoComplete.Input as={CustomInput} />
<AutoComplete.Trigger as="div">...</AutoComplete.Trigger>

Render Function Children#

AutoComplete.List accepts a render function as children, providing access to the component instance for custom option rendering.

<AutoComplete.List>
    {(instance) =>
        instance.options?.map((option, index) => (
            <AutoComplete.Option key={index} index={index}>
                {instance.listbox?.getOptionLabel(option)}
            </AutoComplete.Option>
        ))
    }
</AutoComplete.List>

Pass Through#

Some parts may not be visible in the preview depending on the component's current state.

Pass Through Sections

Hover or click to explore component parts

/* Select a part to see its CSS selector for custom styling */

API#

AutoCompleteRoot#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: AutoCompleteRootInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: AutoCompleteRootInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`AutoCompleteRootInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<AutoCompleteRootPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: AutoCompleteRootInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`value`	`unknown`	—
The current selected value of the autocomplete.
`defaultValue`	`unknown`	—
The default selected value when used in uncontrolled mode.
`inputValue`	`string`	—
The current input text value (controlled).
`defaultInputValue`	`string`	—
The default input text value when used in uncontrolled mode.
`open`	`boolean`	—
Controlled open state of the input tags overlay.
`defaultOpen`	`boolean`	—
Default open state for uncontrolled mode.
`options`	`unknown[]`	—
An array of options to display.
`optionKey`	`string`	—
Unique key for each option.
`optionLabel`	`string`	—
Label field for each option.
`optionValue`	`string`	—
Value field for each option.
`optionDisabled`	`string`	—
Field to check if an option is disabled.
`optionGroupLabel`	`string`	—
Label field for option groups.
`optionGroupChildren`	`string`	—
Field that contains the children options in a group.
`locale`	`string`	—
The locale to use for localization.
`multiple`	`boolean`	—
When present, allows selecting multiple options.
`metaKeySelection`	`boolean`	—
When enabled, requires holding the meta key to select/deselect.
`autoOptionFocus`	`boolean`	—
When enabled, the focused option is automatically highlighted.
`selectOnFocus`	`boolean`	—
When enabled, the focused option is automatically selected.
`focusOnHover`	`boolean`	—
When enabled, the focused option changes on hover.
`minLength`	`number`	—
Minimum number of characters to initiate a search.
`delay`	`number`	—
Delay between keystrokes to wait before sending a query.
`forceSelection`	`boolean`	—
When present, it specifies that an input field must be filled out before submitting the form.
`tabIndex`	`number`	—
Index of the element in tabbing order.
`invalid`	`boolean`	—
When present, it specifies that the component is in an invalid state.
`name`	`string`	—
Name of the input element.
`required`	`boolean`	—
When present, it specifies that an input field is required.
`closeOnEscape`	`boolean`	—
When enabled, the overlay closes when Escape key is pressed.
`autoFocus`	`boolean`	—
When enabled, the overlay receives focus automatically when opened.
`trapped`	`boolean`	—
When enabled, focus is trapped within the overlay.
`onOpenChange`	`(event: useAutoCompleteOpenChangeEvent) => void`	—
Callback to invoke when the open state changes.
`disabled`	`boolean`	`false`
When present, it specifies that the element should be disabled.
`onValueChange`	`(event: AutoCompleteValueChangeEvent) => void`	—
Callback fired when the autocomplete's input value is changed.
`onInputValueChange`	`(event: AutoCompleteInputValueChangeEvent) => void`	—
Callback fired when the autocomplete's input value is changed.
`onComplete`	`(event: AutoCompleteCompleteEvent) => void`	—
Callback fired when the autocomplete's search is completed.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"autocomplete"`
`data-part`	`"root"`

Defines passthrough(pt) options of AutoComplete component.

label	type	description
root	AutoCompleteRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.
trigger	AutoCompleteRootPassThroughType<HTMLAttributes<HTMLButtonElement>>	Used to pass attributes to the trigger's DOM element.
pcInputText	AutoCompleteRootPassThroughType<HTMLAttributes<HTMLInputElement>>	Used to pass attributes to the pcInputText's DOM element.
value	AutoCompleteRootPassThroughType<HTMLAttributes<HTMLSpanElement>>	Used to pass attributes to the value's DOM element (non-editable mode).
positioner	AutoCompleteRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the positioner's DOM element.
popup	AutoCompleteRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the popup's DOM element.
list	AutoCompleteRootPassThroughType<HTMLAttributes<HTMLUListElement>>	Used to pass attributes to the list's DOM element.
option	AutoCompleteRootPassThroughType<HTMLAttributes<HTMLLIElement>>	Used to pass attributes to the option's DOM element.
clearIcon	AutoCompleteRootPassThroughType<HTMLAttributes<HTMLSpanElement>>	Used to pass attributes to the clearIcon's DOM element.
selection	AutoCompleteRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the selection's DOM element.
header	AutoCompleteRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the header's DOM element.
footer	AutoCompleteRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the footer's DOM element.
empty	AutoCompleteRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the empty's DOM element.

AutoCompleteInput#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: AutoCompleteInputInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: AutoCompleteInputInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`AutoCompleteInputInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<AutoCompleteInputPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: AutoCompleteInputInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"autocomplete"`
`data-part`	`"input"`

Defines passthrough(pt) options of AutoCompleteInput component.

label	type	description
root	AutoCompleteInputPassThroughType<HTMLAttributes<HTMLInputElement>>	Used to pass attributes to the root's DOM element.

AutoCompleteTrigger#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: AutoCompleteTriggerInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: AutoCompleteTriggerInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`AutoCompleteTriggerInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<AutoCompleteTriggerPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: AutoCompleteTriggerInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"autocomplete"`
`data-part`	`"trigger"`
`data-positioner-open`	Present when popup is open

Defines passthrough(pt) options of AutoCompleteTrigger component.

label	type	description
root	AutoCompleteTriggerPassThroughType<HTMLAttributes<HTMLButtonElement>>	Used to pass attributes to the root's DOM element.

AutoCompleteIndicator#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: AutoCompleteIndicatorInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: AutoCompleteIndicatorInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`AutoCompleteIndicatorInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<AutoCompleteIndicatorPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: AutoCompleteIndicatorInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`match`	`"always"` \| `"open"` \| `"closed"`	—
Determines the visibility of the indicator based on the state of the autocomplete. - "open": Indicator is visible when the dropdown is open. - "closed": Indicator is visible when the dropdown is closed. - "always": Indicator is always visible.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"autocomplete"`
`data-part`	`"indicator"`
`data-open`	Present when popup is open
`data-closed`	Present when popup is closed

Defines passthrough(pt) options of AutoCompleteIndicator component.

label	type	description
root	AutoCompleteIndicatorPassThroughType<HTMLAttributes<HTMLSpanElement>>	Used to pass attributes to the root's DOM element.

AutoCompleteClear#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: AutoCompleteClearInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: AutoCompleteClearInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`AutoCompleteClearInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<AutoCompleteClearPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: AutoCompleteClearInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"autocomplete"`
`data-part`	`"clear"`

Defines passthrough(pt) options of AutoCompleteClear component.

label	type	description
root	AutoCompleteClearPassThroughType<HTMLAttributes<HTMLSpanElement>>	Used to pass attributes to the root's DOM element.

AutoCompletePortal#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`(CSSProperties` \| `((instance?: PortalInstance) => CSSProperties)) & (CSSProperties` \| `((instance?: AutoCompletePortalInstance) => CSSProperties))`	—
The style to apply to the component.
`className`	`(string` \| `((instance?: PortalInstance) => string)) & (string` \| `((instance?: AutoCompletePortalInstance) => string))`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`BaseInstance<SafeRecord<PortalProps>, unknown, HTMLElement> & { props: SafeRecord<SafeRecord<PortalProps>>; attrs: Omit<SafeRecord<SafeRecord<PortalProps>>, string` \| `number` \| `symbol> & Record<PropertyKey, unknown> } & { state: SafeRecord; $computedSetup: SafeRecord } & PortalExposes & Record<PropertyKey, unknown> & useComponentPTReturnType & useComponentStyleReturnType & BaseInstance<SafeRecord<AutoCompletePortalProps>, unknown, HTMLElement> & { props: SafeRecord<SafeRecord<AutoCompletePortalProps>>; attrs: Omit<SafeRecord<SafeRecord<AutoCompletePortalProps>>, string` \| `number` \| `symbol> & Record<PropertyKey, unknown> } & { state: SafeRecord; $computedSetup: SafeRecord } & AutoCompletePortalExposes`	—
The instance to pass to the component.
`pt`	`PortalPassThrough & Record<PropertyKey, unknown> & AutoCompletePortalPassThrough`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: PortalInstance) => ReactNode & (instance: AutoCompletePortalInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`onMounted`	`() => void`	—
Callback function to invoke when the portal is mounted.
`onUnmounted`	`() => void`	—
Callback function to invoke when the portal is unmounted.
`element`	`HTMLElement` \| `ReactNode`	—
The element to be rendered as the portal.
`elementRef`	`RefObject<HTMLElement>`	—
The element reference to be rendered as the portal.
`appendTo`	`string` \| `HTMLElement` \| `((instance: PortalInstance) => HTMLElement)`	`'body'`
The DOM element where the portal should be appended to.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Defines passthrough(pt) options of AutoCompletePortal component.

label	type	description
root	AutoCompletePortalPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.

AutoCompletePositioner#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: AutoCompletePositionerInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: AutoCompletePositionerInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`AutoCompletePositionerInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<AutoCompletePositionerPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: AutoCompletePositionerInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`side`	`SideType`	—
The side of the positioner.
`align`	`AlignType`	—
The align of the positioner.
`sideOffset`	`number`	—
The side offset of the positioner.
`alignOffset`	`number`	—
The align offset of the positioner.
`flip`	`boolean`	—
Whether to flip the positioner.
`shift`	`boolean`	—
Whether to shift the positioner.
`hideWhenDetached`	`boolean`	—
Whether to hide the positioner when detached.
`strategy`	`"fixed"` \| `"absolute"`	`'fixed'`
The positioning strategy.
`boundary`	`HTMLElement`	—
The boundary element that constrains the positioner placement. Used in JS fallback mode only; CSS Anchor mode uses the containing block.
`anchor`	`HTMLElement`	—
The anchor element.
`content`	`HTMLDivElement`	—
The content element.
`arrow`	`HTMLDivElement`	—
The arrow element.
`autoZIndex`	`boolean`	`true`
Whether to automatically manage layering.
`baseZIndex`	`number`	`0`
Base zIndex value to use in layering.
`onPlacementChange`	`(placement: { side: SideType; align: AlignType }) => void`	—
Callback invoked when the actual placement changes due to flip or shift.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-side`	`"top"` \| `"bottom"` \| `"left"` \| `"right"` — placement
`data-align`	`"start"` \| `"center"` \| `"end"` — alignment

CSS Custom Properties

The positioner element exposes CSS custom properties for layout and transform control.

CSS Variable	Description
`--available-height`	Available vertical space in pixels
`--available-width`	Available horizontal space in pixels
`--transform-origin`	Computed transform origin for animations
`--positioner-anchor-width`	Width of the anchor/trigger element

Defines passthrough(pt) options of AutoCompletePositioner component.

label	type	description
root	AutoCompletePositionerPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.

AutoCompletePopup#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: AutoCompletePopupInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: AutoCompletePopupInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`AutoCompletePopupInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<AutoCompletePopupPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: AutoCompletePopupInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`motionProps`	`useMotionProps`	—
Used to apply motion to the popup element. It accepts the same properties as useMotion hook.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"autocomplete"`
`data-part`	`"popup"`
`data-open`	Present when popup is open

Defines passthrough(pt) options of AutoCompletePopup component.

label	type	description
root	AutoCompletePopupPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.

AutoCompleteList#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: AutoCompleteListInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: AutoCompleteListInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`AutoCompleteListInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<AutoCompleteListPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: AutoCompleteListInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"autocomplete"`
`data-part`	`"list"`

Defines passthrough(pt) options of AutoCompleteList component.

label	type	description
root	AutoCompleteListPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.

AutoCompleteOption#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: AutoCompleteOptionInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: AutoCompleteOptionInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`AutoCompleteOptionInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<AutoCompleteOptionPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: AutoCompleteOptionInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`option`	`unknown`	—
The option data.
`index`	`number`	—
The index of the option.
`selected`	`boolean`	—
Whether the option is selected.
`focused`	`boolean`	—
Whether the option is focused.
`disabled`	`boolean`	—
Whether the option is disabled.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-selected`	Present when selected
`data-unselected`	Present when unselected
`data-focused`	Present when focused
`data-disabled`	Present when disabled

Defines passthrough(pt) options of AutoCompleteOption component.

label	type	description
root	AutoCompleteOptionPassThroughType<HTMLAttributes<HTMLLIElement>>	Used to pass attributes to the root's DOM element.

AutoCompleteOptionIndicator#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: AutoCompleteOptionIndicatorInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: AutoCompleteOptionIndicatorInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`AutoCompleteOptionIndicatorInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<AutoCompleteOptionIndicatorPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: AutoCompleteOptionIndicatorInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-selected`	Present when selected
`data-unselected`	Present when unselected

Defines passthrough(pt) options of AutoCompleteOptionIndicator component.

label	type	description
root	AutoCompleteOptionIndicatorPassThroughType<HTMLAttributes<HTMLElement>>	Used to pass attributes to the root's DOM element.

AutoCompleteHeader#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: AutoCompleteHeaderInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: AutoCompleteHeaderInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`AutoCompleteHeaderInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<AutoCompleteHeaderPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: AutoCompleteHeaderInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Defines passthrough(pt) options of AutoCompleteHeader component.

label	type	description
root	AutoCompleteHeaderPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.

AutoCompleteFooter#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: AutoCompleteFooterInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: AutoCompleteFooterInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`AutoCompleteFooterInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<AutoCompleteFooterPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: AutoCompleteFooterInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Defines passthrough(pt) options of AutoCompleteFooter component.

label	type	description
root	AutoCompleteFooterPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.

AutoCompleteEmpty#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: AutoCompleteEmptyInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: AutoCompleteEmptyInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`AutoCompleteEmptyInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<AutoCompleteEmptyPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: AutoCompleteEmptyInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Defines passthrough(pt) options of AutoCompleteEmpty component.

label	type	description
root	AutoCompleteEmptyPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.

AutoCompleteArrow#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: AutoCompleteArrowInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: AutoCompleteArrowInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`AutoCompleteArrowInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<AutoCompleteArrowPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: AutoCompleteArrowInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-side`	`"top"` \| `"bottom"` \| `"left"` \| `"right"` — placement
`data-align`	`"start"` \| `"center"` \| `"end"` — alignment

The arrow element exposes CSS custom properties for dynamic positioning:

CSS Variable	Description
`--placer-arrow-x`	Horizontal offset of arrow
`--placer-arrow-y`	Vertical offset of arrow
`--placer-arrow-left`	Left position of arrow element
`--placer-arrow-top`	Top position of arrow element

Defines passthrough(pt) options of AutoCompleteArrow component.

label	type	description
root	AutoCompleteArrowPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.

AutoCompleteValue#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: AutoCompleteValueInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: AutoCompleteValueInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`AutoCompleteValueInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<AutoCompleteValuePassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: AutoCompleteValueInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`placeholder`	`string`	—
Placeholder text to display when no option is selected.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Defines passthrough(pt) options of AutoCompleteValue component.

label	type	description
root	AutoCompleteValuePassThroughType<HTMLAttributes<HTMLSpanElement>>	Used to pass attributes to the root's DOM element.

Accessibility#

AutoComplete.Root uses a combobox pattern. The input has role="combobox" with aria-autocomplete, aria-haspopup and aria-expanded attributes. The relation between the input and the popup is created with aria-controls and aria-activedescendant attribute is used to instruct screen reader which option to read during keyboard navigation within the popup list. Options have role="option" with aria-selected to indicate the current selection. The clear button has an aria-label for screen reader accessibility. Provide an accessible name with aria-label, aria-labelledby, or an associated label element.

Keyboard Support#

Key	Function
`tab`	Moves focus to the autocomplete element.
`any printable character`	Opens the popup and displays matching suggestions.
`enter`	Selects the focused option and closes the popup.
`escape`	Closes the popup.
`arrow down`	Opens the popup or moves focus to the next option.
`arrow up`	Opens the popup or moves focus to the previous option.
`arrow left`	Removes the visual focus from the current option and moves input cursor.
`arrow right`	Removes the visual focus from the current option and moves input cursor.
`home`	Moves focus to the first option.
`end`	Moves focus to the last option.
`pageUp`	Jumps visual focus to the first option.
`pageDown`	Jumps visual focus to the last option.