Native Solid 2 fork. Original documentation and designs © WorkOS; historical posts retain their original context.

Select

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

Styling solution Source file Download runnable sandbox

import { omit, type ComponentProps } from "solid-js";
import { Select } from "@radix-solid/primitives";
import { CheckIcon, ChevronDownIcon, ChevronUpIcon } from "@radix-solid/icons";
import styles from "./styles.module.css";
const SelectDemo = () => <Select.Root>
		<Select.Trigger class={styles.Trigger} aria-label="Food">
			<Select.Value placeholder="Select a fruit…" />
			<Select.Icon class={styles.Icon}>
				<ChevronDownIcon />
			</Select.Icon>
		</Select.Trigger>
		<Select.Portal>
			<Select.Content class={styles.Content}>
				<Select.ScrollUpButton class={styles.ScrollButton}>
					<ChevronUpIcon />
				</Select.ScrollUpButton>
				<Select.Viewport class={styles.Viewport}>
					<Select.Group>
						<Select.Label class={styles.Label}>Fruits</Select.Label>
						<SelectItem value="apple">Apple</SelectItem>
						<SelectItem value="banana">Banana</SelectItem>
						<SelectItem value="blueberry">Blueberry</SelectItem>
						<SelectItem value="grapes">Grapes</SelectItem>
						<SelectItem value="pineapple">Pineapple</SelectItem>
					</Select.Group>

					<Select.Separator class={styles.Separator} />

					<Select.Group>
						<Select.Label class={styles.Label}>Vegetables</Select.Label>
						<SelectItem value="aubergine">Aubergine</SelectItem>
						<SelectItem value="broccoli">Broccoli</SelectItem>
						<SelectItem value="carrot" disabled>
							Carrot
						</SelectItem>
						<SelectItem value="courgette">Courgette</SelectItem>
						<SelectItem value="leek">Leek</SelectItem>
					</Select.Group>

					<Select.Separator class={styles.Separator} />

					<Select.Group>
						<Select.Label class={styles.Label}>Meat</Select.Label>
						<SelectItem value="beef">Beef</SelectItem>
						<SelectItem value="chicken">Chicken</SelectItem>
						<SelectItem value="lamb">Lamb</SelectItem>
						<SelectItem value="pork">Pork</SelectItem>
					</Select.Group>
				</Select.Viewport>
				<Select.ScrollDownButton class={styles.ScrollButton}>
					<ChevronDownIcon />
				</Select.ScrollDownButton>
			</Select.Content>
		</Select.Portal>
	</Select.Root>;
const SelectItem = function SelectItem(p: Extract<ComponentProps<typeof Select.Item>, {
  asChild?: false;
}>) {
  return <Select.Item class={[styles.Item, p.class]} {...omit(p, "children", "class")} ref={p.ref}>
			<Select.ItemText>{p.children}</Select.ItemText>
			<Select.ItemIndicator class={styles.ItemIndicator}>
				<CheckIcon />
			</Select.ItemIndicator>
		</Select.Item>;
};
export default SelectDemo;

Features

Can be controlled or uncontrolled.
Offers 2 positioning modes.
Supports items, labels, groups of items.
Focus is fully managed.
Full keyboard navigation.
Supports custom placeholder.
Typeahead support.
Supports Right to Left direction.

Anatomy

Import all parts and piece them together.

import { Select } from "@radix-solid/primitives";
export default () => <Select.Root>
		<Select.Trigger>
			<Select.Value />
			<Select.Icon />
		</Select.Trigger>

		<Select.Portal>
			<Select.Content>
				<Select.ScrollUpButton />
				<Select.Viewport>
					<Select.Item value="first">
						<Select.ItemText />
						<Select.ItemIndicator />
					</Select.Item>

					<Select.Group>
						<Select.Label />
						<Select.Item value="second">
							<Select.ItemText />
							<Select.ItemIndicator />
						</Select.Item>
					</Select.Group>

					<Select.Separator />
				</Select.Viewport>
				<Select.ScrollDownButton />
				<Select.Arrow />
			</Select.Content>
		</Select.Portal>
	</Select.Root>;

API Reference

Root

Contains all the parts of a select.

