Report an issue

Select

Enables users to choose from a list of options presented in a dropdown.

	<script lang="ts">
  import { Select } from "bits-ui";
  import CaretUpDown from "phosphor-svelte/lib/CaretUpDown";
  import Check from "phosphor-svelte/lib/Check";
  import Palette from "phosphor-svelte/lib/Palette";
  import CaretDoubleDown from "phosphor-svelte/lib/CaretDoubleDown";
  import CaretDoubleUp from "phosphor-svelte/lib/CaretDoubleUp";
 
  const themes = [
    { value: "light-monochrome", label: "Light Monochrome" },
    { value: "dark-green", label: "Dark Green" },
    { value: "svelte-orange", label: "Svelte Orange" },
    { value: "punk-pink", label: "Punk Pink" },
    { value: "ocean-blue", label: "Ocean Blue" },
    { value: "sunset-red", label: "Sunset Red" },
    { value: "forest-green", label: "Forest Green" },
    { value: "lavender-purple", label: "Lavender Purple" },
    { value: "mustard-yellow", label: "Mustard Yellow" },
    { value: "slate-gray", label: "Slate Gray" },
    { value: "neon-green", label: "Neon Green" },
    { value: "coral-reef", label: "Coral Reef" },
    { value: "midnight-blue", label: "Midnight Blue" },
    { value: "crimson-red", label: "Crimson Red" },
    { value: "mint-green", label: "Mint Green" },
    { value: "pastel-pink", label: "Pastel Pink" },
    { value: "golden-yellow", label: "Golden Yellow" },
    { value: "deep-purple", label: "Deep Purple" },
    { value: "turquoise-blue", label: "Turquoise Blue" },
    { value: "burnt-orange", label: "Burnt Orange" }
  ];
 
  let value = $state("");
  const selectedLabel = $derived(
    themes.find((theme) => theme.value === value)?.label
  );
</script>
 
