Select

Client componentEngine: react-aria

ImportCopy Anchor Link

import { Select } from '@nizivo/react/select';

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

Static or interactiveCopy Anchor Link

Client. It always ships React Aria's listbox and popup code and FieldScope (+72,949 B gzip under Turbopack for one Select on the Next.js fixture). NativeSelect is the static alternative when the browser's own picker fits. How to choose.

In a FieldCopy Anchor Link

Inside a Field, Select reads the Field the way Input does: the label and the selected value name the trigger, the description and the error describe it, and the Field's name, required, disabled and error state apply unless the Select sets its own (an explicit false wins). The Field's name reaches the hidden native <select>, so the value is in FormData.

A click on the label focuses the trigger, with its focus ring, and never opens the list: a native <label for> a button would press it. A required, empty Select stops the submit and takes focus, but shows no inline message yet (React Aria handles the hidden <select>'s invalid event), so pass error for it. The trigger is a button, which cannot carry aria-required, and the Field's * is hidden from screen readers, so put "required" in the label or the description too (the maintainer's rule for 0.1.0). A form reset puts the default value back in the trigger and in the submitted data.

The selected rowCopy Anchor Link

The selected row keeps a --nz-bg-brand-subtle tint, and its label turns Label/M Strong in --nz-text-primary. A check at its end (--nz-icon-brand) carries the state for readers who do not see the colour (WCAG 1.4.1). The check's 16 px column is reserved on every row, so selecting never moves the text. indicator on Select.Item replaces the check, and indicator={null} removes it. Figma draws no tint on the selected row; the code keeps it (the maintainer's decision of 2026-10-18, listed under Deviations).

The listCopy Anchor Link

The list follows Figma's Select Menu (7356:406): --nz-radius-md, --nz-elevation-4, 6 px inside, and 4 px below the trigger (sideOffset on Select.Popup). Rows are 36 px of Label/M with 8 / 12 px padding and no gap between them, and the keyboard ring is drawn inside the row. Group labels are Label/S in --nz-text-secondary, padded 8 / 12 / 4 / 12. A separator has 4 px above and below. The Dropdown Menu (Menu) keeps its own look.

Text size on touch screensCopy Anchor Link

Under a coarse pointer (a phone or a tablet), the trigger's value and placeholder are 16 px (Label/L) instead of 14 px (Label/M) at every size, matching NativeSelect, so swapping one for the other does not change the text. The trigger keeps its 32, 40 or 48 px height. The list's rows stay at 14 px and its group labels at 12 px: they are not text fields, so iOS does not zoom into them.

ExamplesCopy Anchor Link

import type { JSX } from 'react';
import { Select } from '@nizivo/react/select';

export function SelectExample(): JSX.Element {
  return (
    <Select.Root defaultValue="30d" name="period" aria-label="Period">
      <Select.Trigger />
      <Select.Popup>
        <Select.Group>
          <Select.GroupLabel>Recent</Select.GroupLabel>
          <Select.Item value="7d">Last 7 days</Select.Item>
          <Select.Item value="30d">Last 30 days</Select.Item>
        </Select.Group>
        <Select.Separator />
        <Select.Item value="all" disabled>
          All time
        </Select.Item>
      </Select.Popup>
    </Select.Root>
  );
}

import type { JSX } from 'react';
import { Field } from '@nizivo/react/field';
import { Select } from '@nizivo/react/select';

export function SelectFieldExample(): JSX.Element {
  return (
    <Field
      label="Reporting period"
      description="Applies to every chart on this page."
      name="period"
    >
      <Select.Root defaultValue="30d">
        <Select.Trigger />
        <Select.Popup>
          <Select.Item value="7d">Last 7 days</Select.Item>
          <Select.Item value="30d">Last 30 days</Select.Item>
          <Select.Item value="90d">Last 90 days</Select.Item>
        </Select.Popup>
      </Select.Root>
    </Field>
  );
}

import type { JSX } from 'react';
import { Select } from '@nizivo/react/select';

export function SelectOpenExample(): JSX.Element {
  return (
    <Select.Root defaultOpen placeholder="Choose a period" aria-label="Period" size="sm" invalid>
      <Select.Trigger />
      <Select.Popup>
        <Select.Item value="7d">Last 7 days</Select.Item>
      </Select.Popup>
    </Select.Root>
  );
}

Other exportsCopy Anchor Link

SelectGroupLabelProps type

import type { SelectGroupLabelProps } from '@nizivo/react/select'

The props of Select.GroupLabel, listed above.

SelectGroupProps type

import type { SelectGroupProps } from '@nizivo/react/select'

The props of Select.Group, listed above.

SelectItemProps type

import type { SelectItemProps } from '@nizivo/react/select'

The props of Select.Item, listed above.

SelectItemState type

import type { SelectItemState } from '@nizivo/react/select'

The render state of Select.Item, listed above.

SelectLabels type

import type { SelectLabels } from '@nizivo/react/select'

Strings the engine renders (§9.3 rule 7). placeholder is passed to the engine. Engine-owned with React Aria (not overridable): the visually hidden "Dismiss" buttons in the popup.

Name	Type	Default	Description
placeholderrequired	string	–	Shown while no value is chosen. React Aria's default is its localized "Select an item".

SelectPopupProps type

import type { SelectPopupProps } from '@nizivo/react/select'

The props of Select.Popup, listed above.

SelectPopupState type

import type { SelectPopupState } from '@nizivo/react/select'

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

SelectRootProps type

import type { SelectRootProps } from '@nizivo/react/select'

The props of Select.Root, listed above.

SelectRootState type

import type { SelectRootState } from '@nizivo/react/select'

Name	Type	Default	Description
disabledrequired	boolean	–
openrequired	boolean	–

SelectSeparatorProps type

import type { SelectSeparatorProps } from '@nizivo/react/select'

The props of Select.Separator, listed above.

SelectTriggerProps type

import type { SelectTriggerProps } from '@nizivo/react/select'

The props of Select.Trigger, listed above.

SelectTriggerState type

import type { SelectTriggerState } from '@nizivo/react/select'

The render state of Select.Trigger, listed above.

SelectValueProps type

import type { SelectValueProps } from '@nizivo/react/select'

The props of Select.Value, listed above.

SelectValueReason type

import type { SelectValueReason } from '@nizivo/react/select'

type SelectValueReason = "item-press" | "keyboard" | "typeahead" | "form-reset"

SelectValueState type

import type { SelectValueState } from '@nizivo/react/select'

The render state of Select.Value, listed above.

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-select-chevron, .nz-select-group, .nz-select-group-label, .nz-select-icon, .nz-select-item, .nz-select-item-indicator, .nz-select-list, .nz-select-popup, .nz-select-separator, .nz-select-trigger, .nz-select-value. 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:

• select-item: draws the focus outline when the engine reports keyboard focus, not on pointer hover.
• select-trigger: draws the focus outline itself on keyboard focus.

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

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

Pattern: WAI-ARIA Authoring Practices.

KeyboardCopy Anchor Link

Source: react-aria-components 1.22.1 Select (react-aria 3.53.1 useSelect, useMenuTrigger and useSelectableCollection) through _engines/react-aria/select.client.tsx. apps/docs/scripts/smoke.ts checks ArrowDown opening on the selected option, ArrowDown and Enter choosing, Escape closing with focus back on the trigger, ArrowRight and ArrowLeft on the closed trigger, and typing on the trigger; the overlay lane (test/overlay/select.spec.tsx) checks Tab and Shift+Tab, which the adapter handles because React Aria keeps Tab inside its modal popover.

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: Figma node 7275:11438, Figma node 7356:401, Figma node 7356:402, Figma node 7356:404, Figma node 7356:406
• Ghost masters: Figma node 745:222