Build a combobox autocomplete

A controlled combobox that exposes value, query, options, and loading as props. The parent owns network, debouncing, and stale-response protection.

type Option = { id: string; label: string; description?: string };

type ComboboxProps = {
  label: string;
  options: Option[];
  value: string | null;
  onChange: (id: string | null) => void;
  query: string;
  onQueryChange: (next: string) => void;
  loading?: boolean;
};

export function Combobox({
  label,
  options,
  value,
  onChange,
  query,
  onQueryChange,
  loading,
}: ComboboxProps) {
  const [open, setOpen] = React.useState(false);
  const [activeIndex, setActiveIndex] = React.useState<number>(-1);
  const listboxId = React.useId();
  const inputId = React.useId();

  function commit(index: number) {
    const option = options[index];
    if (!option) return;
    onChange(option.id);
    onQueryChange(option.label);
    setOpen(false);
    setActiveIndex(-1);
  }

  function move(delta: number) {
    if (options.length === 0) return;
    setActiveIndex((current) => {
      const next = current < 0 ? (delta > 0 ? 0 : options.length - 1) : current + delta;
      return Math.max(0, Math.min(options.length - 1, next));
    });
  }

  return (
    <div className="combobox">
      <label htmlFor={inputId}>{label}</label>
      <input
        id={inputId}
        role="combobox"
        // ARIA 1.2 combobox pattern: aria-expanded reflects listbox visibility,
        // aria-controls points at the listbox, aria-activedescendant names the
        // virtually focused option without moving DOM focus.
        aria-expanded={open}
        aria-controls={listboxId}
        aria-autocomplete="list"
        aria-activedescendant={
          activeIndex >= 0 ? listboxId + '-option-' + activeIndex : undefined
        }
        value={query}
        onChange={(event) => {
          onQueryChange(event.target.value);
          setOpen(true);
          setActiveIndex(-1);
        }}
        onFocus={() => setOpen(true)}
        onBlur={() => setOpen(false)}
        onKeyDown={(event) => {
          if (event.key === 'ArrowDown') {
            event.preventDefault();
            setOpen(true);
            move(1);
          } else if (event.key === 'ArrowUp') {
            event.preventDefault();
            move(-1);
          } else if (event.key === 'Enter' && activeIndex >= 0) {
            event.preventDefault();
            commit(activeIndex);
          } else if (event.key === 'Escape') {
            event.preventDefault();
            setOpen(false);
            setActiveIndex(-1);
          }
        }}
      />

      {open && (
        <ul id={listboxId} role="listbox" aria-label={label}>
          {loading && <li role="status" className="status">Loading...</li>}
          {!loading && options.length === 0 && <li role="status" className="status">No matches</li>}
          {options.map((option, index) => (
            <li
              key={option.id}
              id={listboxId + '-option-' + index}
              role="option"
              aria-selected={value= option.id || activeIndex= index}
              onMouseDown={(event)=> event.preventDefault()}
              onClick={()=> commit(index)}
            >
              <strong>{option.label}</strong>
              {option.description && <span>{option.description}</span>}
            </li>
          ))}
        </ul>
      )}
    </div>
  );
}

UI interview practice should behave like component documentation, not a static snippet. This uses the same isolation pattern as Storybook, Sandpack, CodeSandbox, and StackBlitz: editable source on one side, a sandboxed browser preview on the other. Edit the DOM code, run it, and verify focus, keyboard, pointer, and state behavior in the preview.

Convert the answer into observable behavior. In a mid-senior interview, say which behaviors are covered by unit tests, interaction tests, accessibility checks, and one browser smoke path.

import { describe, it, expect, vi } from 'vitest';
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';

describe('Combobox', () => {
  const options = [
    { id: 'a', label: 'Apple' },
    { id: 'b', label: 'Banana' },
  ];

  it('commits selection via keyboard without losing focus', async () => {
    const user = userEvent.setup();
    const onChange = vi.fn();
    const onQueryChange = vi.fn();

    render(
      <Combobox
        label="Fruit"
        options={options}
        value={null}
        onChange={onChange}
        query=""
        onQueryChange={onQueryChange}
      />
    );

    const input = screen.getByRole('combobox', { name: /fruit/i });
    await user.click(input);
    await user.keyboard('{ArrowDown}{Enter}');
    expect(onChange).toHaveBeenCalledWith('a');
    expect(input).toHaveFocus();
  });

  it('reports no-match state with role=status', () => {
    render(
      <Combobox
        label="Fruit"
        options={[]}
        value={null}
        onChange={()=> {}}
        query="zz"
        onQueryChange={()=> {}}
      />
    );
    expect(screen.getByRole('combobox')).toBeInTheDocument();
  });
});

Shows whether you can build components as interaction systems rather than visual boxes.

• Name the controlled and uncontrolled state.
• Define keyboard and focus behavior.
• Include loading, empty, disabled, and error states.

• Start with the accessibility role and interaction contract.
• Separate rendering slots from state management.
• Expose callbacks that describe user intent, not internal implementation details.

• A headless primitive is reusable but slower to consume.
• A product-specific component ships faster but can trap behavior in one use case.

• Focus after close, selection, deletion, or route change.
• Large datasets and slow network responses.
• Screen reader labels and live updates.

• Keyboard path through the primary workflow.
• A11y names, descriptions, and roles.
• State transition after slow or failed data load.

• How would this component be documented in a design system?
• What props would you refuse to expose?