Select

Displays a list of options for the user to pick from—triggered by a button.

Preview Code
Interactive

Features

  • Can be controlled or uncontrolled.
  • Supports items, labels, and groups of items.
  • Focus is fully managed.
  • Full keyboard navigation.
  • Supports Right to Left direction.
  • Typeahead support.

Installation

Install the component from your command line.

Angular CLInpmpnpmyarnbun
Bash
ng g @ng-cn/core:c select

Anatomy

Import all parts and piece them together.

Typescript
import {
  Select,
  SelectTrigger,
  SelectValue,
  SelectContent,
  SelectItem,
  SelectGroup,
  SelectLabel,
  SelectSeparator
} from '@/ui/select';
Html
<Select>
  <SelectTrigger>
    <SelectValue />
  </SelectTrigger>
  <SelectContent>
    <SelectGroup>
      <SelectLabel />
      <SelectItem />
    </SelectGroup>
    <SelectSeparator />
  </SelectContent>
</Select>

API Reference

Root

Contains all the parts of a select.

PropTypeDefault
value string —
The controlled value of the select.
defaultValue string —
The value of the select when initially rendered.
open boolean —
The controlled open state of the select.
defaultOpen boolean false
The open state of the select when initially rendered.
disabled boolean false
When true, prevents the user from interacting with select.
name string —
The name of the select. Submitted with its owning form as part of a name/value pair.
required boolean false
When true, indicates that the user must select a value before the owning form can be submitted.

Trigger

The button that toggles the select.

PropTypeDefault
class string —
Additional CSS classes to apply.

Data Attributes

AttributeValues
[data-state]"open" | "closed"
[data-disabled]Present when disabled
[data-placeholder]Present when placeholder is shown

Value

The part that reflects the selected value.

PropTypeDefault
placeholder string —
The content that will be rendered when no value or defaultValue is set.

Content

The component that pops out when the select is open.

PropTypeDefault
position 'item-aligned' | 'popper' 'item-aligned'
The positioning mode. item-aligned aligns with the selected item, popper positions like a popover.
side 'top' | 'right' | 'bottom' | 'left' 'bottom'
The preferred side when position is popper.
sideOffset number 0
The distance in pixels from the trigger.
align 'start' | 'center' | 'end' 'start'
The preferred alignment when position is popper.
class string —
Additional CSS classes to apply.

Data Attributes

AttributeValues
[data-state]"open" | "closed"
[data-side]"top" | "right" | "bottom" | "left"
[data-align]"start" | "center" | "end"

Item

The component that contains the select items.

PropTypeDefault
value *string —
The value given as data when submitted with a name.
disabled boolean false
When true, prevents the user from selecting the item.
class string —
Additional CSS classes to apply.

Data Attributes

AttributeValues
[data-state]"checked" | "unchecked"
[data-highlighted]Present when highlighted
[data-disabled]Present when disabled

Group

Used to group multiple items.

PropTypeDefault
class string —
Additional CSS classes to apply.

Label

Used to render the label of a group.

PropTypeDefault
class string —
Additional CSS classes to apply.

Separator

Used to visually separate items in the select.

PropTypeDefault
class string —
Additional CSS classes to apply.

Examples

Basic

A simple select with a few options.

Html
<Select>
  <SelectTrigger class="w-[180px]">
    <SelectValue placeholder="Select a fruit" />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="apple">Apple</SelectItem>
    <SelectItem value="banana">Banana</SelectItem>
    <SelectItem value="orange">Orange</SelectItem>
  </SelectContent>
</Select>

With groups

Group related items together.

Html
<Select>
  <SelectTrigger class="w-[200px]">
    <SelectValue placeholder="Select a timezone" />
  </SelectTrigger>
  <SelectContent>
    <SelectGroup>
      <SelectLabel>North America</SelectLabel>
      <SelectItem value="est">Eastern Standard Time (EST)</SelectItem>
      <SelectItem value="cst">Central Standard Time (CST)</SelectItem>
      <SelectItem value="pst">Pacific Standard Time (PST)</SelectItem>
    </SelectGroup>
    <SelectSeparator />
    <SelectGroup>
      <SelectLabel>Europe</SelectLabel>
      <SelectItem value="gmt">Greenwich Mean Time (GMT)</SelectItem>
      <SelectItem value="cet">Central European Time (CET)</SelectItem>
    </SelectGroup>
  </SelectContent>
</Select>

Controlled

Control the select state from outside.

Html
// In your component:
selectedFruit = signal('');

// In template:
<Select [value]="selectedFruit()" (valueChange)="selectedFruit.set($event)">
  <SelectTrigger class="w-[180px]">
    <SelectValue placeholder="Select a fruit" />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="apple">Apple</SelectItem>
    <SelectItem value="banana">Banana</SelectItem>
  </SelectContent>
</Select>

<p>Selected: {{ selectedFruit() }}</p>

With form

Use with Angular forms.

Html
<form [formGroup]="form">
  <Select name="fruit" formControlName="fruit" [required]="true">
    <SelectTrigger class="w-[180px]">
      <SelectValue placeholder="Select a fruit" />
    </SelectTrigger>
    <SelectContent>
      <SelectItem value="apple">Apple</SelectItem>
      <SelectItem value="banana">Banana</SelectItem>
    </SelectContent>
  </Select>
</form>

Accessibility

Adheres to the Listbox WAI-ARIA design pattern .

Keyboard Interactions

KeyDescription
Space When focus is on trigger, opens/closes the select.
Enter When focus is on trigger, opens the select. When focus is on item, selects it.
ArrowDown When focus is on trigger, opens the select. When open, moves focus to next item.
ArrowUp When open, moves focus to previous item.
Home When open, moves focus to first item.
End When open, moves focus to last item.
Escape Closes the select.
A-Z / a-z When open, moves focus to item starting with typed character.