# Build an Accessible React Combobox with React Aria (2026) A combobox is one of the hardest widgets to build by hand: it needs `role="combobox"`, `aria-expanded`, `aria-controls`, `aria-activedescendant`, and full keyboard support, wired together correctly. This guide builds one with **react-aria-components 1.19.0**, styles it with CSS, and proves it's accessible with a real `jest-axe` test suite. ## TL;DR You'll build a filterable, keyboard-navigable combobox using **react-aria-components 1.19.0** (React 19.2, TypeScript 6, Vite 8), following the [WAI-ARIA Combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) without writing a single `aria-*` attribute by hand. Then you'll wire it into a form with required-field validation, and verify the whole thing with `jest-axe` (zero violations, checked both closed and open) plus `@testing-library/user-event` keyboard interaction tests. Every code block in this post is copy-pasted from a project that actually typechecks, builds, and passes its test suite. Budget about 30 minutes. ## What you'll learn - Why hand-rolling ARIA combobox semantics is a common source of accessibility bugs, and what the spec actually requires - How to install and structure a `react-aria-components` `ComboBox` using its real 1.19.0 API (not the newer preview API shown on the docs site) - How to style a headless combobox with plain CSS using its `data-*` state attributes - How filtering, the empty state, and the `menuTrigger` option actually behave — including two gotchas that will surprise you if you've only read the docs - How to wire the combobox into a native `

` with `isRequired` and `FieldError` - How to write an automated accessibility test with `jest-axe` - How to test full keyboard interaction (type-to-filter, arrow-to-focus, Enter-to-select, Escape-to-close) with `@testing-library/user-event` ## Prerequisites - Node.js **20.19+** or **22.12+** (Vite 8's `engines` requirement — Vitest 4 accepts `^20.0.0 || ^22.0.0 || >=24.0.0`, so either LTS line works) - `react` and `react-dom` **19.2.7** (react-aria-components' peer range also covers React 16.8–19, so this isn't React-19-only) - Familiarity with React function components and hooks - No prior React Aria experience needed Install the runtime dependency: ```bash npm install react-aria-components@1.19.0 ``` And the dev/test toolchain used in this guide: ```bash npm install -D vite@8.1.2 @vitejs/plugin-react@6.0.3 vitest@4.1.9 jsdom@29.1.1 \ @testing-library/react@16.3.2 @testing-library/user-event@14.6.1 \ @testing-library/jest-dom@6.9.1 jest-axe@10.0.0 @types/jest-axe@3.5.9 \ typescript@6.0.3 ``` ## Step 1: Why not just write the `div`s yourself? The [WAI-ARIA Authoring Practices Guide (APG) Combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) specifies a `role="combobox"` input that owns `aria-controls`, `aria-expanded`, and `aria-autocomplete` (`list` for this guide's filter-as-you-type behavior), plus a popup listbox whose focused option is tracked with `aria-activedescendant` on the input itself — DOM focus never actually leaves the text field, and each option in the popup needs `aria-selected` set correctly as that virtual focus moves.[^apg] Get any one of those wrong — a stale `aria-controls` id, an `aria-expanded` that doesn't flip, activedescendant IDs that don't match rendered option IDs — and a screen reader user gets silence or wrong information, while the widget still looks perfectly normal to a sighted user testing it with a mouse. None of these mistakes throw a console error or fail a visual review. Miss `aria-activedescendant` and a screen reader announces nothing as the user arrows through suggestions. Forget to update `aria-expanded`, and assistive tech reports the popup as closed while it's visibly open. They only show up when someone actually navigates with a keyboard and a screen reader — which is exactly why this pattern shows up so often in accessibility audits. `react-aria-components` implements this pattern for you at the hook level (`useComboBox`) and exposes it as headless, unstyled components, so you write markup and CSS, and the library manages the ARIA wiring, keyboard interaction, and focus management.[^apg][^rac] ## Step 2: Build the base ComboBox Create `Combobox.tsx`. This wraps `react-aria-components`' `ComboBox` in a small, reusable, generic component: ```tsx // src/Combobox.tsx import { Button, ComboBox, Input, Label, ListBox, Popover, Text, FieldError, type ComboBoxProps as AriaComboBoxProps, type Key, type ValidationResult } from 'react-aria-components'; export interface ComboboxOption { id: string; name: string; } interface ComboboxProps extends Omit, 'children'> { label: string; description?: string; errorMessage?: string | ((validation: ValidationResult) => string); items: Iterable; children: (item: T) => React.ReactNode; ref?: React.Ref; } // All ARIA roles, states (aria-expanded, aria-activedescendant, // aria-controls), keyboard handling, and focus management come from // react-aria-components. This wrapper only supplies markup + styling hooks. // React 19 lets function components accept `ref` as a plain prop, so no // forwardRef wrapper is needed here (see Troubleshooting). export function Combobox({ label, description, errorMessage, items, children, ref, ...props }: ComboboxProps) { return ( {label}