Prop	Type	Default
`defaultValue`	`string`	—
`value`	`string`	—
`onValueChange`	`function`	—
`defaultOpen`	`boolean`	—
`open`	`boolean`	—
`onOpenChange`	`function`	—
`dir`	`enum`	—
`name`	`string`	—
`disabled`	`boolean`	—
`required`	`boolean`	—

Trigger

The button that toggles the select. The Select.Content will position itself by aligning over the trigger.

Prop	Type	Default
`asChild`	`boolean`	`false`

Data attribute	Values
`[data-state]`	`"open" \| "closed"`
`[data-disabled]`	Present when disabled
`[data-placeholder]`	Present when has placeholder

The part that reflects the selected value. By default the selected item's text will be rendered. if you require more control, you can instead control the select and pass your own children. It should not be styled to ensure correct positioning. An optional placeholder prop is also available for when the select has no value.

Prop	Type	Default
`asChild`	`boolean`	`false`
`placeholder`	`Element`	—

Icon

A small icon often displayed next to the value as a visual affordance for the fact it can be open. By default renders ▼ but you can use your own icon via asChild or use children.

Prop	Type	Default
`asChild`	`boolean`	`false`

Portal

When used, portals the content part into the body.

Prop	Type	Default
`forceMount`	`boolean`	—
`container`	`HTMLElement`	`document.body`

Content

The component that pops out when the select is open.

Prop	Type	Default
`asChild`	`boolean`	`false`
`forceMount`	`boolean`	—
`onCloseAutoFocus`	`function`	—
`onEscapeKeyDown`	`function`	—
`onPointerDownOutside`	`function`	—
`position`	`enum`	`"item-aligned"`
`side`	`enum`	`"bottom"`
`sideOffset`	`number`	`0`
`align`	`enum`	`"start"`
`alignOffset`	`number`	`0`
`avoidCollisions`	`boolean`	`true`
`collisionBoundary`	`Boundary`	`[]`
`collisionPadding`	`number \| Padding`	`10`
`arrowPadding`	`number`	`0`
`sticky`	`enum`	`"partial"`
`hideWhenDetached`	`boolean`	`false`

Data attribute	Values
`[data-state]`	`"open" \| "closed"`
`[data-side]`	`"left" \| "right" \| "bottom" \| "top"`
`[data-align]`	`"start" \| "end" \| "center"`

CSS Variable	Description
`--radix-select-content-transform-origin`	The `transform-origin` computed from the content and arrow positions/offsets. Only present when `position="popper"`.
`--radix-select-content-available-width`	The remaining width between the trigger and the boundary edge. Only present when `position="popper"`.
`--radix-select-content-available-height`	The remaining height between the trigger and the boundary edge. Only present when `position="popper"`.
`--radix-select-trigger-width`	The width of the trigger. Only present when `position="popper"`.
`--radix-select-trigger-height`	The height of the trigger. Only present when `position="popper"`.

Viewport

The scrolling viewport that contains all of the items.

Prop	Type	Default
`asChild`	`boolean`	`false`

Item

The component that contains the select items.

Prop	Type	Default
`asChild`	`boolean`	`false`
`value*`	`string`	—
`disabled`	`boolean`	—
`textValue`	`string`	—

Data attribute	Values
`[data-state]`	`"checked" \| "unchecked"`
`[data-highlighted]`	Present when highlighted
`[data-disabled]`	Present when disabled

ItemText

The textual part of the item. It should only contain the text you want to see in the trigger when that item is selected. It should not be styled to ensure correct positioning.

Prop	Type	Default
`asChild`	`boolean`	`false`

ItemIndicator

Renders when the item is selected. You can style this element directly, or you can use it as a wrapper to put an icon into, or both.

Prop	Type	Default
`asChild`	`boolean`	`false`

ScrollUpButton

An optional button used as an affordance to show the viewport overflow as well as functionally enable scrolling upwards.

Prop	Type	Default
`asChild`	`boolean`	`false`

ScrollDownButton

An optional button used as an affordance to show the viewport overflow as well as functionally enable scrolling downwards.

Prop	Type	Default
`asChild`	`boolean`	`false`

Group

Used to group multiple items. use in conjunction with Select.Label to ensure good accessibility via automatic labelling.

Prop	Type	Default
`asChild`	`boolean`	`false`

Label

