Select

Preview

Design guidance

Selected options use a trailing checkmark and regular label weight. Their resting background stays transparent; hover and keyboard focus provide the row highlight.

Use Select when the options are known and the user can choose them without searching. Use Combobox when the list needs filtering or text entry. Keep labels short enough for the trigger; longer labels can wrap in the popup while the trigger keeps the full accessible name.

For multiple values, keep a short caller-owned summary in the trigger. The popup stays open while users choose values. For object values, define label and form serialization explicitly, and compare objects by a stable key.

Select.Trigger has two styling variants: ghost and outline (the default). Both keep the same padding and rounded corners. An open trigger retains the shared active surface until its popup closes. Ghost has a transparent resting surface and a subtle hover fill; outline keeps a visible field border. Use compact with either variant to fit the trigger to its value.

Installation

Install Select and its declared source dependencies from the Ghost UI registry.

npx shadcn@latest add https://ghost-ui.com/r/select.json

Basic usage

This complete string-value example keeps the trigger and popup in the same Root. The selected row shows a trailing checkmark.

1234567891011121314151617181920212223import { ChevronDown } from "lucide-react";
import { Select } from "@/components/ui/select";

const formats = [{ value: "text", label: "Plain text" }, { value: "markdown", label: "Markdown" }];

<Select.Root items={formats} defaultValue="text">
  <Select.Trigger aria-label="Output format">
    <Select.Value placeholder="Choose a format" />
    <Select.Icon><ChevronDown aria-hidden="true" /></Select.Icon>
  </Select.Trigger>
  <Select.Portal>
    <Select.Positioner>
      <Select.Popup aria-label="Output formats">
        {formats.map((item) => (
          <Select.Item key={item.value} value={item.value}>
            <Select.ItemText>{item.label}</Select.ItemText>
            <Select.ItemIndicator />
          </Select.Item>
        ))}
      </Select.Popup>
    </Select.Positioner>
  </Select.Portal>
</Select.Root>

Structures

Root owns the value and hidden form input. The Trigger contains the current value and an optional icon. Positioner controls popup placement; Popup contains options, optional groups, and optional scroll affordances. Put Field.Label and Field.Error around Select when the caller needs a visible field label or validation message.

Examples

Ghost

Use variant="ghost" for a quiet control in a toolbar or composer. Hover adds a subtle background inside the padded, rounded trigger.

Outline

Use variant="outline" when the choice needs a visible field boundary. This is the default when variant is omitted.

Compact trigger

Use compact independently from the outline appearance when the trigger should fit its value.

Align the selected option

Opt into selected-item alignment when the open list should line up with the displayed value.

Grouped options

Use Group and GroupLabel to organize related options into labeled sections. Compose Separator between groups. This example keeps the trigger wide enough for its longest option, so its width stays the same when the value changes.

Select multiple items

Set multiple to select more than one item. The caller owns the selected-value summary in the trigger.

Select an object value

Provide a display label, serialized form value, and stable equality function for object options.

Scroll a long option list

Use List and scroll arrows when options exceed the available popup height. Select keeps the choices in one scrollable list.

Disable the whole Select

Keep the selected value visible while the caller prevents changes.

Explain an unavailable option

Disable one choice only when the caller can explain why it is unavailable.

Show a required validation error

Compose Select with Field for the caller-owned label, required form value, and error message.

Wrap long option names

The trigger truncates a long value while preserving its full accessible name. Popup option labels can wrap.

Empty options

Use a disabled trigger and a caller-owned message when the option list is empty.

API reference

The component preserves Base UI 1.8.0 Root generics, refs, render composition, and controlled or uncontrolled values. items supplies option labels to Select.Value. For multiple selection, value and onValueChange use string[] (or the chosen item value array). For object values, use itemToStringLabel, itemToStringValue, and isItemEqualToValue when object identity can change.

Root, Trigger, Positioner, Popup, Item, and the remaining parts preserve Base UI attributes, refs, state, and render support. ItemIndicator is optional. It defaults to the same SVG Check icon as Combobox. The shared theme controls indicator size, stroke and color; pass children to use a custom icon. List and scroll arrows are optional and useful for long lists. Select owns option selection; the caller owns labels, helper text, availability messages, and selected-value summaries.