Combobox

Client componentEngine: react-aria

ImportCopy Anchor Link

import { Combobox } from '@nizivo/react/combobox';

// Once per app (Getting started), after
// @nizivo/tokens/tokens.css and @nizivo/react/css/base.css and @nizivo/react/css/input.css
import '@nizivo/react/css/combobox.css';

Static or interactiveCopy Anchor Link

Client. It is React Aria's ComboBox, which reads its Field through FieldScope, so a page with a Combobox also loads FieldScope. The server HTML is the input with the chosen item's text and, with a name, the hidden input with its value, so a form submits before hydration; the list opens once the page has hydrated. How to choose.

In a client app (a Vite or React Router single-page app, or a 'use client' file) it is an ordinary React component: event handlers, refs and state work as usual. In a client app.

PartsCopy Anchor Link

Combobox.Root holds the value and draws the box. Combobox.Input is the text input; Combobox.Trigger after it adds a chevron button that opens every item. Combobox.Popup holds Combobox.Items, which may sit in Combobox.Groups with a Combobox.GroupLabel, apart from each other by a Combobox.Separator. The popup is as wide as the box, the Trigger included.

Value and textCopy Anchor Link

value is the chosen item's value, and inputValue the text in the input; each has a default… and an on…Change. Choosing an item puts its text (textValue, or its children when they are a string) in the input. Without allowsCustomValue, a blur or Escape puts back the chosen item's text, and clearing the input clears the choice. With it, the text may be anything: it stays as typed, and a form submits it.

When the list opensCopy Anchor Link

menuTrigger is 'input' by default: the list opens as the reader types and shows the items that contain the text, matched in the locale's collation and ignoring case. 'focus' also opens it, with every item, when the input takes focus or is pressed. 'manual' opens it only from the Trigger or the arrow keys. With no match the list closes. defaultOpen opens it on the first render; React Aria keeps the open state itself, so there is no controlled open, and onOpenChange reports each change.

FormsCopy Anchor Link