<Select.Root name="hello" bind:value>
  <Select.Trigger
    class="inline-flex h-input w-[296px] select-none items-center rounded-9px border border-border-input bg-background px-[11px] text-sm transition-colors placeholder:text-foreground-alt/50"
    aria-label="Select a theme"
  >
    <Palette class="mr-[9px] size-6 text-muted-foreground" />
    {#if selectedLabel}
      <Select.Value class="text-sm">
        {selectedLabel}
      </Select.Value>
    {:else}
      <Select.Value class="text-sm" placeholder="Select a theme" />
    {/if}
    <CaretUpDown class="ml-auto size-6 text-muted-foreground" />
  </Select.Trigger>
  <Select.Portal>
    <Select.Content
      class="focus-override z-50 max-h-96 w-full min-w-[296px] rounded-xl border border-muted bg-background px-1 py-3 shadow-popover outline-none"
      sideOffset={8}
      preventScroll={false}
    >
      <Select.ScrollUpButton class="flex w-full items-center justify-center">
        <CaretDoubleUp class="size-3" />
      </Select.ScrollUpButton>
      <Select.Viewport class="p-1">
        {#each themes as theme}
          <Select.Item
            class="focus-override flex h-10 w-full select-none items-center rounded-button py-3 pl-5 pr-1.5 text-sm outline-none transition-all duration-75 focus:outline-none focus-visible:outline-none data-[highlighted]:bg-muted"
            value={theme.value}
          >
            {#snippet children({ selected })}
              <Select.ItemText>
                {theme.label}
              </Select.ItemText>
              {#if selected}
                <span class="ml-auto">
                  <Check />
                </span>
              {/if}
            {/snippet}
          </Select.Item>
        {/each}
      </Select.Viewport>
      <Select.ScrollDownButton
        class="flex w-full items-center justify-center py-1"
      >
        <CaretDoubleDown class="size-3" />
      </Select.ScrollDownButton>
    </Select.Content>
  </Select.Portal>
</Select.Root>

Overview

The Select component can be used as a replacement for the native <select> element in your application. It provides a more flexible and customizable way to select an option from a list of options. The component offers a variety of features, such as typeahead, keyboard navigation, scroll up/down buttons, and more.

Structure

	<script lang="ts">
	import { Select } from "bits-ui";
</script>
 
<Select.Root>
	<Select.Trigger>
		<Select.Value />
	</Select.Trigger>
	<Select.Portal>
		<Select.Content>
			<Select.ScrollUpButton />
			<Select.Viewport>
				<Select.Item>
					<Select.ItemText />
				</Select.Item>
				<Select.Group>
					<Select.GroupLabel />
					<Select.Item>
						<Select.ItemText />
					</Select.Item>
				</Select.Group>
			</Select.Viewport>
			<Select.ScrollDownButton />
		</Select.Content>
	</Select.Portal>
</Select.Root>

Reusable Components

As you can see from the structure above, there are a number of pieces that make up the Select component. These pieces are provided to give you maximum flexibility and customization options, but can be a burden to write out everywhere you need to use a Select in your application.

To ease this burden, it's recommended to create your own reusable Select component that wraps the primitives and provides a more convenient API for your use cases.

Here's an example of how you might create a reusable MySelect component that receives a list of options and renders each of them as an item.

MySelect.svelte
	<script lang="ts">
	import { Select, type WithoutChildren } from "bits-ui";
 
	type Props = WithoutChildren<Select.RootProps> & {
		placeholder?: string;
		items: { value: string; label: string; disabled?: boolean }[];
		contentProps?: WithoutChildren<Select.ContentProps>;
		// any other specific component props if needed
	};
 
	let { value = $bindable(""), items, contentProps, placeholder, ...restProps }: Props = $props();
 
	const selectedLabel = $derived(items.find((item) => item.value === value)?.label);
</script>
 
<Select.Root bind:value {...restProps}>
	<Select.Trigger>
		{#if selectedLabel}
			<Select.Value>
				{selectedLabel}
			</Select.Value>
		{:else}
			<Select.Value {placeholder} />
		{/if}
	</Select.Trigger>
	<Select.Portal>
		<Select.Content {...contentProps}>
			<Select.ScrollUpButton>up</Select.ScrollUpButton>
			<Select.Viewport>
				{#each items as { value, label, disabled } (value)}
					<Select.Item {value} textValue={label} {disabled}>
						{#snippet children({ selected })}
							{selected ? "✅" : ""}
							<Select.ItemText>
								{item.label}
							</Select.ItemText>
						{/snippet}
					</Select.Item>
				{/each}
			</Select.Viewport>
			<Select.ScrollDownButton>down</Select.ScrollDownButton>
		</Select.Content>
	</Select.Portal>
</Select.Root>

You can then use the MySelect component throughout your application like so:

	<script lang="ts">
	import MySelect from "$lib/components/MySelect.svelte";
 
	const items = [
		{ value: "apple", label: "Apple" },
		{ value: "banana", label: "Banana" },
		{ value: "cherry", label: "Cherry" },
	];
 
	let fruit = $state("apple");
</script>
 
<MySelect {items} bind:value={fruit} />

Managing Value State

The value represents the currently selected item/option within the select menu. Bits UI provides flexible options for controlling and synchronizing the Select's value state.

Two-Way Binding

Use the bind:value directive for effortless two-way synchronization between your local state and the Select's internal state.

	<script lang="ts">
	import { Select } from "bits-ui";
	let myValue = $state<string>("");
</script>
 
<button onclick={() => (myValue = "apple")}> Apple </button>
 
<Select.Root bind:value={myValue}>
	<!-- ... -->
</Select.Root>

This setup enables toggling the Select via the custom button and ensures the local myValue state updates when the Select changes through any internal means (e.g., clicking on an item's button).

Change Handler

You can also use the onValueChange prop to update local state when the Select's value state changes. This is useful when you don't want two-way binding for one reason or another, or you want to perform additional logic when the Select changes.

	<script lang="ts">
	import { Select } from "bits-ui";
	let myValue = $state<string>("");
</script>
 
<Select.Root
	value={myValue}
	onValueChange={(value) => {
		myValue = value;
		// additional logic here.
	}}
>
	<!-- ... -->
</Select.Root>

Managing Open State

The open state represents whether or not the select menu is open. Bits UI provides flexible options for controlling and synchronizing the Select's open state.

Two-Way Binding

Use the bind:open directive for effortless two-way synchronization between your local state and the Select's internal state.

	<script lang="ts">
	import { Select } from "bits-ui";
	let isOpen = $state(false);
</script>
 
<button onclick={() => (open = true)}> Open select </button>
 
<Select.Root bind:open={isOpen}>
	<!-- ... -->
</Select.Root>

This setup enables toggling the Select via the custom button and ensures the local isOpen state updates when the Select changes through any internal means e.g. clicking on the trigger or outside the content.

Change Handler

You can also use the onOpenChange prop to update local state when the Select's open state changes. This is useful when you don't want two-way binding for one reason or another, or you want to perform additional logic when the Select changes.

	<script lang="ts">
	import { Select } from "bits-ui";
	let isOpen = $state(false);
</script>
 
<Select.Root
	open={isOpen}
	onOpenChange={(open) => {
		isOpen = open;
		// additional logic here.
	}}
>
	<!-- ... -->
</Select.Root>

Positioning

The Select component supports two different positioning strategies for the content. The default positioning strategy is floating, which uses Floating UI to position the content relative to the trigger, similar to other popover-like components. If you prefer a more native-like experience, you can set the position prop to item-aligned, which will position the content relative to the trigger, similar to a native <select> element.

	<Select.Content position="floating">
	<!-- ... -->
</Select.Content>
 
<!-- or -->
 
<Select.Content position="item-aligned">
	<!-- ... -->
</Select.Content>

Here's an example of both strategies in action:

position="floating"
position="item-aligned"

NOTE: When using the "item-aligned" positioning strategy, the props related to configuring Floating UI on the Select.Content component will be ignored.

HTML Forms

The Select component is designed to work seamlessly with HTML forms. You can use the name prop to associate the select with a form field.

	<Select.Root name="theme">
	<!-- ... -->
</Select.Root>

Server-side Rendering

To accomplish some of the nice features of the Select component, such as typeahead while the select content is closed and the trigger is focused, we leverage portals to send items into the Select.Value component.

Portals only work client-side, so if you are using SvelteKit with SSR, you'll need to handle the case where a default value is provided, otherwise, there will be a flicker of the placeholder value before the default value is portalled into the Select.Value component. We're demonstrating this in the featured demo at the top of this page, but here's an example of how you might handle this:

+page.svelte
	<script lang="ts">
	// default value is provided via page data from a load function
	let { data } = $props();
 
	let options = [
		{ value: "apple", label: "Apple" },
		{ value: "banana", label: "Banana" },
		{ value: "cherry", label: "Cherry" },
	];
 
	let value = $state(data.fruit);
 
	const selectedLabel = $derived(options.find((option) => option.value === data.fruit)?.label);
</script>
 
<Select.Root value={data.fruit} onValueChange={(v) => (data.fruit = v)}>
	<Select.Trigger>
		{#if selectedLabel}
			<Select.Value>
				{selectedLabel}
			</Select.Value>
		{:else}
			<Select.Value placeholder="Select a fruit" />
		{/if}
	</Select.Trigger>
	<!-- ... other select components -->
</Select.Root>

Scroll Lock

By default, when a user opens the select, scrolling outside the content will be disabled. You can override this behavior by setting the preventScroll prop to false.

	<Select.Content preventScroll={false}>
	<!-- ... -->
</Select.Content>

Viewport

The Select.Viewport component is used to determine the size of the select menu in order to determine whether or not the scroll up and down buttons should be rendered. If you wish to set a minimum/maxmimum height for the select content, you should apply it to the Select.Viewport component.

Scroll Up/Down Buttons

The Select.ScrollUpButton and Select.ScrollDownButton components are used to render the scroll up and down buttons when the select content is larger than the viewport.

Multiple Select

The Select component does not support multiple selections. If you're looking for a multi-select component, check out the Listbox component.

API Reference

Select.Root

The root select component which manages & scopes the state of the select.

Property Type Description
value bindable prop
string

The value of the currently selected select item.

Default: ''
onValueChange
function

A callback that is fired when the select menu's value changes.

Default: undefined
open bindable prop
boolean

The open state of the select menu.

Default: false
onOpenChange
function

A callback that is fired when the select menu's open state changes.

Default: undefined
disabled
boolean

Whether or not the select menu is disabled.

Default: false
autocomplete
string

The autocomplete attribute of the select.

Default: undefined
dir
enum

The reading direction of the app.

Default: ltr
form
string

The form attribute of the select.

Default: undefined
name
string

The name to apply to the hidden input element for form submission.

Default: undefined
required
boolean

Whether or not the select menu is required.

Default: false
children
Snippet

The children content to render.

Default: undefined

Select.Trigger

The button element which toggles the select menu's open state.

Property Type Description
disabled
boolean

Whether or not the select menu trigger is disabled.

Default: false
ref bindable prop
HTMLButtonElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See delegation docs for more information.

Default: undefined
Data Attribute Value Description
data-state
enum

The dropdown menu's open state.

data-disabled
''

Present when the trigger is disabled.

data-select-trigger
''

Present on the trigger element.

Select.Content

The content/menu element which contains the select menu's items.

Property Type Description
position
enum

The positioning strategy to use for the content. If set to 'item-aligned', the content will be positioned relative to the trigger, similar to a native select. If set to floating, the content will use Floating UI to position itself similar to other popover-like components.

Default: floating
dir
enum

The reading direction of the app.

Default: ltr
side
enum

The preferred side of the anchor to render the floating element against when open. Will be reversed when collisions occur.

Default: bottom
sideOffset
number

The distance in pixels from the anchor to the floating element.

Default: 0
align
enum

The preferred alignment of the anchor to render the floating element against when open. This may change when collisions occur.

Default: start
alignOffset
number

The distance in pixels from the anchor to the floating element.

Default: 0
arrowPadding
number

The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision.

Default: 0
avoidCollisions
boolean

When true, overrides the side and align options to prevent collisions with the boundary edges.

Default: true
collisionBoundary
union

A boundary element or array of elements to check for collisions against.

Default: undefined
collisionPadding
union

The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision.

Default: 0
sticky
enum

The sticky behavior on the align axis. 'partial' will keep the content in the boundary as long as the trigger is at least partially in the boundary whilst 'always' will keep the content in the boundary regardless.

Default: partial
hideWhenDetached
boolean

When true, hides the content when it is detached from the DOM. This is useful for when you want to hide the content when the user scrolls away.

Default: true
updatePositionStrategy
enum

The strategy to use when updating the position of the content. When 'optimized' the content will only be repositioned when the trigger is in the viewport. When 'always' the content will be repositioned whenever the position changes.

Default: optimized
strategy
enum

The positioning strategy to use for the floating element. When 'fixed' the element will be positioned relative to the viewport. When 'absolute' the element will be positioned relative to the nearest positioned ancestor.

Default: fixed
preventScroll
boolean

When true, prevents the body from scrolling when the content is open. This is useful when you want to use the content as a modal.

Default: true
onInteractOutside
function

Callback fired when an outside interaction event completes, which is either a pointerup, mouseup, or touchend event, depending on the user's input device. You can call event.preventDefault() to prevent the default behavior of handling the outside interaction.

Default: undefined
onInteractOutsideStart
function

Callback fired when an outside interaction event starts, which is either a pointerdown, mousedown, or touchstart event, depending on the user's input device. You can call event.preventDefault() to prevent the continuation of the outside interaction.

Default: undefined
onFocusOutside
function

Callback fired when focus leaves the dismissable layer. You can call event.preventDefault() to prevent the default behavior on focus leaving the layer.

Default: undefined
interactOutsideBehavior
enum

The behavior to use when an interaction occurs outside of the floating content. 'close' will close the content immediately. 'ignore' will prevent the content from closing. 'defer-otherwise-close' will defer to the parent element if it exists, otherwise it will close the content. 'defer-otherwise-ignore' will defer to the parent element if it exists, otherwise it will ignore the interaction.

Default: close
onEscapeKeydown
function

Callback fired when an escape keydown event occurs in the floating content. You can call event.preventDefault() to prevent the default behavior of handling the escape keydown event.

Default: undefined
escapeKeydownBehavior
enum

The behavior to use when an escape keydown event occurs in the floating content. 'close' will close the content immediately. 'ignore' will prevent the content from closing. 'defer-otherwise-close' will defer to the parent element if it exists, otherwise it will close the content. 'defer-otherwise-ignore' will defer to the parent element if it exists, otherwise it will ignore the interaction.

Default: close
onMountAutoFocus
function

Event handler called when auto-focusing the content as it is mounted. Can be prevented.

Default: undefined
onDestroyAutoFocus
function

Event handler called when auto-focusing the content as it is destroyed. Can be prevented.

Default: undefined
trapFocus
boolean

Whether or not to trap the focus within the content when open.

Default: true
preventOverflowTextSelection
boolean

When true, prevents the text selection from overflowing the bounds of the element.

Default: true
forceMount
boolean

Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animation library for the content.

Default: false
loop
boolean

Whether or not the select menu should loop through items when reaching the end.

Default: false
ref bindable prop
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See delegation docs for more information.

Default: undefined
Data Attribute Value Description
data-select-content
''

Present on the content element.

Select.Item

A select item, which must be a child of the Select.Content component.

Property Type Description
value required prop
string

The value of the select item.

Default: undefined
textValue
string

The text value of the select item, which is used for typeahead purposes.

Default: undefined
disabled
boolean

Whether or not the select item is disabled. This will prevent interaction/selection.

Default: false
ref bindable prop
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See delegation docs for more information.

Default: undefined
Data Attribute Value Description
data-state
enum

The state of the item.

data-highlighted
''

Present when the item is highlighted, via keyboard navigation or hover.

data-disabled
''

Present when the item is disabled.

data-select-item
''

Present on the item element.

Select.Value

A representation of the select menu's value, which is typically displayed in the trigger.

Property Type Description
placeholder
string

A placeholder value to display when no value is selected.

Default: undefined
ref bindable prop
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See delegation docs for more information.

Default: undefined
Data Attribute Value Description
data-select-value
''

Present on the value element.

data-placeholder
''

Present when the placeholder is being displayed (there isn't a value selected). You can use this to style the placeholder differently than the selected value.

Select.Viewport

An optional element to track the scroll position of the select for rendering the scroll up/down buttons.

Property Type Description
ref bindable prop
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See delegation docs for more information.

Default: undefined
Data Attribute Value Description
data-select-viewport
''

Present on the viewport element.

Select.ScrollUpButton

An optional scroll up button element to improve the scroll experience within the select. Should be used in conjunction with the Select.Viewport component.

Property Type Description
ref bindable prop
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See delegation docs for more information.

Default: undefined
Data Attribute Value Description
data-select-scroll-up-button
''

Present on the scroll up button element.

Select.ScrollDownButton

An optional scroll down button element to improve the scroll experience within the select. Should be used in conjunction with the Select.Viewport component.

Property Type Description
ref bindable prop
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See delegation docs for more information.

Default: undefined
Data Attribute Value Description
data-select-scroll-down-button
''

Present on the scroll down button element.

Select.Group

An accessible group of select menu items.

Property Type Description
ref bindable prop
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See delegation docs for more information.

Default: undefined
Data Attribute Value Description
data-select-group
''

Present on the group element.

Select.GroupLabel

A label for the select menu which will be skipped when navigating with the keyboard. This must be a child of the Select.Group component.

Property Type Description
ref bindable prop
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See delegation docs for more information.

Default: undefined
Data Attribute Value Description
data-select-group-label
''

Present on the label element.

Select.Separator

A visual separator for use between select items or groups.

Property Type Description
ref bindable prop
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See delegation docs for more information.

Default: undefined
Data Attribute Value Description
data-separator-root
''

Present on the separator element.

Select.Arrow

An optional arrow element which points to the trigger when open.

Property Type Description
width
number

The width of the arrow in pixels.

Default: 8
height
number

The height of the arrow in pixels.

Default: 8
ref bindable prop
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See delegation docs for more information.

Default: undefined
Data Attribute Value Description
data-arrow
''

Present on the arrow element.