Skip to content

Design system

Documentation

DesignComponents / Select

Components / Select

Stable

Select

Use Select for a predefined value or a short set of values that should open from a compact form trigger.

On this page

Examples

Basic selection

A compact trigger opens a positioned list of predefined values.

Basic Select with a placeholder-capable value

Density

Use sm, md, or lg so the trigger matches the surrounding form rhythm.

Select trigger small, default, and large sizes

Controlled value

Use controlled state when a selected value drives surrounding feature behavior.

Controlled Select preview

Grouped options

Group related choices and keep a disabled option understandable.

Select groups, labels, separator, and disabled item

Multiple selection

Use Base UI multiple mode when the form needs more than one value.

Select with multiple values

Placeholder, disabled, and long list

The trigger and popup remain usable at narrow widths and with many options.

Select placeholder, disabled trigger, and scrollable list

When to use

Use Select when the options are predefined and the list is too long or secondary to keep visible. Use RadioGroup for a small peer set. Add the optional search config to SelectContent when the feature needs a callback-driven search input inside the popup; use Combobox when text entry and option matching are the primary interaction.

Usage

select-basic.tsx
"use client";

import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@phuctech/ui/components/select";

export function Example() {
  return (
    <Select defaultValue="activity">
      <SelectTrigger aria-label="Sort projects"><SelectValue placeholder="Sort projects" /></SelectTrigger>
      <SelectContent>
        <SelectItem value="activity">Recent activity</SelectItem>
        <SelectItem value="name">Name</SelectItem>
        <SelectItem value="owner">Owner</SelectItem>
      </SelectContent>
    </Select>
  );
}

The wrapper exposes Base UI's positioned popup and supports the same render-based composition model as the rest of the library. Pair the trigger with a Field label when it is part of a form.

States

Select states
StateGuidance
PlaceholderUse SelectValue placeholder when no value is selected.
MultipleSet multiple and provide an array value when more than one choice is valid.
Disabled / read-onlyKeep unavailable or inherited values understandable outside the trigger.
Long listThe popup list is bounded by available viewport height and scrolls internally.
Callback searchPass a search config with a query callback, loading/error state, and an explicit no-results state; update SelectItem children from the feature.

API

Component API
PropTypeDefaultDescriptionConstraints
SelectRoot props—Owns value, open state, form semantics, and multiple mode.Use one value model per instance.
SelectTriggerbutton props—Opens the positioned list.Give it an accessible name through FieldLabel or aria-label.
SelectTrigger size"sm" | "md" | "lg""md"Trigger height and padding density.Align with nearby Input and Button sizes.
SelectValuevalue + placeholder—Renders the selected label or placeholder.Keep placeholder text actionable and concise.
SelectContentpopup props + side/align + search?side=bottomPortaled, scroll-bounded options popup with optional callback search.The application filters or replaces SelectItem children; the component does not fetch.
search.query / defaultQuery / onQueryChangestring / string / callbackuncontrolled emptyControls the visible search text.When query is controlled, pair it with onQueryChange.
search.onSearch / searchDebounceMs(query: string) => void / number— / 350Reports a trimmed query after a short delay.Delay is clamped to 300–500 ms and duplicate consecutive queries are skipped; the feature owns requests and race protection.
search.loading / error / noResultsboolean / ReactNode / booleanfalse / — / falseDisplays externally owned status, error, or settled empty text.Set noResults only when the current result set is empty.
SelectItemvalue + item props—One selectable option.Use unique values and visible labels.
SelectGroup / SelectGroupLabel / SelectSeparatorcompound parts—Organize related options.Keep groups short and meaningful.

Tokens

Component tokens
TokenRoleEffective valueUsage
--size-control-sm / md / lgTrigger height1.75 / 2 / 2.25remThe size prop aligns Select with Input and Button.
--color-bg-elevated / --elevation-popoverPopup surfacesemantic rolesSeparates the portaled list from the page.
--motion-duration-fastPopup motion120msKeeps opening and closing brief.

Accessibility

  • Open the list with Enter, Space, or Arrow keys and move with the arrow keys.
  • When search is enabled, its input has a programmatic name and Arrow Down moves focus into the first available option.
  • Escape closes the popup and returns focus to the trigger.
  • Use a visible label or an explicit aria-label; placeholder text alone is not a label.
  • Field connects Select to labels and errors.
  • RadioGroup keeps a short set of peer options visible.
  • DropdownMenu is for actions rather than form values.