Used to render the label of a group. It won't be focusable using arrow keys.

Prop	Type	Default
`asChild`	`boolean`	`false`

Separator

Used to visually separate items in the select.

Prop	Type	Default
`asChild`	`boolean`	`false`

Arrow

An optional arrow element to render alongside the content. This can be used to help visually link the trigger with the Select.Content. Must be rendered inside Select.Content. Only available when position is set to popper.

Prop	Type	Default
`asChild`	`boolean`	`false`
`width`	`number`	`10`
`height`	`number`	`5`

Examples

Change the positioning mode

By default, Select will behave similarly to a native MacOS menu by positioning Select.Content relative to the active item. If you would prefer an alternative positioning approach similar to Popover or DropdownMenu then you can set position to popper and make use of additional alignment options such as side, sideOffset and more.

// index.tsx
import { Select } from "@radix-solid/primitives";
export default () => <Select.Root>
		<Select.Trigger>…</Select.Trigger>
		<Select.Portal>
			<Select.Content position="popper" sideOffset={5}>
				…
			</Select.Content>
		</Select.Portal>
	</Select.Root>;

Constrain the content size

When using position="popper" on Select.Content, you may want to constrain the width of the content so that it matches the trigger width. You may also want to constrain its height to not exceed the viewport.

We expose several CSS custom properties such as --radix-select-trigger-width and --radix-select-content-available-height to support this. Use them to constrain the content dimensions.

// index.tsx
import { Select } from "@radix-solid/primitives";
import "./styles.css";
export default () => <Select.Root>
		<Select.Trigger>…</Select.Trigger>
		<Select.Portal>
			<Select.Content class="SelectContent" position="popper" sideOffset={5}>
				…
			</Select.Content>
		</Select.Portal>
	</Select.Root>;

/* styles.css */
.SelectContent {
	width: var(--radix-select-trigger-width);
	max-height: var(--radix-select-content-available-height);
}

With disabled items

You can add special styles to disabled items via the data-disabled attribute.

// index.tsx
import { Select } from "@radix-solid/primitives";
import "./styles.css";
export default () => <Select.Root>
		<Select.Trigger>…</Select.Trigger>
		<Select.Portal>
			<Select.Content>
				<Select.Viewport>
					<Select.Item value="disabled" class="SelectItem" disabled>
						…
					</Select.Item>
					<Select.Item value="first">…</Select.Item>
					<Select.Item value="second">…</Select.Item>
				</Select.Viewport>
			</Select.Content>
		</Select.Portal>
	</Select.Root>;

/* styles.css */
.SelectItem[data-disabled] {
	color: "gainsboro";
}

With a placeholder

You can use the placeholder prop on Value for when the select has no value. There's also a data-placeholder attribute on Trigger to help with styling.

// index.tsx
import { Select } from "@radix-solid/primitives";
import "./styles.css";
export default () => <Select.Root>
		<Select.Trigger class="SelectTrigger">
			<Select.Value placeholder="Pick an option" />
			<Select.Icon />
		</Select.Trigger>
		<Select.Portal>
			<Select.Content>…</Select.Content>
		</Select.Portal>
	</Select.Root>;

/* styles.css */
.SelectTrigger[data-placeholder] {
	color: "gainsboro";
}

With separators

Use the Separator part to add a separator between items.

<Select.Root>
	<Select.Trigger>…</Select.Trigger>
	<Select.Portal>
		<Select.Content>
			<Select.Viewport>
				<Select.Item value="first">…</Select.Item>
				<Select.Item value="second">…</Select.Item>
				<Select.Item value="third">…</Select.Item>
				<Select.Separator />
				<Select.Item value="fourth">…</Select.Item>
				<Select.Item value="fifth">…</Select.Item>
			</Select.Viewport>
		</Select.Content>
	</Select.Portal>
</Select.Root>

With grouped items

Use the Group and Label parts to group items in a section.

<Select.Root>
	<Select.Trigger>…</Select.Trigger>
	<Select.Portal>
		<Select.Content>
			<Select.Viewport>
				<Select.Group>
					<Select.Label>Label</Select.Label>
					<Select.Item value="first">…</Select.Item>
					<Select.Item value="second">…</Select.Item>
					<Select.Item value="third">…</Select.Item>
				</Select.Group>
			</Select.Viewport>
		</Select.Content>
	</Select.Portal>
