Select
Select new
Section titled “Select new”import { useSelect } from "@katanakit/ui";
const select = useSelect({ label: "Country", name: "country", options: [ { value: "es", label: "Spain" }, { value: "ar", label: "Argentina" }, ],});
document.body.append(select.root);Built on the WAI-ARIA select-only combobox pattern.
Why aria-activedescendant, not roving tabindex
Section titled “Why aria-activedescendant, not roving tabindex”Contrast Tabs, which uses roving tabindex. The difference is
lifetime, not preference:
- A tablist is permanently in the DOM, so its children can carry real
tabindexvalues and the browser’s tab order can visit them. - A listbox is virtual — it only exists while open. There is no stable element for the tab order to visit.
So focus stays on the button at all times, and the active option is addressed by
id with aria-activedescendant. A screen reader still announces each option as
the arrows move, and closing the list does not have to move focus back from
somewhere it never left.
::: warning label is not optional in practice
A role="combobox" with no accessible name is announced as just “combo box”. The
user has no idea what they are being asked to choose. Always pass one.
:::
| Key | Action |
|---|---|
| ↓ / ↑ | Open, then move through enabled options. |
| Home / End | First / last enabled option, while open. |
| Enter / Space | Open; commit when already open. |
| Esc | Close without committing — selection is restored. |
| Tab | Close without committing, and move on. |
| Type a letter | Typeahead, jumping to the matching option. |
Disabled options are skipped in both directions and cannot be chosen.
Committing versus browsing
Section titled “Committing versus browsing”While the list is open, the active row and the selection are different things. The arrows move the active row; nothing is committed until Enter, Space or a click. Esc and Tab both discard the active row and leave the selection where it was.
That distinction matters on long lists: a user can scan with the arrows without changing anything.
Typeahead
Section titled “Typeahead”Typing jumps to the first option whose label starts with what you typed. The
buffer holds for 500 ms, so a then r finds “Argentina”, and a mistyped prefix
leaves you where you were rather than resetting.
Form participation
Section titled “Form participation”Pass name and the component also renders a hidden <input>, so the value joins
a normal form submission. Without it the component is presentational and the
caller owns the value.
Options
Section titled “Options”| Option | Type | Default | Notes |
|---|---|---|---|
options |
SelectOption[] |
— | The choices, in order. |
label |
string |
— | Accessible name. Always set one. |
value |
string |
first enabled | Initially selected value. |
placeholder |
string |
"Select…" |
Shown when nothing is selected. |
disabled |
boolean |
false |
Disables the whole control. |
name |
string |
— | Renders a hidden input so the value joins a form. |
onChange |
(value: string) => void |
— | Called with the newly selected value. |
The returned elements
Section titled “The returned elements”const { root, button, list, options, input, getValue, setOpen } = useSelect({ label, options });
document.body.append(root);getValue(); // "es" | undefinedsetOpen(true);useSelect needs a DOM. selectClass() is pure and safe on the server.