` element.
**Autocomplete.Positioner Props:**
| Prop | Type | Default | Description |
| :--- | :--- | :------ | :---------- |
| anchor | `Anchor` | - | An element to position the popup against. Defaults to the input group, input or trigger. |
| positionMethod | `"absolute" \| "fixed"` | `'absolute'` | Which CSS `position` the positioner uses. |
| side | `Side` | `'bottom'` | Which side of the anchor to place the popup on. It can flip to avoid collisions. |
| align | `Align` | `'center'` | How to align the popup on its side. |
| sideOffset | `number \| OffsetFunction` | `0` | Distance between the anchor and the popup in pixels, or a function of the anchor and positioner sizes, side and alignment. |
| alignOffset | `number \| OffsetFunction` | `0` | Offset along the alignment axis in pixels, or a function like `sideOffset`. |
| collisionBoundary | `Boundary` | `'clipping-ancestors'` | The area the popup is confined to. |
| collisionPadding | `Padding` | `5` | Space to keep from the edge of the collision boundary. |
| arrowPadding | `number` | `5` | Minimum distance between the arrow and the edges of the popup. |
| sticky | `boolean` | `false` | Whether the popup stays in the viewport after the anchor scrolls out of view. |
| disableAnchorTracking | `boolean` | `false` | Whether the popup stops following layout shifts of its anchor. |
| collisionAvoidance | `CollisionAvoidance` | - | How the popup avoids collisions. Dropdowns flip on the side axis and shift on the other. |
| render | `Snippet<[props: HTMLAttributes
, state: ComboboxPositionerState, children: Snippet \| undefined]>` | - | |
| Attribute | Description |
| -------------------- | --------------------------------------------------------------------- |
| `data-open` | Present when the popup is open. |
| `data-closed` | Present when the popup is closed. |
| `data-anchor-hidden` | Present when the anchor is hidden. |
| `data-align` | Indicates how the popup is aligned relative to specified side. |
| `data-empty` | Present when the items list is empty. |
| `data-side` | Indicates which side the popup is positioned relative to the trigger. |
| CSS variable | Description |
| -------------------- | -------------------------------------------------------------------------------------- |
| `--anchor-height` | The anchor's height. |
| `--anchor-width` | The anchor's width. |
| `--available-height` | The available height between the trigger and the edge of the viewport. |
| `--available-width` | The available width between the trigger and the edge of the viewport. |
| `--transform-origin` | The coordinates that this element is anchored to. Used for animations and transitions. |
### Popup
A container for the list. Renders a `` element.
**Autocomplete.Popup Props:**
| Prop | Type | Default | Description |
| :--- | :--- | :------ | :---------- |
| initialFocus | `ComboboxFocusTarget` | - | The element to focus when the popup opens. With the input inside the popup, the default focuses the input, or the popup on touch. |
| finalFocus | `ComboboxFocusTarget` | - | The element to focus when the popup closes. With the input inside the popup, the default focuses the trigger. Otherwise focus stays where it is. |
| render | `Snippet<[props: HTMLAttributes
, state: ComboboxPopupState, children: Snippet \| undefined]>` | - | |
| Attribute | Description |
| --------------------- | --------------------------------------------------------------------- |
| `data-open` | Present when the popup is open. |
| `data-closed` | Present when the popup is closed. |
| `data-anchor-hidden` | Present when the anchor is hidden. |
| `data-align` | Indicates how the popup is aligned relative to specified side. |
| `data-empty` | Present when the items list is empty. |
| `data-side` | Indicates which side the popup is positioned relative to the trigger. |
| `data-starting-style` | Present when the popup begins animating in. |
| `data-ending-style` | Present when the popup is animating out. |
### Arrow
Displays an element positioned against the anchor. Renders a `` element.
**Autocomplete.Arrow Props:**
| Prop | Type | Default | Description |
| :--- | :--- | :------ | :---------- |
| render | `Snippet<[props: HTMLAttributes
, state: ComboboxArrowState, children: Snippet \| undefined]>` | - | |
| Attribute | Description |
| ----------------- | --------------------------------------------------------------------- |
| `data-open` | Present when the popup is open. |
| `data-closed` | Present when the popup is closed. |
| `data-uncentered` | Present when the arrow is uncentered. |
| `data-align` | Indicates how the popup is aligned relative to specified side. |
| `data-side` | Indicates which side the popup is positioned relative to the trigger. |
### Status
Announces status messages, such as a loading state, politely to screen readers. Keep it mounted and change its children, so screen readers announce the change. Renders a `` element.
**Autocomplete.Status Props:**
| Prop | Type | Default | Description |
| :--- | :--- | :------ | :---------- |
| render | `Snippet<[props: HTMLAttributes
, state: ComboboxStatusState, children: Snippet \| undefined]>` | - | |
### Empty
Renders its children only while the filtered list is empty, and announces them politely to screen readers. Requires the `items` prop on the root. Keep it mounted: hide its children, not the element. Renders a `` element.
**Autocomplete.Empty Props:**
| Prop | Type | Default | Description |
| :--- | :--- | :------ | :---------- |
| children | `Snippet` | - | Shown while the filtered list has no items. |
| render | `Snippet<[props: HTMLAttributes
, state: ComboboxEmptyState, children: Snippet \| undefined]>` | - | |
### Collection
Renders its snippet for each filtered item, or each item of the surrounding group. Renders no element of its own.
**Autocomplete.Collection Props:**
| Prop | Type | Default | Description |
| :--- | :--- | :------ | :---------- |
| children | `Snippet<[item: never, index: number]>` | - | Rendered for each filtered item, or each item of the surrounding `Combobox.Group`. |
### Row
A row of items in a grid list. Renders a `` element.
**Autocomplete.Row Props:**
| Prop | Type | Default | Description |
| :--- | :--- | :------ | :---------- |
| render | `Snippet<[props: HTMLAttributes
, state: ComboboxRowState, children: Snippet \| undefined]>` | - | |
### Item
An item in the list. Pressing it fills the input with its text. Renders a `` element.
**Autocomplete.Item Props:**
| Prop | Type | Default | Description |
| :--- | :--- | :------ | :---------- |
| disabled | `boolean \| null` | `false` | Whether the item ignores user interaction. |
| value | `unknown` | `null` | The value this item selects. |
| nativeButton | `boolean` | `false` | Whether the host is a native `
`. |
| index | `number` | - | The item's position in the list. Without it the item takes its position from the document order, or from `items` when the root is `virtualized`. |
| render | `Snippet<[props: HTMLAttributes, state: AutocompleteItemState, children: Snippet \| undefined]>` | - | |
| Attribute | Description |
| ------------------ | ------------------------------------- |
| `data-highlighted` | Present when the item is highlighted. |
| `data-disabled` | Present when the item is disabled. |
### Group
Groups related items with their label. Renders a `` element.
**Autocomplete.Group Props:**
| Prop | Type | Default | Description |
| :--- | :--- | :------ | :---------- |
| items | `readonly unknown[]` | - | The group's items, which a `Combobox.Collection` inside renders. |
| render | `Snippet<[props: HTMLAttributes
, state: ComboboxGroupState, children: Snippet \| undefined]>` | - | |
### GroupLabel
The label of a group. Renders a `` element.
**Autocomplete.GroupLabel Props:**
| Prop | Type | Default | Description |
| :--- | :--- | :------ | :---------- |
| render | `Snippet<[props: HTMLAttributes
, state: ComboboxGroupLabelState, children: Snippet \| undefined]>` | - | |
### Separator
A visual separator between items or groups. Renders a `` element.
**Autocomplete.Separator Props:**
| Prop | Type | Default | Description |
| :--- | :--- | :------ | :---------- |
| orientation | `"horizontal" \| "vertical"` | `'horizontal'` | The orientation of the separator. |
| render | `Snippet<[props: HTMLAttributes
, state: SeparatorState, children: Snippet \| undefined]>` | - | Replace the default ``. Spread `props` onto the host element. |
| Attribute | Description |
| ------------------ | ------------------------------------------- |
| `data-orientation` | Indicates the orientation of the separator. |
## useFilter
Matches items against a query using `Intl.Collator` for robust string matching.
This is a plain function, not a hook: call it in a `$derived` when its options change. It is used when externally filtering items.
| Parameter | Type | Default | Description |
| --------- | --------------------------- | ------- | ----------- |
| options? | `AutocompleteFilterOptions` | `{}` | - |
Returns an `AutocompleteFilter`:
```ts
type AutocompleteFilter = {
contains:
- (item: Item, query: string, itemToString?: (item: Item) => string) => boolean;
startsWith:
- (item: Item, query: string, itemToString?: (item: Item) => string) => boolean;
endsWith:
- (item: Item, query: string, itemToString?: (item: Item) => string) => boolean;
};
```
## useFilteredItems
Returns the internally filtered items when called inside `
`.
Call it while a part initializes. It returns an object whose `current` is the filtered items. Treat the result as read-only: it is internal state and may be a shared frozen array.
```ts
type ReturnValue = { readonly current: readonly T[] };
```