</Select.Root>

With complex items

You can use custom content in your items.

import { Select } from "@radix-solid/primitives";
export default () => <Select.Root>
		<Select.Trigger>…</Select.Trigger>
		<Select.Portal>
			<Select.Content>
				<Select.Viewport>
					<Select.Item value="adolfo">
						<Select.ItemText>
							<img src="…" alt="" />
							Adolfo Hess
						</Select.ItemText>
						<Select.ItemIndicator>…</Select.ItemIndicator>
					</Select.Item>
					<Select.Item value="second">…</Select.Item>
					<Select.Item value="third">…</Select.Item>
				</Select.Viewport>
			</Select.Content>
		</Select.Portal>
	</Select.Root>;

Controlling the value displayed in the trigger

By default the trigger will automatically display the selected item ItemText's content. You can control what appears by chosing to put things inside/outside the ItemText part.

If you need more flexibility, you can control the component using value/onValueChange props and passing children to SelectValue. Remember to make sure what you put in there is accessible.

import { createSignal } from "solid-js";
const countries = new Map([
  ["france", "🇫🇷"],
  ["united-kingdom", "🇬🇧"],
  ["spain", "🇪🇸"]
]);
export default () => {
  const [value, setValue] = createSignal("france");
  return <Select.Root value={value()} onValueChange={setValue}>
			<Select.Trigger>
				<Select.Value aria-label={value()}>
					{countries.get(value())}
				</Select.Value>
				<Select.Icon />
			</Select.Trigger>
			<Select.Portal>
			<Select.Content>
				<Select.Viewport>
					<Select.Item value="france">
						<Select.ItemText>France</Select.ItemText>
						<Select.ItemIndicator>…</Select.ItemIndicator>
					</Select.Item>
					<Select.Item value="united-kingdom">
						<Select.ItemText>United Kingdom</Select.ItemText>
						<Select.ItemIndicator>…</Select.ItemIndicator>
					</Select.Item>
					<Select.Item value="spain">
						<Select.ItemText>Spain</Select.ItemText>
						<Select.ItemIndicator>…</Select.ItemIndicator>
					</Select.Item>
				</Select.Viewport>
			</Select.Content>
			</Select.Portal>
		</Select.Root>;
};

With custom scrollbar

The native scrollbar is hidden by default as we recommend using the ScrollUpButton and ScrollDownButton parts for the best UX. If you do not want to use these parts, compose your select with our Scroll Area primitive.

// index.tsx
import { Select, ScrollArea } from "@radix-solid/primitives";
import "./styles.css";
export default () => <Select.Root>
		<Select.Trigger>…</Select.Trigger>
		<Select.Portal>
			<Select.Content>
				<ScrollArea.Root class="ScrollAreaRoot" type="auto">
					<Select.Viewport asChild>{target => target(ScrollArea.Viewport, {
            "class": "ScrollAreaViewport",
            children: <>
							<Select.Item value="first"><Select.ItemText>First item</Select.ItemText></Select.Item>
							<Select.Item value="second"><Select.ItemText>Second item</Select.ItemText></Select.Item>
							<Select.Item value="third"><Select.ItemText>Third item</Select.ItemText></Select.Item>
						</>
          })}</Select.Viewport>
					<ScrollArea.Scrollbar class="ScrollAreaScrollbar" orientation="vertical">
						<ScrollArea.Thumb class="ScrollAreaThumb" />
					</ScrollArea.Scrollbar>
				</ScrollArea.Root>
			</Select.Content>
		</Select.Portal>
	</Select.Root>;

/* styles.css */
.ScrollAreaRoot {
	width: 100%;
	height: 100%;
}

.ScrollAreaViewport {
	width: 100%;
	height: 100%;
}

.ScrollAreaScrollbar {
	width: 4px;
	padding: 5px 2px;
}

.ScrollAreaThumb {
	background: rgba(0, 0, 0, 0.3);
	border-radius: 3px;
}

Decoupling the hidden input

By default, Select.Root renders a visually hidden select for form submission. To recompose, move, or exclude that element, you can build the select from its lower-level parts instead.

Important: These parts are unstable and prefixed with unstable_, so their API may change in a future release.