With name (or a Field's), a hidden input carries the chosen item's value, de and never "Germany", into FormData; with allowsCustomValue the input itself carries the typed text. Inside a Field, required is checked natively on the input, so the Field's messages.valueMissing applies.

Engine-ownedCopy Anchor Link

The Trigger's name, "Show suggestions" followed by the field's label, the list's name, "Suggestions" (used only when the field has no label; with one, the list is named by it), and the announcements of how many items are available come from React Aria's catalogue, translated in 36 locales. labels does not set them: the Strings guide lists the engine-owned strings.

ExamplesCopy Anchor Link

import type { JSX } from 'react';
import { Field } from '@nizivo/react/field';
import { Combobox } from '@nizivo/react/combobox';

export function ComboboxExample(): JSX.Element {
  return (
    <Field name="country" label="Country" description="Where we ship the order." required>
      <Combobox.Root>
        <Combobox.Input placeholder="Start typing" />
        <Combobox.Trigger />
        <Combobox.Popup>
          <Combobox.Item value="at">Austria</Combobox.Item>
          <Combobox.Item value="be">Belgium</Combobox.Item>
          <Combobox.Item value="de">Germany</Combobox.Item>
          <Combobox.Item value="fr">France</Combobox.Item>
          <Combobox.Item value="in">India</Combobox.Item>
          <Combobox.Item value="nl">Netherlands</Combobox.Item>
          <Combobox.Item value="gb">United Kingdom</Combobox.Item>
          <Combobox.Item value="us">United States</Combobox.Item>
        </Combobox.Popup>
      </Combobox.Root>
    </Field>
  );
}

import type { JSX } from 'react';
import { Field } from '@nizivo/react/field';
import { Combobox } from '@nizivo/react/combobox';

export function ComboboxSuggestionsExample(): JSX.Element {
  return (
    <Field name="q" label="Search products">
      <Combobox.Root allowsCustomValue>
        <Combobox.Input placeholder="Mugs, bowls, glaze…" />
        <Combobox.Popup>
          <Combobox.Group>
            <Combobox.GroupLabel>Recent</Combobox.GroupLabel>
            <Combobox.Item value="sand-mug">Sand mug</Combobox.Item>
          </Combobox.Group>
          <Combobox.Separator />
          <Combobox.Group>
            <Combobox.GroupLabel>Categories</Combobox.GroupLabel>
            <Combobox.Item value="mugs">Mugs</Combobox.Item>
            <Combobox.Item value="bowls">Bowls</Combobox.Item>
            <Combobox.Item value="plates">Plates</Combobox.Item>
          </Combobox.Group>
        </Combobox.Popup>
      </Combobox.Root>
    </Field>
  );
}

import type { JSX } from 'react';
import { Field } from '@nizivo/react/field';
import { Combobox } from '@nizivo/react/combobox';

export function ComboboxStatesExample(): JSX.Element {
  const items = (
    <Combobox.Popup>
      <Combobox.Item value="standard">Standard</Combobox.Item>
      <Combobox.Item value="express">Express</Combobox.Item>
      <Combobox.Item value="pickup" disabled>
        Store pickup
      </Combobox.Item>
    </Combobox.Popup>
  );
  return (
    <div style={{ display: 'grid', gap: 16, maxInlineSize: 320 }}>
      <Field label="Shipping">
        <Combobox.Root defaultValue="express" size="sm">
          <Combobox.Input />
          <Combobox.Trigger />
          {items}
        </Combobox.Root>
      </Field>
      <Field label="Shipping" error="Express is not available for this address.">
        <Combobox.Root defaultValue="express" size="lg">
          <Combobox.Input />
          <Combobox.Trigger />
          {items}
        </Combobox.Root>
      </Field>
      <Field label="Shipping" disabled>
        <Combobox.Root defaultValue="standard">
          <Combobox.Input />
          <Combobox.Trigger />
          {items}
        </Combobox.Root>
      </Field>
    </div>
  );
}

Other exportsCopy Anchor Link

ComboboxGroupLabelProps type

import type { ComboboxGroupLabelProps } from '@nizivo/react/combobox'

The props of Combobox.GroupLabel, listed above.

ComboboxGroupProps type

import type { ComboboxGroupProps } from '@nizivo/react/combobox'

The props of Combobox.Group, listed above.

ComboboxInputProps type

import type { ComboboxInputProps } from '@nizivo/react/combobox'

The props of Combobox.Input, listed above.

ComboboxInputState type

import type { ComboboxInputState } from '@nizivo/react/combobox'

The render state of Combobox.Input, listed above.

ComboboxItemProps type

import type { ComboboxItemProps } from '@nizivo/react/combobox'

The props of Combobox.Item, listed above.

ComboboxItemState type

import type { ComboboxItemState } from '@nizivo/react/combobox'

The render state of Combobox.Item, listed above.

ComboboxMenuTrigger type

import type { ComboboxMenuTrigger } from '@nizivo/react/combobox'

When the list opens. 'input': as the reader types (the default). 'focus': also when the input takes focus, showing every item. 'manual': only from the Trigger or Arrow Down / Up.

type ComboboxMenuTrigger = "input" | "focus" | "manual"

ComboboxPopupProps type

import type { ComboboxPopupProps } from '@nizivo/react/combobox'

The props of Combobox.Popup, listed above.

ComboboxPopupState type

import type { ComboboxPopupState } from '@nizivo/react/combobox'

Name	Type	Default	Description
enteringrequired	boolean	–
exitingrequired	boolean	–
siderequired	Side "top" | "right" | "bottom" | "left"	–

ComboboxRootProps type

import type { ComboboxRootProps } from '@nizivo/react/combobox'

The props of Combobox.Root, listed above.

ComboboxRootState type

import type { ComboboxRootState } from '@nizivo/react/combobox'

Name	Type	Default	Description
disabledrequired	boolean	–
invalidrequired	boolean	–
openrequired	boolean	–
readOnlyrequired	boolean	–
requiredrequired	boolean	–

ComboboxSeparatorProps type

import type { ComboboxSeparatorProps } from '@nizivo/react/combobox'

The props of Combobox.Separator, listed above.

ComboboxTriggerProps type

import type { ComboboxTriggerProps } from '@nizivo/react/combobox'

The props of Combobox.Trigger, listed above.

ComboboxTriggerState type

import type { ComboboxTriggerState } from '@nizivo/react/combobox'

The render state of Combobox.Trigger, listed above.

ComboboxValueReason type

import type { ComboboxValueReason } from '@nizivo/react/combobox'

React Aria reports no cause for a change.

type ComboboxValueReason = "unknown"

Data attributes and slotsCopy Anchor Link

Style parts by class (.nz-<slot>) and state by data attribute. Attribute meanings come from contracts/vocabulary.json.

CSS hooksCopy Anchor Link

Set a hook on the component's class or any ancestor to restyle it without specificity games; leave it unset for the default shown.

Layers: nz.components. Classes: .nz-combobox, .nz-combobox-chevron, .nz-combobox-control, .nz-combobox-group, .nz-combobox-group-label, .nz-combobox-item, .nz-combobox-item-indicator, .nz-combobox-list, .nz-combobox-popup, .nz-combobox-separator, .nz-combobox-trigger, .nz-input. Runtime variables: --nz-available-height, --nz-transform-origin, --nz-trigger-width.

AccessibilityCopy Anchor Link

These parts are interactive. Each gets the focus outline and touch-action rule from @nizivo/react/css/base.css (the nz.base layer), so the floor survives a restyle:

• combobox-control: draws the outline when the field inside it has focus.
• combobox-item: draws the focus outline when the engine reports keyboard focus, not on pointer hover.
• combobox-trigger: draws the focus outline itself on keyboard focus.

In forced-colours mode these states keep a visible system colour: combobox-item[data-selected] (highlight), combobox-popup (border).

Behaviour comes from the react-aria engine through Nizivo's adapter: focus management, ARIA wiring and keyboard handling are the engine's.

KeyboardCopy Anchor Link

Source: React Aria Components 1.22.1 ComboBox (_engines/react-aria/combobox.client.tsx). The overlay lane (test/overlay/combobox.spec.tsx) runs the family's overlay conformance and checks filtering, the active item, Enter, Escape, the Trigger, blur, custom values, forms and a Field's required message.

FigmaCopy Anchor Link

Node ids from design/component-map.json, which nz gen writes from component.json. The links open the Nizivo Figma library, which may ask you to sign in.

• Canonical: none
• Ghost masters: none