Select

When to UseCopy Anchor Link

• to choose one option from a short, fixed list, such as payment terms or a currency
• when an option has more than text, like a currency code next to its name
• as a control joined to an Input in a Button Group, for example a currency before an amount

When Not to UseCopy Anchor Link

• for a list long enough to need a search (use a Combobox)
• to let the browser render the list (use a Native Select)
• for a few options that can all be shown on the page (use a Radio Group or a Segmented Control)
• to offer actions (use a Dropdown Menu)

AnatomyCopy Anchor Link

SelectTrigger adds the caret, SelectItem adds a check at the end of the selected option, and SelectContent renders the portal and the popup, so you don’t need to add them. The popup’s padding is set on SelectGroup, so place every item in a group, even when the group has no label.

SizesCopy Anchor Link

Set size on SelectTrigger.

An Input is 32px tall and has no other size, so use default for a Select next to one. See Sizing for the rule on controls in a row.

BehaviorCopy Anchor Link

By default, a Select is modal while its list is open: Base UI locks the page’s scroll and prevents clicks from reaching the page. If you want the page to stay interactive, set modal={false} on Select.

PositionCopy Anchor Link

By default, the list opens below the trigger and is aligned with its start edge. If the list doesn’t fit there, Base UI moves it to another side. The list is as wide as the trigger, with a minimum width of 144px. To change its position, use side, sideOffset, align, and alignOffset on SelectContent.

If alignItemWithTrigger is set, the list opens over the trigger, with the selected option on top of the value. This is the default in Base UI, and it is off in Summit.

OverflowCopy Anchor Link

By default, the trigger is as wide as its value. If you set a width and the value is longer than the trigger, the value is truncated to one line. If the list is taller than the space available next to the trigger, it scrolls inside the popup. SelectScrollUpButton and SelectScrollDownButton are rendered only when alignItemWithTrigger is set.

ContentCopy Anchor Link

AccessibilityCopy Anchor Link

Base UI’s Select sets the roles, moves focus into the list, and returns it to the trigger. You provide the name.

KeyboardCopy Anchor Link

RequirementsCopy Anchor Link

InstallationCopy Anchor Link

npx shadcn@latest add @summit/select

UsageCopy Anchor Link

To show the label of the selected option in SelectValue, pass the options to items on Select. If items isn’t set, SelectValue shows the raw value.

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

const terms = [
    { value: 'net-15', label: 'Net 15' },
    { value: 'net-30', label: 'Net 30' },
];

<Select items={terms}>
    <SelectTrigger aria-label="Payment terms" className="w-48">
        <SelectValue placeholder="Choose payment terms" />
    </SelectTrigger>
    <SelectContent>
        <SelectGroup>
            {terms.map(({ value, label }) => (
                <SelectItem key={value} value={value}>
                    {label}
                </SelectItem>
            ))}
        </SelectGroup>
    </SelectContent>
</Select>;

With GroupsCopy Anchor Link

To name a SelectGroup, add a SelectLabel to it. To divide two groups, place a SelectSeparator between them.

<SelectContent>
    <SelectGroup>
        <SelectLabel>Americas</SelectLabel>
        <SelectItem value="USD">US dollar</SelectItem>
        <SelectItem value="CAD">Canadian dollar</SelectItem>
    </SelectGroup>
    <SelectSeparator />
    <SelectGroup>
        <SelectLabel>Europe</SelectLabel>
        <SelectItem value="EUR">Euro</SelectItem>
        <SelectItem value="CHF" disabled>
            Swiss franc
        </SelectItem>
    </SelectGroup>
</SelectContent>

In a FieldCopy Anchor Link

In a Field, the FieldLabel names the Select, and a click on the label opens the list.

import { Field, FieldDescription, FieldLabel } from '@/components/ui/field';

<Field>
    <FieldLabel>Payment terms</FieldLabel>
    <Select items={terms}>
        <SelectTrigger>
            <SelectValue placeholder="Choose payment terms" />
        </SelectTrigger>
    </Select>
    <FieldDescription>Applied to new invoices for this client.</FieldDescription>
</Field>;

API ReferenceCopy Anchor Link

The parts accept the props of their matching parts in Base UI’s Select, where SelectContent is Select.Popup and SelectLabel is Select.GroupLabel. See the Base UI Select documentation for items, value, onValueChange, name, multiple, modal, and OffsetFunction.

SelectTriggerCopy Anchor Link

SelectContentCopy Anchor Link