Ariakit supplies unstyled React components with explicit shared state and composable accessible parts. Its combobox separates typed input from committed selection, making it useful for search-driven pickers; the reference finder below demonstrates that distinction with grouped and unavailable results.
Native @ariakit/react 0.4.40 and React 19. All visual tokens and sample reference content are original. · Implementation reference
02
Ariakit Design System Design Reference
Ariakit React 0.4.40 is an unstyled accessibility toolkit. It does not publish the page palette, font scale or spacing below as a native design theme. All --app-* values are an explicit original configuration used by this runnable specimen; component names and state attributes are Ariakit APIs.
Ariakit Design System Start with the Combobox State Model
Start with the Combobox State Model
Ariakit’s ComboboxProvider connects the label, editable input, disclosure, popup and options. The provider owns their shared interaction state while each component supplies its part of the structure. This allows the search field and selected-detail panel to be arranged independently without treating every keystroke as a new selection.
The reference finder demonstrates six records in two named groups. Filtering belongs to the application collection; navigation and option selection belong to the native combobox. Keeping that boundary explicit is useful when replacing static records with another data source: a filtered result set and the currently committed item are not necessarily the same thing.
Ariakit Design System Search Text and Committed Selection Are Different State
Search Text and Committed Selection Are Different State
The example controls inputValue and setInputValue for the text being typed, and selectedValue and setSelectedValue for the chosen reference. In the verified 0.4.40 API, inputValue is the current name for the input state; older examples may show the deprecated value/setValue aliases. The complete code uses the current names.
Typing “color” narrows the suggestions but does not immediately replace the displayed detail card. Choosing Color roles commits that item and updates the panel. Clearing the search similarly leaves the last selected reference intact. Treating every partial query as a committed value would make the detail view jump to invalid or nonexistent records.
Ariakit Design System Connect Label, Input, Disclosure and Popover
Connect Label, Input, Disclosure and Popover
ComboboxProvider supplies shared state to ComboboxLabel, Combobox, ComboboxDisclosure and ComboboxPopover. The visible label identifies the input. The disclosure is a separate button with an explicit accessible name, while the popover uses sameWidth and an eight-pixel gutter to stay aligned with the anchor.
Each result is a ComboboxItem with a stable value. Foundations and Components are native ComboboxGroup sections with ComboboxGroupLabel headings. A visually bold heading inserted into an unstructured list would not express the same grouping relationship; the native anatomy carries that relationship along with its keyboard model.
Ariakit Design System Filter Data Before Rendering Native Items
Filter Data Before Rendering Native Items
The sample collection contains five available references and one deliberately unavailable Experimental grid. Filtering is an application-level case-insensitive substring match against each reference name. The two groups are rendered only when they contain matching records, avoiding empty headings between results.
A zero-result query produces a specific message that suggests clearing the search or trying “color.” It does not turn the message into a selectable option. The disabled record remains visible when relevant and carries an Unavailable label, while the native disabled prop prevents it from becoming a committed selection.
Ariakit Design System Verify the Actual Down-and-Enter Path
Verify the Actual Down-and-Enter Path
The specimen leaves autoSelect off. After typing a query, Down enters the suggestion list and Enter selects the active item. Escape closes the popover. This matches the visible instructions and was verified against the selected detail title, not only against whether a dropdown appeared.
Auto-highlighting can be appropriate in another product, but it changes the starting point of arrow navigation. With a single already-active result, another Down press can move focus back to the input. The example avoids that mismatch and styles the active item through data-active-item, keeping keyboard position distinct from saved reading-list membership.
Type “color” and wait for its matching option.
Press Down, then Enter, and inspect the Color roles detail panel.
Search for an unavailable or nonexistent reference and confirm no unintended selection is committed.
Ariakit Design System Active Option, Focus Ring and Saved State Have Different Cues
Active Option, Focus Ring and Saved State Have Different Cues
The input and disclosure use visible focus outlines. The active option receives a pale green background plus a one-pixel internal outline through the native data-active-item attribute. Disabled options reduce emphasis and retain their explicit text label. These styles do not rely on hover alone.
The Add button becomes disabled and changes its text after the selected reference is already in the reading list. That saved state belongs to the application and is separate from the combobox’s currently active result. A pale green saved-action surface avoids representing a disabled action as another enabled primary button.
Ariakit Design System A Reading List Does Not Replace the Current Reference
A Reading List Does Not Replace the Current Reference
Adding a reference appends its name to a local array only once; the current reference remains visible so the user can inspect its notes. Each reading-list row has a specifically named Remove button. Removing an entry re-enables Add when that reference is still selected. The count is derived from the array length.
The sample detail content includes type, spacing and component guidance to make the finder useful to explore. Its values are clearly labeled original sample content. A reader must not mistake “Display 36px” in the Type scale record for an Ariakit typography token; Ariakit is not supplying that design language.
Ariakit Design System A Popover Needs Room Without Resizing the Whole Page
A Popover Needs Room Without Resizing the Whole Page
The popover follows the input width and caps its own height at 340px. A larger result collection scrolls inside that boundary while the selected-detail card remains normal document content. Keep the input, disclosure and option popup connected even if the detail card moves to another column; committing an item should still update the same selected record.
At the original 700px breakpoint the finder and detail card stack. The search controls, keyboard hint and reading list remain before the selected card in document order. Decorative reference artwork is hidden from assistive technology because the title and notes provide the actual meaning.
Constrain a long option list locally while preserving readable item spacing.
Keep the committed detail panel outside the transient popover.
Retain visible input labels and keyboard hints on mobile.
Ariakit Design System Connect the Provider, Collection and Stylesheet
Connect the Provider, Collection and Stylesheet
Install @ariakit/react 0.4.40 in the React project and keep the complete provider/component composition from App.jsx. The current example uses inputValue/setInputValue and selectedValue/setSelectedValue as separate controlled pairs. Keep the selected record available even when the current input query filters it out of the popup.
Import the supplied style.css alongside the component. Its data-active-item rule follows the combobox’s keyboard position, while the saved-list styles follow application state. When substituting asynchronously loaded results, preserve those two state channels and the group/option relationships; do not replace the committed detail panel with an intermediate query string.
Provider, label, input, disclosure, grouped popover items and local reading-list actions.
jsx
import React,{useState} from 'react';
import * as Ariakit from '@ariakit/react';
const resources=[{name:'Type scale',group:'Foundations',code:'Aa',description:'A compact editorial hierarchy for headings, supporting text and labels.',notes:['Display · 36px / 1.1','Section · 24px / 1.25','Body · 16px / 1.6'],color:'#f0dbc3'},{name:'Color roles',group:'Foundations',code:'◐',description:'Separate surface, text, boundary and action roles before naming brand colors.',notes:['Canvas and raised surface','Primary and muted text','Action and on-action pair'],color:'#d6e5d8'},{name:'Spacing rhythm',group:'Foundations',code:'▥',description:'Use a small set of intervals to show relationships between content groups.',notes:['8px within a compact group','16px between related controls','32px between sections'],color:'#d6dfee'},{name:'Form field',group:'Components',code:'⌑',description:'Keep the label, hint, input and error message in one understandable group.',notes:['Persistent visible label','Hint before an error exists','Error connected to the input'],color:'#e9d8de'},{name:'Navigation menu',group:'Components',code:'☷',description:'A small set of destinations with a visible current location and keyboard access.',notes:['Destination labels describe content','Current item has a text/state cue','Collapsed layout keeps names'],color:'#e7e0c5'},{name:'Experimental grid',group:'Components',code:'▦',description:'Unavailable in this sample collection.',notes:[],color:'#e3e3e3',disabled:true}];
export default function App(){const[query,setQuery]=useState(''),[chosen,setChosen]=useState('Type scale'),[saved,setSaved]=useState([]);const selected=resources.find(x=>x.name===chosen)||resources[0],matches=resources.filter(x=>x.name.toLowerCase().includes(query.toLowerCase()));return <main className="resource-finder"><header><p className="eyebrow">ARIAKIT · ACCESSIBLE PRIMITIVES</p><h1>A reference, within reach.</h1><p>Search a small collection with the keyboard, inspect the result and keep a local reading list.</p></header><div className="finder-grid"><section className="search-area"><Ariakit.ComboboxProvider inputValue={query} setInputValue={setQuery} selectedValue={chosen} setSelectedValue={setChosen}><Ariakit.ComboboxLabel className="label">Find a reference</Ariakit.ComboboxLabel><div className="input-row"><Ariakit.Combobox className="combobox" placeholder="Try type, color or form" /><Ariakit.ComboboxDisclosure className="disclosure" aria-label="Show reference suggestions">⌄</Ariakit.ComboboxDisclosure></div><Ariakit.ComboboxPopover gutter={8} sameWidth className="popover">{['Foundations','Components'].map(group=>{const items=matches.filter(x=>x.group===group);return items.length?<Ariakit.ComboboxGroup key={group}><Ariakit.ComboboxGroupLabel className="group-label">{group}</Ariakit.ComboboxGroupLabel>{items.map(x=><Ariakit.ComboboxItem key={x.name} value={x.name} disabled={x.disabled} className="combo-item"><span>{x.name}</span><small>{x.disabled?'Unavailable':x.group==='Foundations'?'Guide':'Pattern'}</small></Ariakit.ComboboxItem>)}</Ariakit.ComboboxGroup>:null})}{!matches.length&&<p className="empty" role="status">No matching reference. Try “color” or clear the search.</p>}</Ariakit.ComboboxPopover></Ariakit.ComboboxProvider><p className="hint">Type to filter. Use ↓ and ↑ to browse, Enter to choose, Escape to close.</p><div className="collection-note"><span>06</span><div><strong>Sample references</strong><p>Five available, one deliberately disabled to show an unavailable item.</p></div></div><section className="reading-list"><h2>Your reading list <small>{saved.length}</small></h2>{saved.length?<ul>{saved.map(name=><li key={name}><span>{name}</span><Ariakit.Button className="remove" onClick={()=>setSaved(saved.filter(x=>x!==name))} aria-label={`Remove ${name}`}>Remove</Ariakit.Button></li>)}</ul>:<p className="muted">Choose a reference, then add it here.</p>}<p className="local-note">This list stays in memory and clears on reload.</p></section></section><section className="reference-card" aria-label="Selected reference"><div className="reference-art" style={{background:selected.color}} aria-hidden="true"><span>{selected.code}</span><i></i></div><div className="reference-body"><p className="eyebrow">{selected.group} · SAMPLE CONTENT</p><h2>{selected.name}</h2><p>{selected.description}</p><ul className="note-list">{selected.notes.map(note=><li key={note}>{note}</li>)}</ul><Ariakit.Button className="primary" disabled={saved.includes(selected.name)} onClick={()=>setSaved([...saved,selected.name])}>{saved.includes(selected.name)?'Added to reading list':'Add to reading list'}</Ariakit.Button><p className="scope-note">These sample reference values are original content, not Ariakit design tokens.</p></div></section></div><p className="selection-status" role="status">Selected reference: {selected.name}</p></main>}
Ariakit supplies behavior and semantics, not this color or spacing system.
The active result is styled through data-active-item.
The popover has its own maximum height and scroll region.
04
Ariakit Design System Agent Setup
Implementation Starting Point
Verified with @ariakit/react 0.4.40 and React 19. Uses current inputValue/setInputValue names and a controlled selectedValue.
jsx
// Create the project first:
// npm create vite@latest ariakit-specimen -- --template react
// cd ariakit-specimen && npm install
// In a Vite React project:
// npm install @ariakit/[email protected] react@19 react-dom@19
// Save the complete component as App.jsx and the visual configuration as style.css.
import React from 'react';
import {createRoot} from 'react-dom/client';
import App from './App.jsx';
import './style.css';
createRoot(document.getElementById('root')).render(<App />);
// index.html contains <div id="root"></div>.
// No Ariakit theme stylesheet is required; style.css is this example's original theme.
// Keep the template index.html and replace its entry with the code above.
// npm run dev
A Prompt for Your Project
Agent Prompt
Use the supplied Ariakit 0.4.40 reference finder in React. Keep ComboboxProvider inputValue/setInputValue independent from selectedValue/setSelectedValue, retain native labeled groups and the disabled Experimental grid option, and filter the data before rendering items. Preserve the verified Down-then-Enter path with autoSelect off and style data-active-item separately from saved membership. Add the committed reference to a duplicate-free local reading list and allow removal without discarding the current detail. Include the complete original stylesheet.
05
Ariakit Design System Sources and Scope
Ariakit React 0.4.40. All visual tokens, artwork and sample reference values are original configuration; no official Ariakit palette or typography scale is claimed. Reading-list state is local.