Select.unstable_Provider provides the select state and accepts the form-related and state props (name, value, defaultValue, onValueChange, etc.).
Select.unstable_BubbleInput is the visually hidden select that Select.Root renders by default. Omit it when you don't need form submission.

import { Select } from "@radix-solid/primitives";
export default () => <Select.unstable_Provider name="fruit">
		<Select.Trigger>
			<Select.Value placeholder="Pick an option" />
			<Select.Icon />
		</Select.Trigger>
		<Select.Portal>
			<Select.Content>{/* Your content */}</Select.Content>
		</Select.Portal>
		<Select.unstable_BubbleInput />
	</Select.unstable_Provider>;

Accessibility

Adheres to the ListBox WAI-ARIA design pattern.

See the W3C Select-Only Combobox example for more information.

Keyboard Interactions

Key	Description
`Space`	When focus is on `Select.Trigger`, opens the select and focuses the selected item. When focus is on an item, selects the focused item.
`Enter`	When focus is on `Select.Trigger`, opens the select and focuses the first item. When focus is on an item, selects the focused item.
`ArrowDown`	When focus is on `Select.Trigger`, opens the select. When focus is on an item, moves focus to the next item.
`ArrowUp`	When focus is on `Select.Trigger`, opens the select. When focus is on an item, moves focus to the previous item.
`Esc`	Closes the select and moves focus to `Select.Trigger`.

Labelling

Use our Label component in order to offer a visual and accessible label for the select.

import { Select, Label } from "@radix-solid/primitives";
export default () => <>
		<Label.Root>
			Country
			<Select.Root>…</Select.Root>
		</Label.Root>

		{/* or */}

		<Label.Root for="country">Country</Label.Root>
		<Select.Root>
			<Select.Trigger id="country">…</Select.Trigger>
			<Select.Portal>
				<Select.Content>…</Select.Content>
			</Select.Portal>
		</Select.Root>
	</>;

Custom APIs

Create your own API by abstracting the primitive parts into your own component.

Abstract down to `Select` and `SelectItem`

This example abstracts most of the parts.

Usage

import { Select, SelectItem } from "./your-select";
export default () => <Select defaultValue="2">
		<SelectItem value="1">Item 1</SelectItem>
		<SelectItem value="2">Item 2</SelectItem>
		<SelectItem value="3">Item 3</SelectItem>
	</Select>;

Implementation

import { omit, type ComponentProps } from "solid-js";
// your-select.tsx

import { Select as SelectPrimitive } from "@radix-solid/primitives";
import { CheckIcon, ChevronDownIcon, ChevronUpIcon } from "@radix-solid/icons";
export const Select = (p: ComponentProps<typeof SelectPrimitive.Root> &
  Pick<ComponentProps<typeof SelectPrimitive.Trigger>, "ref" | "class">) => {
  return <SelectPrimitive.Root {...omit(p, "children", "class", "ref")}>
				<SelectPrimitive.Trigger ref={p.ref} class={p.class}>
					<SelectPrimitive.Value />
					<SelectPrimitive.Icon>
						<ChevronDownIcon />
					</SelectPrimitive.Icon>
				</SelectPrimitive.Trigger>
				<SelectPrimitive.Portal>
					<SelectPrimitive.Content>
						<SelectPrimitive.ScrollUpButton>
							<ChevronUpIcon />
						</SelectPrimitive.ScrollUpButton>
						<SelectPrimitive.Viewport>{p.children}</SelectPrimitive.Viewport>
						<SelectPrimitive.ScrollDownButton>
							<ChevronDownIcon />
						</SelectPrimitive.ScrollDownButton>
					</SelectPrimitive.Content>
				</SelectPrimitive.Portal>
			</SelectPrimitive.Root>;
};
export const SelectItem = (p: Extract<ComponentProps<typeof SelectPrimitive.Item>, {
  asChild?: false;
}>) => {
  return <SelectPrimitive.Item {...omit(p, "children", "class")} ref={p.ref}>
				<SelectPrimitive.ItemText>{p.children}</SelectPrimitive.ItemText>
				<SelectPrimitive.ItemIndicator>
					<CheckIcon />
				</SelectPrimitive.ItemIndicator>
			</SelectPrimitive.Item>;
};