SearchSelect

Usage

SearchSelect is a controlled async typeahead: pass a fetcher (onSearch), hold the selection in state (value + onChange), and always provide ariaLabel — it is required at the type level. The component owns debouncing (300 ms by default), a request race guard that drops stale responses, outside-click dismissal, and keyboard navigation. Wire it to your real API inside the fetcher — the component is endpoint-agnostic.

import { useState } from 'react'
import { SearchSelect } from '@epasslive/design-system'

const [venue, setVenue] = useState(null)

<SearchSelect
  ariaLabel="Venue"
  placeholder="Search venues…"
  value={venue}
  onChange={setVenue}
  onSearch={(q) => fetchVenues(q)}
  resultLimit={3}
  refineLabel="Keep typing to refine"
/>

Inline create

Provide onCreate and a create row appears whenever the search returns no results. Selecting it (click or Enter) calls your creator with the trimmed query and adopts the returned option as the selection. The row label defaults to the literal text Add "query" built from the trimmed query — pass createLabel to customize it, as in the second live example above. While the create request is in flight the row shows loadingLabel.

<SearchSelect
  ariaLabel="Artist"
  value={artist}
  onChange={setArtist}
  onSearch={(q) => searchArtists(q)}
  onCreate={(q) => createArtist(q)}
  createLabel={(q) => `Add new artist "${q}"`}
  noResultsLabel="No artist found"
/>

SearchSelect vs Select vs Listbox

Use SearchSelect for async, server-backed single-select typeahead with optional inline create. Use Select for static or locally searched option lists, multi-select, and button-triggered popovers. Use Listbox for an always-visible inline selection list with no text input. Do not use SearchSelect for static option lists — Select is the correct static widget.

Accessibility

The input exposes role="combobox" with aria-expanded, aria-controls, aria-autocomplete="list", and the required ariaLabel. The popup is a role="listbox" whose rows are role="option". Keyboard: ArrowDown opens, ArrowUp/Down navigate (including the create row), Home/End jump, Enter selects or creates, Escape closes and restores the selected label, Tab closes. Focus stays in the input throughout.

Known gap (tracked for the next cascade step): the input does not yet set aria-activedescendant and option rows carry no ids, so arrow-key navigation is silent to screen readers; aria-selected also currently tracks the visually active row rather than the chosen option. The active-option tint (teal at 10% with theme-swapping text tokens) passes WCAG AA 4.5:1 in both light and dark themes.

Props