Select
Select controls choose one option from a compact set such as status, owner, or view mode.
Overview and decision boundary
Use Select when a user chooses one option from a compact, known set.
Do not use Select for a searchable set; use Combobox for bounded synchronous filtering.
Status
Choose the closest workflow state.
import { Select } from '@nerio-ui/ui/client';<Select label="Publication status" name="status" placeholder="Choose status" options={[ { label: 'Draft', value: 'draft' }, { label: 'In review', value: 'review' }, { label: 'Published', value: 'published' }, { label: 'Archived', value: 'archived', disabled: true }, ]}/>Installation and imports
Install the editable registry source, or use the matching package entrypoint when the product keeps Nerio as a workspace dependency.
pnpm exec nerio add selectimport { Select } from '@nerio-ui/ui/client';Usage
import { Select } from '@nerio-ui/ui/client';<Select label="Publication status" name="status" placeholder="Choose status" options={[ { label: 'Draft', value: 'draft' }, { label: 'In review', value: 'review' }, { label: 'Published', value: 'published' }, { label: 'Archived', value: 'archived', disabled: true }, ]}/>Variants
| Mode | Purpose |
|---|---|
options | Data-driven options for a compact known list. |
composed | Curated items, groups, labels, and separators. |
sm / md / lg | Shared control scale; md is the default. |
Anatomy
| Slot | Purpose |
|---|---|
root | Root slot exposed through data-slot="root". |
label | Label slot exposed through data-slot="label". |
trigger | Button-like control that opens the option list. |
value | Current selection or placeholder text. |
icon | Chevron end-slot centered within the trigger. |
content | Layered list rendered through Base UI portal behavior. |
item | Selectable option with highlighted and selected states. |
item-description | Optional supporting text for an option. |
indicator | Selected-item indicator. |
group / group-label | Curated grouping anatomy for structured option sets. |
separator | Visual boundary between option groups. |
message | Helper or validation message. |
States
| State | Behavior |
|---|---|
Open | Options appear above the app layer. |
Placeholder | Placeholder text does not auto-select the first option. |
Highlighted | Keyboard or pointer focus indicates the next selection. |
Selected | A restrained selected surface and indicator confirms the current value. |
Disabled | Prevents choosing unavailable options. |
Read-only | Keeps the value visible without allowing changes. |
Required | Supports native form required metadata. |
Invalid | Connects error text and aria-invalid when validation fails. |
Motion
- State changes should use shared motion tokens and preserve reduced-motion behavior.
Accessibility
- Uses the Base UI Select primitive.
- The visible label is associated with the select control.
- Supports placeholder, description, helper or error message, disabled, read-only, and invalid states.
- Supports native form metadata including name, form, required, readOnly, and autoComplete.
- Does not select the first option when only a placeholder is supplied.
- Error messages are announced with role="alert" only when invalid is true.
- Options support disabled states, typeahead, and Base UI keyboard navigation.
- Pair the document dir attribute with Base UI DirectionProvider so popup behavior follows LTR or RTL.
- Use Combobox for a bounded synchronous searchable set. Remotely loaded and multi-select datasets remain outside Select.
Review the shared responsibility and evidence boundaries in the Accessibility foundation alongside this component-specific contract. Use the Spacing & layout foundation for shared density, wrapping, overflow, reflow, and component-versus-product ownership guidance. The Color foundation, Typography foundation, and Localization foundation define the shared visual-role, text-resilience, direction, and locale boundaries used by component examples.
API
| Props | Purpose |
|---|---|
label / options | Visible ReactNode label and concise data-driven options. |
children | Curated SelectItem composition; cannot be mixed with options. |
value / defaultValue / onValueChange | Controlled or uncontrolled single value with Nerio event details. |
open / defaultOpen / onOpenChange | Controlled or uncontrolled popup state with Nerio event details. |
size / triggerRef | Shared control size and access to the combobox trigger. |
name / form / required / readOnly / autoComplete | Native form participation and control state. |
className | Extends the component root while preserving tokenized defaults. |
Implementation contract
| Contract | Value |
|---|---|
Registry item | select installs Tailwind-first source, the token bridge, and residual popup keyframes. |
Base UI | select |
Registry dependencies | form-message |
Package dependencies | @base-ui/react, @nerio-ui/adapters, clsx, react, tailwind-merge, tailwindcss |
Styling contract
| Contract | Value |
|---|---|
Authoring | Complete, statically detectable Tailwind CSS v4 recipes own component visuals. |
Values | Semantic and component --n-* variables remain the canonical customization layer. |
Overrides | Customizable slots merge consumer className values with tailwindCn so conflicting utilities resolve deterministically. |
Residual CSS | Only shared keyframes and scoped no-Preflight compatibility rules remain; there is no parallel visual selector layer. |
Design notes
- Use Select when a user chooses one option from a compact, known set.
Do / do not
Do
Use for status, owner, view mode, and compact configuration choices.
Do not
Use Select for large, searchable, remotely loaded, or multi-select datasets.
Related components
Tokens
These are the primary customization points. Override semantic or component tokens instead of changing component source.
| Token | Purpose |
|---|---|
--n-select-height-sm | Public customization point for this component contract. |
--n-select-height-md | Public customization point for this component contract. |
--n-select-height-lg | Public customization point for this component contract. |
--n-select-padding-inline | Public customization point for this component contract. |
--n-select-trigger-gap | Public customization point for this component contract. |
--n-select-item-gap | Public customization point for this component contract. |
--n-select-item-padding-inline | Public customization point for this component contract. |
--n-select-group-label-padding-inline | Public customization point for this component contract. |
--n-select-empty-padding | Public customization point for this component contract. |
--n-select-popup-radius | Public customization point for this component contract. |
--n-input-radius | Public customization point for this component contract. |
--n-input-background | Public customization point for this component contract. |
--n-input-border | Public customization point for this component contract. |
--n-input-border-hover | Public customization point for this component contract. |
--n-input-border-focus | Public customization point for this component contract. |
--n-input-border-danger | Public customization point for this component contract. |
--n-input-placeholder | Public customization point for this component contract. |
--n-input-foreground | Public customization point for this component contract. |
--n-input-disabled-background | Public customization point for this component contract. |
--n-input-disabled-foreground | Public customization point for this component contract. |
--n-overlay-z-index | Public customization point for this component contract. |
--n-overlay-floating-z-index | Public customization point for this component contract. |
--n-overlay-background | Public customization point for this component contract. |
--n-overlay-border | Public customization point for this component contract. |
--n-overlay-shadow | Public customization point for this component contract. |
--n-focus-ring | Public customization point for this component contract. |