Select

The Select component provides a dropdown menu for selecting a single option from a list. Built on Radix UI primitives for full accessibility and keyboard navigation.

Installation

npm install @nqlib/nqui

Import

import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from '@nqlib/nqui';

Basic Usage

import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from '@nqlib/nqui';

export default function Example() {
  return (
    <Select>
      <SelectTrigger className="w-[180px]">
        <SelectValue placeholder="Select an option" />
      </SelectTrigger>
      <SelectContent>
        <SelectItem value="option1">Option 1</SelectItem>
        <SelectItem value="option2">Option 2</SelectItem>
        <SelectItem value="option3">Option 3</SelectItem>
      </SelectContent>
    </Select>
  );
}

Examples

Basic Select

With Label

Favorite Fruit

Controlled Select

Selected: None

Disabled State

Sizes

Small

Default

Controlled Select

Use controlled state for programmatic control:

const [value, setValue] = useState('');

<Select value={value} onValueChange={setValue}>
  <SelectTrigger>
    <SelectValue placeholder="Select an option" />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="option1">Option 1</SelectItem>
    <SelectItem value="option2">Option 2</SelectItem>
  </SelectContent>
</Select>

With Label

Always pair selects with labels for accessibility:

import { Label } from '@nqlib/nqui';

<Label htmlFor="fruit-select">Favorite Fruit</Label>
<Select>
  <SelectTrigger id="fruit-select">
    <SelectValue placeholder="Select a fruit" />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="apple">Apple</SelectItem>
    <SelectItem value="banana">Banana</SelectItem>
  </SelectContent>
</Select>

Sizes

The SelectTrigger supports size variants:

<SelectTrigger size="sm">...</SelectTrigger>
<SelectTrigger size="default">...</SelectTrigger>

Disabled State

<Select disabled>
  <SelectTrigger>
    <SelectValue placeholder="Disabled select" />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="option1">Option 1</SelectItem>
  </SelectContent>
</Select>

Component Structure

The Select component consists of several sub-components:

Select - Root component that manages state
SelectTrigger - The button that opens the dropdown
SelectValue - Displays the selected value or placeholder
SelectContent - The dropdown menu container
SelectItem - Individual option items
SelectLabel - Optional group labels
SelectSeparator - Visual separator between groups
SelectGroup - Groups related items together

Props

Select

Prop	Type	Default	Description
`value`	`string`	-	Controlled value
`defaultValue`	`string`	-	Uncontrolled default value
`onValueChange`	`(value: string) => void`	-	Callback when value changes
`disabled`	`boolean`	`false`	Whether the select is disabled
`name`	`string`	-	Form field name
`required`	`boolean`	`false`	Whether the field is required

SelectTrigger

Prop	Type	Default	Description
`size`	`"sm" \| "default"`	`"default"`	Size variant
`className`	`string`	-	Additional CSS classes
All standard button props	-	-	Accepts all HTML button attributes

SelectValue

Prop	Type	Default	Description
`placeholder`	`string`	-	Placeholder when nothing selected
`className`	`string`	-	Additional CSS classes

SelectContent

Prop	Type	Default	Description
`position`	`"popper" \| "item-aligned"`	`"item-aligned"`	Positioning mode
`align`	`"start" \| "center" \| "end"`	`"center"`	Content alignment
`sideOffset`	`number`	-	Offset from trigger
`className`	`string`	-	Additional CSS classes
All standard `div` props	-	-	Accepts HTML div attributes

SelectItem

Prop	Type	Default	Description
`value`	`string`	-	Item value (required)
`disabled`	`boolean`	`false`	Whether the item is disabled
`className`	`string`	-	Additional CSS classes

Styling

Selects use the following design tokens:

Border: border-input
Background: bg-input/20 (dark: bg-input/30)
Text: text-foreground
Placeholder: text-muted-foreground
Focus ring: ring-ring with ring-offset-background
Disabled: opacity-50 with cursor-not-allowed

Accessibility

Full keyboard navigation support
ARIA attributes for screen readers
Focus management
Proper label association
Escape key to close
Arrow keys to navigate options

Best Practices

Always use labels: Pair every select with a label for accessibility
Provide placeholders: Use helpful placeholder text
Group related items: Use SelectGroup and SelectLabel for organization
Handle disabled states: Disable options that aren't available
Consider search: For long lists, consider using Combobox instead

Next Steps

Learn about Combobox for searchable selects
Explore NativeSelect for native HTML selects
Check out Form Components for other form elements