{description && ( {description} )} {errorMessage} ( No matches found )} > {children} ); } export { ListBoxItem } from 'react-aria-components'; export type { Key }; ``` Two things worth calling out here, because they trip people up who read the marketing docs first instead of the installed package: `ComboBox` in 1.19.0 does **not** accept `label` or `placeholder` props directly — those are handled by the `` child and `` — and there is no `ComboBoxItem` export. Items are plain `ListBoxItem`s, same as a standalone `ListBox`. You can confirm this yourself by reading `node_modules/react-aria-components/dist/types/exports/ComboBox.d.ts` after installing — the docs site currently previews a newer, unreleased API shape (`ComboBoxItem`, a `` wrapper, `label`/`placeholder` as direct props) that doesn't match what npm ships as 1.19.0.[^rac] ## Step 3: Use it with a real list ```tsx // src/App.tsx import { useState } from 'react'; import { Combobox, ListBoxItem, type ComboboxOption, type Key } from './Combobox'; interface Framework extends ComboboxOption { name: string; } const frameworks: Framework[] = [ { id: 'react', name: 'React' }, { id: 'vue', name: 'Vue' }, { id: 'svelte', name: 'Svelte' }, { id: 'solid', name: 'Solid' }, { id: 'angular', name: 'Angular' }, { id: 'qwik', name: 'Qwik' }, { id: 'astro', name: 'Astro' } ]; export function App() { // Use react-aria-components' own `Key` type, not React's built-in one -- // they are structurally different and mixing them breaks the typecheck // on `selectedKey` (see Troubleshooting). const [selected, setSelected] = useState(null); return ( {(item) => {item.name}}

Selected: {selected ?? 'none'}

); } ``` `defaultItems` (set inside `Combobox.tsx`) makes the item list uncontrolled — react-aria-components filters it internally as the user types, using a case-insensitive "contains" match by default. If you need custom filtering logic (fuzzy matching, filtering by a field other than the displayed text), pass a `defaultFilter` function to `ComboBox`. ## Step 4: Style it — it's headless, not unstyled-forever `react-aria-components` renders plain DOM elements with `data-*` attributes reflecting state, so you style it with ordinary CSS and no runtime style props: ```css /* Combobox.css */ .combobox-field { display: flex; align-items: center; border: 1px solid #6b7280; border-radius: 6px; } .combobox-input { flex: 1; padding: 0.5rem 0.75rem; border: none; outline: none; } /* [data-focused] is set by the library while the input has focus */ .combobox-input[data-focused] { outline: 2px solid #2563eb; outline-offset: -1px; } .combobox-popover { background: white; border: 1px solid #d1d5db; border-radius: 6px; box-shadow: 0 4px 12px rgba(0, 0, 0, 0.12); } .combobox-listbox { max-height: 240px; overflow-y: auto; padding: 0.25rem; } /* [data-focused] here means "virtually focused via aria-activedescendant" */ [data-focused].react-aria-ListBoxItem { background: #eff6ff; } [data-selected].react-aria-ListBoxItem { font-weight: 600; } .combobox-error { color: #dc2626; font-size: 0.875rem; } ``` Every interactive element exposes the state selectors you'd expect: `[data-open]` and `[data-invalid]` on the `ComboBox` root, `[data-disabled]` and `[data-hovered]` on individual items, and so on — check a rendered DOM tree in your browser devtools to see the full attribute list for any given component. ## Step 5: Two behaviors that will surprise you These aren't bugs — they're exactly what the spec asks for — but they don't match what most people expect the first time: **Typing does not open the popup on its own for an empty result set.** By default, `ComboBox` hides the popup entirely when the filtered collection is empty, so your `renderEmptyState` message never renders. Pass `allowsEmptyCollection` (as in Step 3) if you want a visible "no matches" state instead of the popover silently staying closed. **Clicking or focusing the input alone does not open the popup.** The default `menuTrigger` is `'input'`, meaning the popover opens only when the user *edits* the text — not merely on click or focus. If you want the popup to open on focus (common for "browse all options" comboboxes), set `menuTrigger="focus"`; if you want it to open only via the trigger button or arrow keys, use `menuTrigger="manual"`. **Typing does not auto-highlight the first match.** This one is a spec detail, not a library quirk: the WAI-ARIA APG defines four autocomplete behaviors, and react-aria-components implements "list autocomplete with **manual** selection" — filtering narrows the list, but nothing is auto-selected until the user presses `ArrowDown` (or clicks an option).[^apg] So `user.keyboard('astro{Enter}')` does nothing in a test; you need `user.keyboard('astro{ArrowDown}{Enter}')`. This matters for real users too: don't assume `Enter` alone commits the top filtered result. ## Step 6: Form integration `ComboBox` already behaves like a form field once you give it a `name`. Set `formValue="key"` (the default) to submit the selected item's `id`, or `formValue="text"` to submit the visible text instead. Combined with `isRequired` and `errorMessage`, native HTML5 validation kicks in on submit: ```tsx validationDetails.valueMissing ? 'Please choose a framework.' : 'Invalid selection.' } > {(item) => {item.name}} ``` Under the hood, `ComboBox` renders a hidden `` that mirrors the selected key, so a plain `

` or a `FormData` read picks it up exactly like a native `

#combobox

بناء Combobox سهل الوصول بـ React باستخدام React