Select

Displays a list of options for the user to pick from—triggered by a button.

When to use

Use Select for a small, finite list of options (~2-15) where the user picks exactly one and search/filtering is unnecessary. For larger lists, async data, or any single-select where typing to filter is helpful, use Combobox. For picking multiple options, use Multi Select.

When a Select is rendered inside Field.Item, wrap Select.Root in Field.Control. Field.Control flows the generated id, name, aria-describedby, aria-errormessage, and aria-invalid through to the focusable Select.Trigger: the name lands on Select.Root (so the hidden form input picks it up) and the trigger reads the ARIA props from context.

1import { Field } from "@ngrok/mantle/field";2import { Select } from "@ngrok/mantle/select";3 4<Field.Item className="max-w-64" name="fruits">⋯5	<Field.Label>Fruits</Field.Label>6	<Field.Control>⋯7		<Select.Root>⋯8			<Select.Trigger>⋯9				<Select.Value placeholder="Select a fruit" />10			</Select.Trigger>11			<Select.Content width="trigger">⋯12				<Select.Group>⋯13					<Select.Label>Fruits</Select.Label>14					<Select.Item value="apple">Apple</Select.Item>15					<Select.Item value="banana">Banana</Select.Item>16					<Select.Item value="blueberry">Blueberry</Select.Item>17					<Select.Item value="grapes">Grapes</Select.Item>18					<Select.Item value="pineapple">Pineapple</Select.Item>19				</Select.Group>20				<Select.Separator />21				<Select.Group>⋯22					<Select.Label>Vegetables</Select.Label>23					<Select.Item value="carrot">Carrot</Select.Item>24					<Select.Item value="cucumber">Cucumber</Select.Item>25					<Select.Item value="lettuce">Lettuce</Select.Item>26					<Select.Item value="tomato">Tomato</Select.Item>27					<Select.Item value="zucchini">⋯28						<p>Zucchini</p>29						<p>Ex sit voluptate incididunt pariatur velit consequat reprehenderit.</p>30					</Select.Item>31				</Select.Group>32			</Select.Content>33		</Select.Root>34	</Field.Control>35</Field.Item>;

Composition

Compose the parts of a Select together to build your own:

Select.Root├── Select.Trigger│   └── Select.Value└── Select.Content    ├── Select.Group    │   ├── Select.Label    │   └── Select.Item    └── Select.Separator

Polymorphism

Select.Trigger, Select.Item, Select.Group, Select.Label, and Select.Separator accept asChild, which swaps the part's default element for your single child while keeping its styling and the select's keyboard and selection behavior. Select.Label asChild helps when a group heading must be a specific element for the page's outline. Select.Trigger asChild makes your own control the combobox, and Select.Item asChild makes your own element the option. Each part renders its own chrome beside your children (the trigger's caret, the item's check indicator), so Radix clones your single child as the part's element and moves the label span and that chrome inside it. The translation guarantee holds on both paths.

Select.Root is a state provider that renders no DOM, so it takes no asChild.

Select.Content takes no asChild, and its props type omits it. It renders the scroll buttons and the viewport around your items, so there is no single child for a slot to clone. Style it with className instead.

Layering and z-index

Select.Content renders at Tailwind z-50, Mantle's float tier. When composed inside an open Dialog, AlertDialog, or Sheet, it portals into that overlay's positioner and paints above the overlay that owns it. Outside every overlay, it portals to document.body, below the overlay tier (z-60). When sibling floats share a container, the most recently mounted float paints on top.

Select does not render a backdrop. Modal layers such as Dialog, Sheet, and AlertDialog do render backdrops, so stacking those layers compounds the dim and blur effect on the layers underneath.

Examples

With TanStack Form

Use @tanstack/react-form with zod to keep Select.Root controlled. Wrap the root in Field.Control so the generated name, id, and ARIA props reach the select trigger and hidden input.

