---
path: /docs/combobox/
experimental: true
---
# Combobox
**This is experimental** and may introduce **breaking changes** or be **removed altogether** in patch and minor versions without notice. Learn more in [Experimental features](/docs/experimental/).
Accessible `Combobox` component. It follows the [WAI-ARIA Combobox Pattern](https://www.w3.org/TR/wai-aria-practices/#combobox).
## Installation
```sh
npm install reakit
```
Learn more in [Get started](/docs/get-started/).
## Usage
```jsx
import {
unstable_useComboboxState as useComboboxState,
unstable_Combobox as Combobox,
unstable_ComboboxPopover as ComboboxPopover,
unstable_ComboboxOption as ComboboxOption,
} from "reakit/Combobox";
function Example() {
const combobox = useComboboxState();
return (
<>
);
}
```
## Accessibility
- `Combobox` has role `combobox`.
- `ComboboxPopover` has role `listbox` by default.
- `ComboboxOption` has role `option`.
- When focus is on the combobox input:
- Esc closes the combobox popover if it's visible.
- ↑ and ↓ opens the combobox popover.
- ↓ moves focus to the first combobox option if the combobox popover is visible.
- ↑ moves focus to the last combobox option if the combobox popover is visible.
- PageUp moves focus to the first combobox option.
- PageDown moves focus to the last combobox option.
- When focus is on a combobox option:
- If the combobox option has a `value` prop, Enter updates the combobox input value with the option value and closes the combobox popover.
- Esc closes the combobox popover and revert the combobox input to the original value.
- ↓ moves focus to the next option.
- ↑ moves focus to the previous option.
- PageUp moves focus to the first option.
- PageDown moves focus to the last option.
Learn more in [Accessibility](/docs/accessibility/).
## Props
### `useComboboxGridState`
- **`baseId`**
string
ID that will serve as a base for all the items IDs.
- **`visible`**
boolean
Whether it's visible or not.
- **`animated`**
number | boolean
If `true`, `animating` will be set to `true` when `visible` is updated.
It'll wait for `stopAnimation` to be called or a CSS transition ends.
If `animated` is set to a `number`, `stopAnimation` will be called only
after the same number of milliseconds have passed.
- **`modal`**
boolean
Toggles Dialog's `modal` state.
- Non-modal: `preventBodyScroll` doesn't work and focus is free.
- Modal: `preventBodyScroll` is automatically enabled, focus is
trapped within the dialog and the dialog is rendered within a `Portal`
by default.
- **`placement`**
"auto-start" | "auto" | "auto-end" | "top-start...
Actual `placement`.
- **`unstable_fixed`** ⚠️
boolean | undefined
Whether or not the popover should have `position` set to `fixed`.
- **`unstable_flip`** ⚠️
boolean | undefined
Flip the popover's placement when it starts to overlap its reference
element.
- **`unstable_offset`** ⚠️
[string | number, string | number] | undefined
Offset between the reference and the popover: [main axis, alt axis]. Should not be combined with `gutter`.
- **`gutter`**
number | undefined
Offset between the reference and the popover on the main axis. Should not be combined with `unstable_offset`.
- **`unstable_preventOverflow`** ⚠️
boolean | undefined
Prevents popover from being positioned outside the boundary.
- **`rtl`**
boolean
Determines how `next` and `previous` functions will behave. If `rtl` is
set to `true`, they will be inverted. This only affects the composite
widget behavior. You still need to set `dir="rtl"` on HTML/CSS.
- **`orientation`**
"horizontal" | "vertical" | undefined
Defines the orientation of the composite widget. If the composite has a
single row or column (one-dimensional), the `orientation` value determines
which arrow keys can be used to move focus:
- `undefined`: all arrow keys work.
- `horizontal`: only left and right arrow keys work.
- `vertical`: only up and down arrow keys work.
It doesn't have any effect on two-dimensional composites.
- **`currentId`**
string | null | undefined
The current focused item `id`.
- `undefined` will automatically focus the first enabled composite item.
- `null` will focus the base composite element and users will be able to
navigate out of it using arrow keys.
- If `currentId` is initially set to `null`, the base composite element
itself will have focus and users will be able to navigate to it using
arrow keys.
- **`loop`**
boolean | "horizontal" | "vertical"
On one-dimensional composites:
- `true` loops from the last item to the first item and vice-versa.
- `horizontal` loops only if `orientation` is `horizontal` or not set.
- `vertical` loops only if `orientation` is `vertical` or not set.
- If `currentId` is initially set to `null`, the composite element will
be focused in between the last and first items.
On two-dimensional composites:
- `true` loops from the last row/column item to the first item in the
same row/column and vice-versa. If it's the last item in the last row, it
moves to the first item in the first row and vice-versa.
- `horizontal` loops only from the last row item to the first item in
the same row.
- `vertical` loops only from the last column item to the first item in
the column row.
- If `currentId` is initially set to `null`, vertical loop will have no
effect as moving down from the last row or up from the first row will
focus the composite element.
- If `wrap` matches the value of `loop`, it'll wrap between the last
item in the last row or column and the first item in the first row or
column and vice-versa.
- **`wrap`**
boolean | "horizontal" | "vertical"
**Has effect only on two-dimensional composites**. If enabled, moving to
the next item from the last one in a row or column will focus the first
item in the next row or column and vice-versa.
- `true` wraps between rows and columns.
- `horizontal` wraps only between rows.
- `vertical` wraps only between columns.
- If `loop` matches the value of `wrap`, it'll wrap between the last
item in the last row or column and the first item in the first row or
column and vice-versa.
- **`shift`**
boolean
**Has effect only on two-dimensional composites**. If enabled, moving up
or down when there's no next item or the next item is disabled will shift
to the item right before it.
- **`inputValue`**
string
Combobox input value that will be used to filter `values` and populate
the `matches` property.
- **`minValueLength`**
number
How many characters are needed for opening the combobox popover and
populating `matches` with filtered values.
- **`values`**
string[]
Values that will be used to produce `matches`.
- **`limit`**
number | false
Maximum number of `matches`. If it's set to `false`, there will be no
limit.
- **`list`**
boolean
Determines how the combobox options behave: dynamically or statically.
By default, it's `true` if `values` are provided. Otherwise, it's `false`:
- If it's `true` and `values` are provided, then they will be
automatically filtered based on `inputValue` and will populate `matches`.
- If it's `true` and `values` aren't provided, this means that you'll
provide and filter values by yourself. `matches` will be empty.
- If it's `false` and `values` are provided, then they won't be
automatically filtered and `matches` will be the same as `values`.
- **`inline`**
boolean
Determines whether focusing on an option will temporarily change the value
of the combobox. If it's `true`, focusing on an option will temporarily
change the combobox value to the option's value.
- **`autoSelect`**
boolean
Determines whether the first option will be automatically selected. When
it's set to `true`, the exact behavior will depend on the value of
`inline`:
- If `inline` is `true`, the first option is automatically focused when
the combobox popover opens and the input value changes to reflect this.
The inline completion string will be highlighted and will have a selected
state.
- If `inline` is `false`, the first option is automatically focused when
the combobox popover opens, but the input value remains the same.
- **`columns`**
number
Number of columns by which `values` will be splitted to generate the
`matches` 2D array.
### `useComboboxListGridState`
- **`baseId`**
string
ID that will serve as a base for all the items IDs.
- **`rtl`**
boolean
Determines how `next` and `previous` functions will behave. If `rtl` is
set to `true`, they will be inverted. This only affects the composite
widget behavior. You still need to set `dir="rtl"` on HTML/CSS.
- **`orientation`**
"horizontal" | "vertical" | undefined
Defines the orientation of the composite widget. If the composite has a
single row or column (one-dimensional), the `orientation` value determines
which arrow keys can be used to move focus:
- `undefined`: all arrow keys work.
- `horizontal`: only left and right arrow keys work.
- `vertical`: only up and down arrow keys work.
It doesn't have any effect on two-dimensional composites.
- **`currentId`**
string | null | undefined
The current focused item `id`.
- `undefined` will automatically focus the first enabled composite item.
- `null` will focus the base composite element and users will be able to
navigate out of it using arrow keys.
- If `currentId` is initially set to `null`, the base composite element
itself will have focus and users will be able to navigate to it using
arrow keys.
- **`loop`**
boolean | "horizontal" | "vertical"
On one-dimensional composites:
- `true` loops from the last item to the first item and vice-versa.
- `horizontal` loops only if `orientation` is `horizontal` or not set.
- `vertical` loops only if `orientation` is `vertical` or not set.
- If `currentId` is initially set to `null`, the composite element will
be focused in between the last and first items.
On two-dimensional composites:
- `true` loops from the last row/column item to the first item in the
same row/column and vice-versa. If it's the last item in the last row, it
moves to the first item in the first row and vice-versa.
- `horizontal` loops only from the last row item to the first item in
the same row.
- `vertical` loops only from the last column item to the first item in
the column row.
- If `currentId` is initially set to `null`, vertical loop will have no
effect as moving down from the last row or up from the first row will
focus the composite element.
- If `wrap` matches the value of `loop`, it'll wrap between the last
item in the last row or column and the first item in the first row or
column and vice-versa.
- **`wrap`**
boolean | "horizontal" | "vertical"
**Has effect only on two-dimensional composites**. If enabled, moving to
the next item from the last one in a row or column will focus the first
item in the next row or column and vice-versa.
- `true` wraps between rows and columns.
- `horizontal` wraps only between rows.
- `vertical` wraps only between columns.
- If `loop` matches the value of `wrap`, it'll wrap between the last
item in the last row or column and the first item in the first row or
column and vice-versa.
- **`shift`**
boolean
**Has effect only on two-dimensional composites**. If enabled, moving up
or down when there's no next item or the next item is disabled will shift
to the item right before it.
- **`inputValue`**
string
Combobox input value that will be used to filter `values` and populate
the `matches` property.
- **`minValueLength`**
number
How many characters are needed for opening the combobox popover and
populating `matches` with filtered values.
- **`values`**
string[]
Values that will be used to produce `matches`.
- **`limit`**
number | false
Maximum number of `matches`. If it's set to `false`, there will be no
limit.
- **`list`**
boolean
Determines how the combobox options behave: dynamically or statically.
By default, it's `true` if `values` are provided. Otherwise, it's `false`:
- If it's `true` and `values` are provided, then they will be
automatically filtered based on `inputValue` and will populate `matches`.
- If it's `true` and `values` aren't provided, this means that you'll
provide and filter values by yourself. `matches` will be empty.
- If it's `false` and `values` are provided, then they won't be
automatically filtered and `matches` will be the same as `values`.
- **`inline`**
boolean
Determines whether focusing on an option will temporarily change the value
of the combobox. If it's `true`, focusing on an option will temporarily
change the combobox value to the option's value.
- **`autoSelect`**
boolean
Determines whether the first option will be automatically selected. When
it's set to `true`, the exact behavior will depend on the value of
`inline`:
- If `inline` is `true`, the first option is automatically focused when
the combobox popover opens and the input value changes to reflect this.
The inline completion string will be highlighted and will have a selected
state.
- If `inline` is `false`, the first option is automatically focused when
the combobox popover opens, but the input value remains the same.
- **`columns`**
number
Number of columns by which `values` will be splitted to generate the
`matches` 2D array.
### `useComboboxListState`
- **`baseId`**
string
ID that will serve as a base for all the items IDs.
- **`rtl`**
boolean
Determines how `next` and `previous` functions will behave. If `rtl` is
set to `true`, they will be inverted. This only affects the composite
widget behavior. You still need to set `dir="rtl"` on HTML/CSS.
- **`orientation`**
"horizontal" | "vertical" | undefined
Defines the orientation of the composite widget. If the composite has a
single row or column (one-dimensional), the `orientation` value determines
which arrow keys can be used to move focus:
- `undefined`: all arrow keys work.
- `horizontal`: only left and right arrow keys work.
- `vertical`: only up and down arrow keys work.
It doesn't have any effect on two-dimensional composites.
- **`currentId`**
string | null | undefined
The current focused item `id`.
- `undefined` will automatically focus the first enabled composite item.
- `null` will focus the base composite element and users will be able to
navigate out of it using arrow keys.
- If `currentId` is initially set to `null`, the base composite element
itself will have focus and users will be able to navigate to it using
arrow keys.
- **`loop`**
boolean | "horizontal" | "vertical"
On one-dimensional composites:
- `true` loops from the last item to the first item and vice-versa.
- `horizontal` loops only if `orientation` is `horizontal` or not set.
- `vertical` loops only if `orientation` is `vertical` or not set.
- If `currentId` is initially set to `null`, the composite element will
be focused in between the last and first items.
On two-dimensional composites:
- `true` loops from the last row/column item to the first item in the
same row/column and vice-versa. If it's the last item in the last row, it
moves to the first item in the first row and vice-versa.
- `horizontal` loops only from the last row item to the first item in
the same row.
- `vertical` loops only from the last column item to the first item in
the column row.
- If `currentId` is initially set to `null`, vertical loop will have no
effect as moving down from the last row or up from the first row will
focus the composite element.
- If `wrap` matches the value of `loop`, it'll wrap between the last
item in the last row or column and the first item in the first row or
column and vice-versa.
- **`wrap`**
boolean | "horizontal" | "vertical"
**Has effect only on two-dimensional composites**. If enabled, moving to
the next item from the last one in a row or column will focus the first
item in the next row or column and vice-versa.
- `true` wraps between rows and columns.
- `horizontal` wraps only between rows.
- `vertical` wraps only between columns.
- If `loop` matches the value of `wrap`, it'll wrap between the last
item in the last row or column and the first item in the first row or
column and vice-versa.
- **`shift`**
boolean
**Has effect only on two-dimensional composites**. If enabled, moving up
or down when there's no next item or the next item is disabled will shift
to the item right before it.
- **`inputValue`**
string
Combobox input value that will be used to filter `values` and populate
the `matches` property.
- **`minValueLength`**
number
How many characters are needed for opening the combobox popover and
populating `matches` with filtered values.
- **`values`**
string[]
Values that will be used to produce `matches`.
- **`limit`**
number | false
Maximum number of `matches`. If it's set to `false`, there will be no
limit.
- **`list`**
boolean
Determines how the combobox options behave: dynamically or statically.
By default, it's `true` if `values` are provided. Otherwise, it's `false`:
- If it's `true` and `values` are provided, then they will be
automatically filtered based on `inputValue` and will populate `matches`.
- If it's `true` and `values` aren't provided, this means that you'll
provide and filter values by yourself. `matches` will be empty.
- If it's `false` and `values` are provided, then they won't be
automatically filtered and `matches` will be the same as `values`.
- **`inline`**
boolean
Determines whether focusing on an option will temporarily change the value
of the combobox. If it's `true`, focusing on an option will temporarily
change the combobox value to the option's value.
- **`autoSelect`**
boolean
Determines whether the first option will be automatically selected. When
it's set to `true`, the exact behavior will depend on the value of
`inline`:
- If `inline` is `true`, the first option is automatically focused when
the combobox popover opens and the input value changes to reflect this.
The inline completion string will be highlighted and will have a selected
state.
- If `inline` is `false`, the first option is automatically focused when
the combobox popover opens, but the input value remains the same.
### `useComboboxState`
- **`baseId`**
string
ID that will serve as a base for all the items IDs.
- **`visible`**
boolean
Whether it's visible or not.
- **`animated`**
number | boolean
If `true`, `animating` will be set to `true` when `visible` is updated.
It'll wait for `stopAnimation` to be called or a CSS transition ends.
If `animated` is set to a `number`, `stopAnimation` will be called only
after the same number of milliseconds have passed.
- **`modal`**
boolean
Toggles Dialog's `modal` state.
- Non-modal: `preventBodyScroll` doesn't work and focus is free.
- Modal: `preventBodyScroll` is automatically enabled, focus is
trapped within the dialog and the dialog is rendered within a `Portal`
by default.
- **`placement`**
"auto-start" | "auto" | "auto-end" | "top-start...
Actual `placement`.
- **`unstable_fixed`** ⚠️
boolean | undefined
Whether or not the popover should have `position` set to `fixed`.
- **`unstable_flip`** ⚠️
boolean | undefined
Flip the popover's placement when it starts to overlap its reference
element.
- **`unstable_offset`** ⚠️
[string | number, string | number] | undefined
Offset between the reference and the popover: [main axis, alt axis]. Should not be combined with `gutter`.
- **`gutter`**
number | undefined
Offset between the reference and the popover on the main axis. Should not be combined with `unstable_offset`.
- **`unstable_preventOverflow`** ⚠️
boolean | undefined
Prevents popover from being positioned outside the boundary.
- **`rtl`**
boolean
Determines how `next` and `previous` functions will behave. If `rtl` is
set to `true`, they will be inverted. This only affects the composite
widget behavior. You still need to set `dir="rtl"` on HTML/CSS.
- **`orientation`**
"horizontal" | "vertical" | undefined
Defines the orientation of the composite widget. If the composite has a
single row or column (one-dimensional), the `orientation` value determines
which arrow keys can be used to move focus:
- `undefined`: all arrow keys work.
- `horizontal`: only left and right arrow keys work.
- `vertical`: only up and down arrow keys work.
It doesn't have any effect on two-dimensional composites.
- **`currentId`**
string | null | undefined
The current focused item `id`.
- `undefined` will automatically focus the first enabled composite item.
- `null` will focus the base composite element and users will be able to
navigate out of it using arrow keys.
- If `currentId` is initially set to `null`, the base composite element
itself will have focus and users will be able to navigate to it using
arrow keys.
- **`loop`**
boolean | "horizontal" | "vertical"
On one-dimensional composites:
- `true` loops from the last item to the first item and vice-versa.
- `horizontal` loops only if `orientation` is `horizontal` or not set.
- `vertical` loops only if `orientation` is `vertical` or not set.
- If `currentId` is initially set to `null`, the composite element will
be focused in between the last and first items.
On two-dimensional composites:
- `true` loops from the last row/column item to the first item in the
same row/column and vice-versa. If it's the last item in the last row, it
moves to the first item in the first row and vice-versa.
- `horizontal` loops only from the last row item to the first item in
the same row.
- `vertical` loops only from the last column item to the first item in
the column row.
- If `currentId` is initially set to `null`, vertical loop will have no
effect as moving down from the last row or up from the first row will
focus the composite element.
- If `wrap` matches the value of `loop`, it'll wrap between the last
item in the last row or column and the first item in the first row or
column and vice-versa.
- **`wrap`**
boolean | "horizontal" | "vertical"
**Has effect only on two-dimensional composites**. If enabled, moving to
the next item from the last one in a row or column will focus the first
item in the next row or column and vice-versa.
- `true` wraps between rows and columns.
- `horizontal` wraps only between rows.
- `vertical` wraps only between columns.
- If `loop` matches the value of `wrap`, it'll wrap between the last
item in the last row or column and the first item in the first row or
column and vice-versa.
- **`shift`**
boolean
**Has effect only on two-dimensional composites**. If enabled, moving up
or down when there's no next item or the next item is disabled will shift
to the item right before it.
- **`inputValue`**
string
Combobox input value that will be used to filter `values` and populate
the `matches` property.
- **`minValueLength`**
number
How many characters are needed for opening the combobox popover and
populating `matches` with filtered values.
- **`values`**
string[]
Values that will be used to produce `matches`.
- **`limit`**
number | false
Maximum number of `matches`. If it's set to `false`, there will be no
limit.
- **`list`**
boolean
Determines how the combobox options behave: dynamically or statically.
By default, it's `true` if `values` are provided. Otherwise, it's `false`:
- If it's `true` and `values` are provided, then they will be
automatically filtered based on `inputValue` and will populate `matches`.
- If it's `true` and `values` aren't provided, this means that you'll
provide and filter values by yourself. `matches` will be empty.
- If it's `false` and `values` are provided, then they won't be
automatically filtered and `matches` will be the same as `values`.
- **`inline`**
boolean
Determines whether focusing on an option will temporarily change the value
of the combobox. If it's `true`, focusing on an option will temporarily
change the combobox value to the option's value.
- **`autoSelect`**
boolean
Determines whether the first option will be automatically selected. When
it's set to `true`, the exact behavior will depend on the value of
`inline`:
- If `inline` is `true`, the first option is automatically focused when
the combobox popover opens and the input value changes to reflect this.
The inline completion string will be highlighted and will have a selected
state.
- If `inline` is `false`, the first option is automatically focused when
the combobox popover opens, but the input value remains the same.
### `Combobox`
- **`disabled`**
boolean | undefined
Same as the HTML attribute.
- **`focusable`**
boolean | undefined
When an element is `disabled`, it may still be `focusable`. It works
similarly to `readOnly` on form elements. In this case, only
`aria-disabled` will be set.
- **`hideOnEsc`**
boolean | undefined
When enabled, user can hide the combobox popover by pressing
Esc while focusing on the combobox input.
24 state props
> These props are returned by the state hook. You can spread them into this component (`{...state}`) or pass them separately. You can also provide these props from your own state logic.
- **`baseId`**
string
ID that will serve as a base for all the items IDs.
- **`unstable_virtual`** ⚠️
boolean
If enabled, the composite element will act as an
[aria-activedescendant](https://www.w3.org/TR/wai-aria-practices-1.1/#kbd_focus_activedescendant)
container instead of
[roving tabindex](https://www.w3.org/TR/wai-aria-practices/#kbd_roving_tabindex).
DOM focus will remain on the composite while its items receive virtual focus.
- **`orientation`**
"horizontal" | "vertical" | undefined
Defines the orientation of the composite widget. If the composite has a
single row or column (one-dimensional), the `orientation` value determines
which arrow keys can be used to move focus:
- `undefined`: all arrow keys work.
- `horizontal`: only left and right arrow keys work.
- `vertical`: only up and down arrow keys work.
It doesn't have any effect on two-dimensional composites.
- **`currentId`**
string | null | undefined
The current focused item `id`.
- `undefined` will automatically focus the first enabled composite item.
- `null` will focus the base composite element and users will be able to
navigate out of it using arrow keys.
- If `currentId` is initially set to `null`, the base composite element
itself will have focus and users will be able to navigate to it using
arrow keys.
- **`wrap`**
boolean | "horizontal" | "vertical"
**Has effect only on two-dimensional composites**. If enabled, moving to
the next item from the last one in a row or column will focus the first
item in the next row or column and vice-versa.
- `true` wraps between rows and columns.
- `horizontal` wraps only between rows.
- `vertical` wraps only between columns.
- If `loop` matches the value of `wrap`, it'll wrap between the last
item in the last row or column and the first item in the first row or
column and vice-versa.
- **`groups`**
Group[]
Lists all the composite groups with their `id` and DOM `ref`. This state
is automatically updated when `registerGroup` and `unregisterGroup` are
called.
- **`unstable_moves`** ⚠️
number
Stores the number of moves that have been performed by calling `move`,
`next`, `previous`, `up`, `down`, `first` or `last`.
- **`items`**
Item[]
Lists all the composite items with their `id`, DOM `ref`, `disabled` state
and `groupId` if any. This state is automatically updated when
`registerItem` and `unregisterItem` are called.
- **`move`**
(id: string | null) => void
Moves focus to a given item ID.
- **`first`**
() => void
Moves focus to the first item.
- **`last`**
() => void
Moves focus to the last item.
- **`setCurrentId`**
(value: SetStateAction<string | null | undefine...
Sets `currentId`. This is different from `composite.move` as this only
updates the `currentId` state without moving focus. When the composite
widget gets focused by the user, the item referred by the `currentId`
state will get focus.
- **`visible`**
boolean
Whether it's visible or not.
- **`minValueLength`**
number
How many characters are needed for opening the combobox popover and
populating `matches` with filtered values.
- **`list`**
boolean
Determines how the combobox options behave: dynamically or statically.
By default, it's `true` if `values` are provided. Otherwise, it's `false`:
- If it's `true` and `values` are provided, then they will be
automatically filtered based on `inputValue` and will populate `matches`.
- If it's `true` and `values` aren't provided, this means that you'll
provide and filter values by yourself. `matches` will be empty.
- If it's `false` and `values` are provided, then they won't be
automatically filtered and `matches` will be the same as `values`.
- **`inline`**
boolean
Determines whether focusing on an option will temporarily change the value
of the combobox. If it's `true`, focusing on an option will temporarily
change the combobox value to the option's value.
- **`autoSelect`**
boolean
Determines whether the first option will be automatically selected. When
it's set to `true`, the exact behavior will depend on the value of
`inline`:
- If `inline` is `true`, the first option is automatically focused when
the combobox popover opens and the input value changes to reflect this.
The inline completion string will be highlighted and will have a selected
state.
- If `inline` is `false`, the first option is automatically focused when
the combobox popover opens, but the input value remains the same.
- **`menuRole`**
"listbox" | "tree" | "grid" | "dialog"
Indicates the type of the suggestions popup.
- **`currentValue`**
string | undefined
Value of the item that is currently selected.
- **`show`**
() => void
Changes the `visible` state to `true`
- **`hide`**
() => void
Changes the `visible` state to `false`
- **`unstable_referenceRef`** ⚠️
RefObject<HTMLElement | null>
The reference element.
- **`inputValue`**
string
Combobox input value that will be used to filter `values` and populate
the `matches` property.
- **`setInputValue`**
(value: SetStateAction<string>) => void
Sets `inputValue`.
boolean | undefined
Same as the HTML attribute.
- **`focusable`**
boolean | undefined
When an element is `disabled`, it may still be `focusable`. It works
similarly to `readOnly` on form elements. In this case, only
`aria-disabled` will be set.
- **`id`**
string | undefined
Same as the HTML attribute.
- **`value`**
string | undefined
Item's value that will be used to fill input value and filter `matches`
based on the input value. You can omit this for items that perform
actions other than filling a form. For example, items may open a dialog.
20 state props
> These props are returned by the state hook. You can spread them into this component (`{...state}`) or pass them separately. You can also provide these props from your own state logic.
- **`baseId`**
string
ID that will serve as a base for all the items IDs.
- **`unstable_virtual`** ⚠️
boolean
If enabled, the composite element will act as an
[aria-activedescendant](https://www.w3.org/TR/wai-aria-practices-1.1/#kbd_focus_activedescendant)
container instead of
[roving tabindex](https://www.w3.org/TR/wai-aria-practices/#kbd_roving_tabindex).
DOM focus will remain on the composite while its items receive virtual focus.
- **`orientation`**
"horizontal" | "vertical" | undefined
Defines the orientation of the composite widget. If the composite has a
single row or column (one-dimensional), the `orientation` value determines
which arrow keys can be used to move focus:
- `undefined`: all arrow keys work.
- `horizontal`: only left and right arrow keys work.
- `vertical`: only up and down arrow keys work.
It doesn't have any effect on two-dimensional composites.
- **`unstable_moves`** ⚠️
number
Stores the number of moves that have been performed by calling `move`,
`next`, `previous`, `up`, `down`, `first` or `last`.
- **`currentId`**
string | null | undefined
The current focused item `id`.
- `undefined` will automatically focus the first enabled composite item.
- `null` will focus the base composite element and users will be able to
navigate out of it using arrow keys.
- If `currentId` is initially set to `null`, the base composite element
itself will have focus and users will be able to navigate to it using
arrow keys.
- **`items`**
Item[]
Lists all the composite items with their `id`, DOM `ref`, `disabled` state
and `groupId` if any. This state is automatically updated when
`registerItem` and `unregisterItem` are called.
- **`registerItem`**
(item: Item) => void
Registers a composite item.
- **`unregisterItem`**
(id: string) => void
Unregisters a composite item.
- **`next`**
(unstable_allTheWay?: boolean | undefined) => void
Moves focus to the next item.
- **`previous`**
(unstable_allTheWay?: boolean | undefined) => void
Moves focus to the previous item.
- **`up`**
(unstable_allTheWay?: boolean | undefined) => void
Moves focus to the item above.
- **`down`**
(unstable_allTheWay?: boolean | undefined) => void
Moves focus to the item below.
- **`first`**
() => void
Moves focus to the first item.
- **`last`**
() => void
Moves focus to the last item.
- **`setCurrentId`**
(value: SetStateAction<string | null | undefine...
Sets `currentId`. This is different from `composite.move` as this only
updates the `currentId` state without moving focus. When the composite
widget gets focused by the user, the item referred by the `currentId`
state will get focus.
- **`visible`**
boolean
Whether it's visible or not.
- **`inputValue`**
string
Combobox input value that will be used to filter `values` and populate
the `matches` property.
- **`currentValue`**
string | undefined
Value of the item that is currently selected.
- **`hide`**
() => void
Changes the `visible` state to `false`
- **`setInputValue`**
(value: SetStateAction<string>) => void
Sets `inputValue`.
string | undefined
Same as the HTML attribute.
6 state props
> These props are returned by the state hook. You can spread them into this component (`{...state}`) or pass them separately. You can also provide these props from your own state logic.
- **`baseId`**
string
ID that will serve as a base for all the items IDs.
- **`registerGroup`**
(group: Group) => void
Registers a composite group.
- **`unregisterGroup`**
(id: string) => void
Unregisters a composite group.
- **`currentId`**
string | null | undefined
The current focused item `id`.
- `undefined` will automatically focus the first enabled composite item.
- `null` will focus the base composite element and users will be able to
navigate out of it using arrow keys.
- If `currentId` is initially set to `null`, the base composite element
itself will have focus and users will be able to navigate to it using
arrow keys.
- **`items`**
Item[]
Lists all the composite items with their `id`, DOM `ref`, `disabled` state
and `groupId` if any. This state is automatically updated when
`registerItem` and `unregisterItem` are called.
- **`unstable_moves`** ⚠️
number
Stores the number of moves that have been performed by calling `move`,
`next`, `previous`, `up`, `down`, `first` or `last`.
boolean | undefined
Same as the HTML attribute.
- **`focusable`**
boolean | undefined
When an element is `disabled`, it may still be `focusable`. It works
similarly to `readOnly` on form elements. In this case, only
`aria-disabled` will be set.
- **`id`**
string | undefined
Same as the HTML attribute.
- **`value`**
string | undefined
Item's value that will be used to fill input value and filter `matches`
based on the input value. You can omit this for items that perform
actions other than filling a form. For example, items may open a dialog.
20 state props
> These props are returned by the state hook. You can spread them into this component (`{...state}`) or pass them separately. You can also provide these props from your own state logic.
- **`baseId`**
string
ID that will serve as a base for all the items IDs.
- **`unstable_virtual`** ⚠️
boolean
If enabled, the composite element will act as an
[aria-activedescendant](https://www.w3.org/TR/wai-aria-practices-1.1/#kbd_focus_activedescendant)
container instead of
[roving tabindex](https://www.w3.org/TR/wai-aria-practices/#kbd_roving_tabindex).
DOM focus will remain on the composite while its items receive virtual focus.
- **`orientation`**
"horizontal" | "vertical" | undefined
Defines the orientation of the composite widget. If the composite has a
single row or column (one-dimensional), the `orientation` value determines
which arrow keys can be used to move focus:
- `undefined`: all arrow keys work.
- `horizontal`: only left and right arrow keys work.
- `vertical`: only up and down arrow keys work.
It doesn't have any effect on two-dimensional composites.
- **`unstable_moves`** ⚠️
number
Stores the number of moves that have been performed by calling `move`,
`next`, `previous`, `up`, `down`, `first` or `last`.
- **`currentId`**
string | null | undefined
The current focused item `id`.
- `undefined` will automatically focus the first enabled composite item.
- `null` will focus the base composite element and users will be able to
navigate out of it using arrow keys.
- If `currentId` is initially set to `null`, the base composite element
itself will have focus and users will be able to navigate to it using
arrow keys.
- **`items`**
Item[]
Lists all the composite items with their `id`, DOM `ref`, `disabled` state
and `groupId` if any. This state is automatically updated when
`registerItem` and `unregisterItem` are called.
- **`registerItem`**
(item: Item) => void
Registers a composite item.
- **`unregisterItem`**
(id: string) => void
Unregisters a composite item.
- **`next`**
(unstable_allTheWay?: boolean | undefined) => void
Moves focus to the next item.
- **`previous`**
(unstable_allTheWay?: boolean | undefined) => void
Moves focus to the previous item.
- **`up`**
(unstable_allTheWay?: boolean | undefined) => void
Moves focus to the item above.
- **`down`**
(unstable_allTheWay?: boolean | undefined) => void
Moves focus to the item below.
- **`first`**
() => void
Moves focus to the first item.
- **`last`**
() => void
Moves focus to the last item.
- **`setCurrentId`**
(value: SetStateAction<string | null | undefine...
Sets `currentId`. This is different from `composite.move` as this only
updates the `currentId` state without moving focus. When the composite
widget gets focused by the user, the item referred by the `currentId`
state will get focus.
- **`visible`**
boolean
Whether it's visible or not.
- **`inputValue`**
string
Combobox input value that will be used to filter `values` and populate
the `matches` property.
- **`currentValue`**
string | undefined
Value of the item that is currently selected.
- **`hide`**
() => void
Changes the `visible` state to `false`
- **`setInputValue`**
(value: SetStateAction<string>) => void
Sets `inputValue`.
2 state props
> These props are returned by the state hook. You can spread them into this component (`{...state}`) or pass them separately. You can also provide these props from your own state logic.
- **`menuRole`**
"listbox" | "tree" | "grid" | "dialog"
Indicates the type of the suggestions popup.
- **`baseId`**
string
ID that will serve as a base for all the items IDs.
boolean | undefined
Same as the HTML attribute.
- **`focusable`**
boolean | undefined
When an element is `disabled`, it may still be `focusable`. It works
similarly to `readOnly` on form elements. In this case, only
`aria-disabled` will be set.
- **`id`**
string | undefined
Same as the HTML attribute.
- **`value`**
string | undefined
Item's value that will be used to fill input value and filter `matches`
based on the input value. You can omit this for items that perform
actions other than filling a form. For example, items may open a dialog.
20 state props
> These props are returned by the state hook. You can spread them into this component (`{...state}`) or pass them separately. You can also provide these props from your own state logic.
- **`baseId`**
string
ID that will serve as a base for all the items IDs.
- **`unstable_virtual`** ⚠️
boolean
If enabled, the composite element will act as an
[aria-activedescendant](https://www.w3.org/TR/wai-aria-practices-1.1/#kbd_focus_activedescendant)
container instead of
[roving tabindex](https://www.w3.org/TR/wai-aria-practices/#kbd_roving_tabindex).
DOM focus will remain on the composite while its items receive virtual focus.
- **`orientation`**
"horizontal" | "vertical" | undefined
Defines the orientation of the composite widget. If the composite has a
single row or column (one-dimensional), the `orientation` value determines
which arrow keys can be used to move focus:
- `undefined`: all arrow keys work.
- `horizontal`: only left and right arrow keys work.
- `vertical`: only up and down arrow keys work.
It doesn't have any effect on two-dimensional composites.
- **`unstable_moves`** ⚠️
number
Stores the number of moves that have been performed by calling `move`,
`next`, `previous`, `up`, `down`, `first` or `last`.
- **`currentId`**
string | null | undefined
The current focused item `id`.
- `undefined` will automatically focus the first enabled composite item.
- `null` will focus the base composite element and users will be able to
navigate out of it using arrow keys.
- If `currentId` is initially set to `null`, the base composite element
itself will have focus and users will be able to navigate to it using
arrow keys.
- **`items`**
Item[]
Lists all the composite items with their `id`, DOM `ref`, `disabled` state
and `groupId` if any. This state is automatically updated when
`registerItem` and `unregisterItem` are called.
- **`registerItem`**
(item: Item) => void
Registers a composite item.
- **`unregisterItem`**
(id: string) => void
Unregisters a composite item.
- **`next`**
(unstable_allTheWay?: boolean | undefined) => void
Moves focus to the next item.
- **`previous`**
(unstable_allTheWay?: boolean | undefined) => void
Moves focus to the previous item.
- **`up`**
(unstable_allTheWay?: boolean | undefined) => void
Moves focus to the item above.
- **`down`**
(unstable_allTheWay?: boolean | undefined) => void
Moves focus to the item below.
- **`first`**
() => void
Moves focus to the first item.
- **`last`**
() => void
Moves focus to the last item.
- **`setCurrentId`**
(value: SetStateAction<string | null | undefine...
Sets `currentId`. This is different from `composite.move` as this only
updates the `currentId` state without moving focus. When the composite
widget gets focused by the user, the item referred by the `currentId`
state will get focus.
- **`visible`**
boolean
Whether it's visible or not.
- **`inputValue`**
string
Combobox input value that will be used to filter `values` and populate
the `matches` property.
- **`currentValue`**
string | undefined
Value of the item that is currently selected.
- **`hide`**
() => void
Changes the `visible` state to `false`
- **`setInputValue`**
(value: SetStateAction<string>) => void
Sets `inputValue`.
boolean | undefined
When enabled, user can hide the dialog by pressing `Escape`.
- **`hideOnClickOutside`**
boolean | undefined
When enabled, user can hide the dialog by clicking outside it.
- **`preventBodyScroll`**
boolean | undefined
When enabled, user can't scroll on body when the dialog is visible.
This option doesn't work if the dialog isn't modal.
- **`unstable_initialFocusRef`** ⚠️
RefObject<HTMLElement> | undefined
The element that will be focused when the dialog shows.
When not set, the first tabbable element within the dialog will be used.
- **`unstable_finalFocusRef`** ⚠️
RefObject<HTMLElement> | undefined
The element that will be focused when the dialog hides.
When not set, the disclosure component will be used.
- **`unstable_orphan`** ⚠️
boolean | undefined
Whether or not the dialog should be a child of its parent.
Opening a nested orphan dialog will close its parent dialog if
`hideOnClickOutside` is set to `true` on the parent.
It will be set to `false` if `modal` is `false`.
9 state props
> These props are returned by the state hook. You can spread them into this component (`{...state}`) or pass them separately. You can also provide these props from your own state logic.
- **`menuRole`**
"listbox" | "tree" | "grid" | "dialog"
Indicates the type of the suggestions popup.
- **`baseId`**
string
ID that will serve as a base for all the items IDs.
- **`visible`**
boolean
Whether it's visible or not.
- **`animated`**
number | boolean
If `true`, `animating` will be set to `true` when `visible` is updated.
It'll wait for `stopAnimation` to be called or a CSS transition ends.
If `animated` is set to a `number`, `stopAnimation` will be called only
after the same number of milliseconds have passed.
- **`modal`**
boolean
Toggles Dialog's `modal` state.
- Non-modal: `preventBodyScroll` doesn't work and focus is free.
- Modal: `preventBodyScroll` is automatically enabled, focus is
trapped within the dialog and the dialog is rendered within a `Portal`
by default.
- **`hide`**
() => void
Changes the `visible` state to `false`
- **`animating`**
boolean
Whether it's animating or not.
- **`stopAnimation`**
() => void
Stops animation. It's called automatically if there's a CSS transition.
- **`unstable_referenceRef`** ⚠️
RefObject<HTMLElement | null>
The reference element.