Select

Reach for Select when a value comes from a short, fixed set of options and the user picks exactly one: a time zone, a plan, a deploy region. It renders a button that opens a listbox, keeps the chosen label in the trigger, and submits through a hidden input when it sits in a form. It has typeahead but no filtering — for lists long enough to need a search field, use Combobox instead.

Pass items to <Select.Root> so <Select.Value> renders the option's label instead of the raw value — without it the trigger above would read Europe/London. The popup opens over the trigger with the selected row's text sitting on the trigger's text; that is alignItemWithTrigger, on by default — see Placement for the trade-off and how to turn it off.

Import

import { Select } from "@forte-ui/react";

Examples

Labelling

<Select.Label> is the labelling pattern to reach for. It renders a <div> wired to the trigger with aria-labelledby, so clicking it focuses the trigger without opening the popup.

Grouped options

<Select.Group> renders role="group" and takes its accessible name from the <Select.GroupLabel> inside it, so screen readers announce the heading along with its members. The group label is indented past the check-mark column so its text lines up with the item text.

Placement

By default the popup overlaps the trigger, with the selected row's text landing on the trigger's own text — alignItemWithTrigger, which is what a native <select> does on macOS. Pass alignItemWithTrigger={false} to drop the popup below the trigger instead, the way a Menu opens.

Aligned placement puts the current value under the pointer at the moment the popup opens, so re-picking the same option is a click without a journey. It costs the trigger: the popup covers it, and it needs room above and below, which is why Base UI drops back to side placement for touch input and when the viewport is too tight — so it is the mode users see least consistently. Menu placement never covers the trigger and behaves identically everywhere, which is what you want for a select sitting in a dense toolbar or next to a value the user is comparing against.

The two modes animate differently, and that is not a knob. Aligned mode has no side to rise from, so it unfurls out of the selected row with --transform-origin pinned there; side placement unfolds away from the trigger edge and adds a short slide when it lands on an inline side. side, align, sideOffset and alignOffset apply only to the second — Base UI ignores all four while the popup is aligned.

Sizes

size sets the trigger's height, inline padding and font size — nothing else. The popup is unaffected: items keep their own type scale and their --forte-target-min (24px) minimum row height whatever size the trigger is.

Variants

variant changes only how much weight the trigger carries: outline reads as a form control, soft as a filled field, ghost as an inline affordance.

Disabled items

A disabled item stays in the list and stays announced, so the option remains discoverable — it just cannot be chosen. Typeahead skips it, matching what a native <select> does. Say in the item's own text why it is unavailable; greying alone tells the user nothing.

Accessibility

The highlight does not wrap: Arrow Down on the last item and Arrow Up on the first stay put rather than cycling.

data-highlighted is the focus analogue for items. Base UI moves real DOM focus between options with a roving tabindex, so the highlighted item is the focused element, and pointer hover sets the same attribute (highlightItemOnHover on <Select.Root>, on by default — set it to false if you need CSS :hover to be distinguishable from the focused state). Style rows off [data-highlighted] rather than :hover, or keyboard users get no highlight at all.

The scroll arrows at the top and bottom of a long popup are a pointer convenience only. Base UI does not render them for touch input, marks them aria-hidden, and hides them once the list cannot scroll further — the list itself scrolls by wheel, drag, keyboard and typeahead, so no item is ever reachable only through an arrow. Turning them off with scrollArrows={false} removes nothing but the affordance.

Theming

Every --forte-select-* property below is declared on the surface that owns it, and an element's own declaration beats an inherited value — so setting one on :root, on a theme scope or on any ancestor has no effect. The popup is portalled to <body> as well, so an ancestor of the trigger is not even in its tree. Set each property on the part that declares it, through that part's className (an unlayered rule beats the library's @layer forte.components, whatever its specificity) or an inline style:

• Select.Label declares the four label-* properties.
• Select.Trigger declares every trigger-* property.
• Select.Popup declares the popup-* properties plus --forte-select-item-px, --forte-select-item-gap and --forte-select-item-indicator-size — the layout knobs the list, the items and the group labels read but never redeclare, so the popup is the right place to set them.
• positionerClassName reaches --forte-select-z-index and --forte-select-positioner-min-height, and nothing else: those two are the only properties declared on the positioner.
• Select.Item declares --forte-select-item-fg, --forte-select-item-bg-highlighted, --forte-select-item-fg-highlighted, --forte-select-item-fg-selected and --forte-select-item-font-size.
• --forte-select-backdrop-z-index, --forte-select-list-padding-y and --forte-select-scroll-arrow-size are declared on the backdrop, the list and the scroll arrows — elements Select.Popup renders internally and exposes no class name for, so they cannot be retargeted from outside.

The global tokens these resolve to — --forte-color-*, --forte-control-*, --forte-radius-*, --forte-space-* — are the exception: the component only reads those and never redeclares them, so re-pointing them on :root or on a theme scope does re-skin every select.

API reference

Select.Root

Groups every part and owns the value and open state. It renders no DOM element, so it takes neither className nor ref, and it forwards Base UI's own Select.Root props unchanged — including value, defaultValue, onValueChange, items, multiple, name, disabled, readOnly, required, modal and highlightItemOnHover. Both generics are preserved, so <Select.Root<Theme>> types onValueChange and defaultValue for you.

Select.Label

Select.Trigger

Select.Value

Select.Icon

Select.Popup

Renders the whole floating half of the anatomy — portal, optional backdrop, positioner, popup, scroll arrows and the scrolling list — as one part.

Select.Item

Select.Group

Select.GroupLabel

Select.Separator