1import { Button } from "@ngrok/mantle/button";2import { Field, toErrorMessages } from "@ngrok/mantle/field";3import { Select } from "@ngrok/mantle/select";4import { useForm } from "@tanstack/react-form";5import { z } from "zod";6 7export const formSchema = z.object({⋯8	fruit: z.string().min(1, "Choose a fruit."),9});10function Example() {⋯11	const defaultValues = {⋯12		fruit: "",13	};14	const form = useForm({⋯15		defaultValues,16		validators: {⋯17			onSubmit: formSchema,18		},19		onSubmit: ({ value }) => {⋯20			// Handle form submission here21		},22	});23 24	return (25		<form⋯26			onSubmit={(event) => {⋯27				event.preventDefault();28				event.stopPropagation();29				void form.handleSubmit();30			}}31		>32			<form.Field name="fruit">⋯33				{(field) => (34					<Field.Item name={field.name}>⋯35						<Field.Label>Fruit</Field.Label>36						<Field.Control>⋯37							<Select.Root⋯38								value={field.state.value}39								onBlur={field.handleBlur}40								onValueChange={field.handleChange}41							>42								<Select.Trigger>⋯43									<Select.Value placeholder="Select a fruit" />44								</Select.Trigger>45								<Select.Content width="trigger">⋯46									<Select.Item value="apple">Apple</Select.Item>47									<Select.Item value="banana">Banana</Select.Item>48									<Select.Item value="blueberry">Blueberry</Select.Item>49								</Select.Content>50							</Select.Root>51						</Field.Control>52						<Field.Errors messages={toErrorMessages(field.state.meta.errors)} />53					</Field.Item>54				)}55			</form.Field>56			<Button type="submit" appearance="filled" intent="neutral">⋯57				Submit58			</Button>59		</form>60	);61}

Raw usage and validation

Use Select.Root directly when you don't need Field label, helper, or error wiring. Set validation on Select.Root to render a success, warning, or error state outside of a field.

1import { Select } from "@ngrok/mantle/select";2 3<Select.Root>4	<Select.Trigger className="max-w-64" aria-label="Fruit">5		<Select.Value placeholder="Select a fruit" />6	</Select.Trigger>7	<Select.Content width="trigger">8		<Select.Item value="apple">Apple</Select.Item>9		<Select.Item value="banana">Banana</Select.Item>10		<Select.Item value="blueberry">Blueberry</Select.Item>11	</Select.Content>12</Select.Root>13 14<Select.Root validation="error">15	<Select.Trigger className="max-w-64" aria-label="Fruit with error">16		<Select.Value placeholder="Select a fruit" />17	</Select.Trigger>18	<Select.Content width="trigger">19		<Select.Item value="apple">Apple</Select.Item>20		<Select.Item value="banana">Banana</Select.Item>21		<Select.Item value="blueberry">Blueberry</Select.Item>22	</Select.Content>23</Select.Root>24 25<Select.Root validation="success">26	<Select.Trigger className="max-w-64" aria-label="Fruit with success">27		<Select.Value placeholder="Select a fruit" />28	</Select.Trigger>29	<Select.Content width="trigger">30		<Select.Item value="apple">Apple</Select.Item>31		<Select.Item value="banana">Banana</Select.Item>32		<Select.Item value="blueberry">Blueberry</Select.Item>33	</Select.Content>34</Select.Root>35 36<Select.Root validation="warning">37	<Select.Trigger className="max-w-64" aria-label="Fruit with warning">38		<Select.Value placeholder="Select a fruit" />39	</Select.Trigger>40	<Select.Content width="trigger">41		<Select.Item value="apple">Apple</Select.Item>42		<Select.Item value="banana">Banana</Select.Item>43		<Select.Item value="blueberry">Blueberry</Select.Item>44	</Select.Content>45</Select.Root>;

Custom selected value

By default the selected item's text renders in the trigger. To render something different, control the select and pass children instead.

1import { Select } from "@ngrok/mantle/select";2import { useState } from "react";3 4function Example() {⋯5	const [value, setValue] = useState("");6 7	return (8		<Select.Root value={value} onValueChange={setValue}>⋯9			<Select.Trigger className="w-45">⋯10				<Select.Value placeholder="Select a fruit">⋯11					{value === "apple" ? <>🍎 Apple</> : <>🍑 Peach</>}12				</Select.Value>13			</Select.Trigger>14			<Select.Content width="trigger">⋯15				<Select.Item value="apple">Apple</Select.Item>16				<Select.Item value="peach">Peach</Select.Item>17			</Select.Content>18		</Select.Root>19	);20}

Rich item labels

An item takes any content, and the trigger shows the selected label as-is. When the list needs two lines and the trigger must stay on one line, control the select and render a compact value with Select.Value children. Both renders stay safe on a translated page: React removes the label span or the value span, never a bare text node.

1import { Icon } from "@ngrok/mantle/icon";2import { Select } from "@ngrok/mantle/select";3import { GlobeHemisphereWestIcon } from "@phosphor-icons/react/GlobeHemisphereWest";4import { useState } from "react";5 6const regions = [⋯7	{ value: "us", label: "United States", host: "us.ngrok.com" },8	{ value: "eu", label: "Europe", host: "eu.ngrok.com" },9	{ value: "ap", label: "Asia Pacific", host: "ap.ngrok.com" },10	{ value: "au", label: "Australia", host: "au.ngrok.com" },11];12 13function Example() {⋯14	const [value, setValue] = useState("us");15	const region = regions.find((candidate) => candidate.value === value);16 17	return (18		<Select.Root value={value} onValueChange={setValue}>⋯19			<Select.Trigger className="w-72" aria-label="Region">⋯20				<Select.Value placeholder="Select a region">⋯21					{region && (22						<span className="flex items-center gap-2">⋯23							<Icon svg={<GlobeHemisphereWestIcon />} className="size-4" />24							<span>{region.label}</span>25							<span className="text-muted text-xs" translate="no">⋯26								{region.host}27							</span>28						</span>29					)}30				</Select.Value>31			</Select.Trigger>32			<Select.Content width="trigger">⋯33				{regions.map((region) => (34					<Select.Item key={region.value} value={region.value} icon={<GlobeHemisphereWestIcon />}>⋯35						<span className="flex flex-col">⋯36							<span>{region.label}</span>37							<span className="text-muted text-xs" translate="no">⋯38								{region.host}39							</span>40						</span>41					</Select.Item>42				))}43			</Select.Content>44		</Select.Root>45	);46}

Untranslatable labels

When a label is an ID, a path, a filename, or a key, set translate="no" on the item. A browser translation engine then skips the row and the copy the trigger shows, so the reader copies the right string.

1import { Select } from "@ngrok/mantle/select";2 3<Select.Root defaultValue="us-east-1">⋯4	<Select.Trigger className="w-56" aria-label="AWS region">⋯5		<Select.Value placeholder="Select a region" />6	</Select.Trigger>7	<Select.Content width="trigger">⋯8		<Select.Item value="us-east-1" translate="no">⋯9			us-east-110		</Select.Item>11		<Select.Item value="eu-west-1" translate="no">⋯12			eu-west-113		</Select.Item>14		<Select.Item value="ap-southeast-2" translate="no">⋯15			ap-southeast-216		</Select.Item>17	</Select.Content>18</Select.Root>;

API Reference

The Select components are built on top of Radix Select.

Select.Root

Displays a list of options for the user to pick from—triggered by a button.

Select.Content renders at Tailwind z-50, Mantle's float tier. When composed inside an open Dialog, AlertDialog, or Sheet, it portals into that overlay's positioner and paints above the overlay that owns it. Outside every overlay, it portals to document.body, below the overlay tier (z-60). When sibling floats share a container, the most recently mounted float paints on top.

Set validation on Select.Root when the whole select has an explicit state; this root-level state is forwarded to the trigger and takes precedence over ambient field-level validation from Field.Item.

Rendered Field.Errors or Field.ErrorList still force the trigger into the error state because Field.Control sets aria-invalid="true" on the focusable trigger, and an explicit invalid ARIA value always wins. If a non-error Select.Root state needs to win even when errors are rendered, pass validation on Field.Item to suppress the inferred error.

All props from Radix Select.Root, plus:

Select.Trigger

The button that toggles the Select. The Select.Content will position itself adjacent to the trigger.

When composing with Field.Item, wrap Select.Root (not the trigger) in Field.Control. The generated id, name, and aria-invalid flow onto Select.Root (so the hidden form input picks up the field name), and the trigger reads aria-describedby / aria-errormessage from FieldControlContext. Validation resolves from explicit Select.Root, then Select.Trigger, then the nearest Field.Item.

children render inside a <span data-slot="select-trigger-label">. The caret is a permanent element sibling, so without the span a bare text child is never a lone child: a browser translation engine reparents that text node, and the removal React runs when the child changes shape or goes away throws. The span is display: contents, so Select.Value stays a flex item of the trigger and keeps its gap. Browser translation covers the mechanism and the rules your own components need.

Select.Value is now a grandchild of the trigger, so a [&>span] class of your own reaches the wrapper instead. Match the part's own variant: [&>[data-slot=select-trigger-label]>span]:line-clamp-none. That form shares the default's variant prefix, so tailwind-merge drops the default instead of shipping both. A bare [&>span]:line-clamp-none lands on the wrapper, and line-clamp sets display, which gives the wrapper a box and takes Select.Value out of the trigger's flex row.

All props from Radix Select.Trigger, plus:

Data attributes

Select.Value

The part that reflects the selected value. Renders the selected item's text by default. For more control, control the select and pass your own children. Do not style this part: under Select.Content position="item-aligned", Radix measures its box to align the open list over the selected item. Pass placeholder for the text to show when the select has no value.

placeholder renders inside a <span data-slot="select-placeholder">, your own children inside a <span data-slot="select-value-label">, and the selected item's text arrives inside the select-item-label span from Select.Item. Each span is display: contents, so it adds no box and changes no layout. React removes one of those spans whenever the value changes, and an element removal is safe on a translated page. A browser translation engine reparents text nodes, and a removal aimed at a reparented text node throws. Browser translation covers the mechanism.

Radix Select.Value props.

Data attributes

Select.Content

The component that pops out when the Select is open as a portal adjacent to the Select.Trigger button. It contains a scrolling viewport of the select items. position defaults to "popper", so the list opens below the trigger instead of over the selected item.

Select.Content renders at Tailwind z-50, Mantle's float tier. When composed inside an open Dialog, AlertDialog, or Sheet, it portals into that overlay's positioner and paints above the overlay that owns it. Outside every overlay, it portals to document.body, below the overlay tier (z-60). When sibling floats share a container, the most recently mounted float paints on top.

All props from Radix Select.Content, except asChild, plus:

Data attributes

Select.Group

A group of related options within a select menu. Similar to an html optgroup element. Pair it with Select.Label, which gives the group its accessible name.

Radix Select.Group props.

Data attributes

Select.Separator

Used to visually separate items in the select. Composed from Mantle Separator.

Data attributes

Select.Item

An option within a select menu. Similar to an html option element. Has a required value prop. When a user selects this item, Select.Root passes that value to its onValueChange handler. Displays the children as the option's text. Pass icon to render an icon before the text.

children render inside a <span data-slot="select-item-label">. Radix portals that span into Select.Value while the item is selected and removes it when the selection changes. The span exists so the node React removes is an element: a browser translation engine reparents text nodes, and a removal aimed at one throws. The span is display: contents, so it adds no box in the list or in the trigger, and your own item content stays the direct layout child of the value. To style it as a box, set a display of your own on it first. Browser translation covers the mechanism and the rule your own components need.

When the label is an ID, a path, a filename, or a key, set translate="no" on the item. The attribute also rides on the label span, so the copy the trigger shows stays untranslated too.

All props from Radix Select.Item, plus:

Data attributes

Select.Label

Used to render the label of a group. It won't be focusable using arrow keys. Pair it with Select.Group — the label gives the group its accessible name.

Radix Select.Label props.

Data attributes