Select

A select lets users choose one option from a list that opens in a popup, or several with multiple. The trigger shows the selected option, or a placeholder while none is selected, and a press on it opens the list. By default, the popup opens over the trigger, so that the selected option lines up with the text in the trigger. items on Select gives the select the label of each value, so the trigger shows the label of the selected option instead of its raw value. SelectGroup provides the padding around the options, so the options sit in a SelectGroup even when the list has a single group. The trigger is as wide as its content, and the popup takes the width of the trigger but is at least 9rem wide. The trigger has no visible label of its own, so the examples name it with aria-label.

UsageCopy Anchor Link

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

const stores = [
	{ label: "Basel", value: "basel" },
	{ label: "Bern", value: "bern" },
	{ label: "Geneva", value: "geneva" },
	{ label: "Lucerne", value: "lucerne" },
	{ label: "Zurich", value: "zurich" },
];

export function SelectDefault() {
	return (
		<Select items={stores}>
			<SelectTrigger aria-label="Store">
				<SelectValue placeholder="Select a store"/>
			</SelectTrigger>
			<SelectContent>
				<SelectGroup>
					{stores.map((store) => (
						<SelectItem key={store.value} value={store.value}>{store.label}</SelectItem>
					))}
				</SelectGroup>
			</SelectContent>
		</Select>
	);
}

ExamplesCopy Anchor Link

With GroupsCopy Anchor Link

Long lists often combine options of different kinds, for example product categories from several departments. Related options sit together in a SelectGroup, and a SelectLabel names each group, so users find an option faster and assistive technology reads the name of its group as well.

With SeparatorCopy Anchor Link

Labels alone may not keep groups apart clearly enough, especially in a long list that users scan quickly. Placed between two groups, SelectSeparator marks where one set of options ends and the next begins, so users recognize the change of kind without reading every label.

With IconCopy Anchor Link

In a dense form, users should recognize what a field asks for before they read its value. An icon in the trigger gives that hint at a glance and stays in place whichever option users select.

SmallCopy Anchor Link

Toolbars, filter bars and table headers leave little room for a field. With size set to "sm" on SelectTrigger, the select claims less space and fits into such a row without outweighing the content it filters.

Default SizeCopy Anchor Link

Forms, dialogs and settings pages give a field the room it needs. There the trigger keeps the size "default", which applies whenever no other size is set, so a select lines up with the inputs around it.

ScrollableCopy Anchor Link

Certain choices span more options than the screen can show at once, such as every supplier in an assortment. The list then stays within the available space and scrolls. Wherever further options lie beyond the visible ones, a button at that end scrolls on while the pointer rests on it, and users can also type the first characters of an option to move straight to it.

MultipleCopy Anchor Link

Reports and filters often cover more than one option at a time, such as several regions in a sales comparison. Through multiple, users select as many options as they need, the popup stays open between their choices, and another press on a selected option removes it again.

Without Item AlignmentCopy Anchor Link

Opening over the trigger keeps the selected option where users were looking, yet it covers the field itself. With alignItemWithTrigger set to false on SelectContent, the popup opens beside the trigger instead, below it unless side says otherwise, so the field and its surroundings stay in view while users choose.

Top SideCopy Anchor Link

At the bottom of a panel or in a footer bar, the room for a list lies above the select. Set to "top", side opens the popup there once alignItemWithTrigger is false, because a popup that lies over the trigger ignores the side.

Right SideCopy Anchor Link

Along the left edge of a screen, in a sidebar for instance, the open space lies to the right of the select. Together with alignItemWithTrigger set to false, side set to "right" lets the list unfold into that space instead of covering what lies below the trigger.

Left SideCopy Anchor Link

Panels on the right edge of a screen, such as a details pane, leave their room to the left. Once alignItemWithTrigger is false, side set to "left" opens the popup on that side, while the values "inline-start" and "inline-end" follow the reading direction for products in right-to-left languages.

Default ValueCopy Anchor Link

Many forms begin with a choice that most users keep, such as the current week in a sales report. Through defaultValue the select starts with that option selected, and users change it only when they need another one.

Controlled ValueCopy Anchor Link

Other parts of the interface often depend on the selection, such as a dashboard that filters its figures by the chosen category. The application then holds the value through value and onValueChange, so it can reset or change the selection from elsewhere while the select always shows the current choice.

Controlled Open StateCopy Anchor Link

Another part of the interface may need to open the list, for example a keyboard shortcut or a guided step that points users to a missing choice. Through open and onOpenChange, the application holds whether the popup is open, while users still open and close it as usual.

DisabledCopy Anchor Link

Until an earlier choice is made, a select may have nothing meaningful to offer, such as sizes before a product is chosen. Marked as disabled, it neither opens nor changes its value, keyboard focus passes over it, and the form leaves its value out.

Disabled ItemCopy Anchor Link

Single options are sometimes unavailable for a while, such as a promotion that has not started yet. With disabled on its SelectItem, the option remains in the list, so users still see the full range, but they cannot select it.

Read-OnlyCopy Anchor Link

Some values are decided elsewhere, by head office or by an automated process, yet users still need to know them. Through readOnly, users open the list and read every option without changing the selection, and the form still submits the value.

InvalidCopy Anchor Link

A required choice that is missing, or one that no longer fits the rest of a form, should stand out before users submit. With aria-invalid on SelectTrigger, the field signals the error and assistive technology announces it, so users find the field that needs their attention.

API ReferenceCopy Anchor Link

SelectCopy Anchor Link

SelectTriggerCopy Anchor Link

SelectValueCopy Anchor Link

SelectContentCopy Anchor Link

SelectGroupCopy Anchor Link

SelectLabelCopy Anchor Link

SelectItemCopy Anchor Link

SelectSeparatorCopy Anchor Link

SelectScrollUpButtonCopy Anchor Link

SelectScrollDownButtonCopy Anchor Link