Report an issue

Listbox

A list of options that can be selected by the user.

	<script lang="ts">
  import { Listbox } from "bits-ui";
  import Check from "phosphor-svelte/lib/Check";
  import Palette from "phosphor-svelte/lib/Palette";
  import CaretUpDown from "phosphor-svelte/lib/CaretUpDown";
  import CaretDoubleUp from "phosphor-svelte/lib/CaretDoubleUp";
  import CaretDoubleDown from "phosphor-svelte/lib/CaretDoubleDown";
 
  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<string>("");
  const selectedLabel = $derived(
    value
      ? themes.find((theme) => theme.value === value)?.label
      : "Select a theme"
  );
</script>
 
<Listbox.Root type="single" bind:value>
  <Listbox.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" />
    {selectedLabel}
    <CaretUpDown class="ml-auto size-6 text-muted-foreground" />
  </Listbox.Trigger>
  <Listbox.Portal>
    <Listbox.Content
      class="max-h-96 w-[var(--bits-listbox-trigger-width)] min-w-[var(--bits-listbox-trigger-width)] rounded-xl border border-muted bg-background px-1 py-3 shadow-popover outline-none"
      sideOffset={10}
    >
      <Listbox.ScrollUpButton class="flex w-full items-center justify-center">
        <CaretDoubleUp class="size-3" />
      </Listbox.ScrollUpButton>
      <Listbox.Viewport class="p-1">
        {#each themes as theme, i (i + theme.value)}
          <Listbox.Item
            class="flex h-10 w-full select-none items-center rounded-button py-3 pl-5 pr-1.5 text-sm capitalize outline-none duration-75 data-[highlighted]:bg-muted"
            value={theme.value}
            label={theme.label}
          >
            {#snippet children({ selected })}
              {theme.label}
              {#if selected}
                <div class="ml-auto">
                  <Check />
                </div>
              {/if}
            {/snippet}
          </Listbox.Item>
        {/each}
      </Listbox.Viewport>
      <Listbox.ScrollDownButton class="flex w-full items-center justify-center">
        <CaretDoubleDown class="size-3" />
      </Listbox.ScrollDownButton>
    </Listbox.Content>
  </Listbox.Portal>
</Listbox.Root>

Structure

	<script lang="ts">
	import { Listbox } from "bits-ui";
</script>
 
<Listbox.Root>
	<Listbox.Label />
	<Listbox.Content>
		<Listbox.Group>
			<Listbox.GroupLabel />
			<Listbox.Item />
		</Listbox.Group>
	</Listbox.Content>
</Listbox.Root>

API Reference

Listbox.Root

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

Property Type Description
type required prop
enum

The type of selection to use for the listbox.

Default: undefined
value bindable prop
union

The value of the listbox. When the type is 'single', this should be a string. When the type is 'multiple', this should be an array of strings.

Default: undefined
onValueChange
function

A callback that is fired when the listbox value changes. When the type is 'single', the argument will be a string. When the type is 'multiple', the argument will be an array of strings.

Default: undefined
open bindable prop
boolean

The open state of the listbox menu.

Default: false
onOpenChange
function

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

Default: undefined
disabled
boolean

Whether or not the listbox component is disabled.

Default: false
name
string

The name to apply to the hidden input element for form submission. If provided, a hidden input element will be rendered to submit the value of the listbox.

Default: undefined
required
boolean

Whether or not the listbox menu is required.

Default: false
scrollAlignment
enum

The alignment of the highlighted item when scrolling.

Default: 'nearest'
loop
boolean

Whether or not the listbox menu should loop through items.

Default: false
children
Snippet

The children content to render.

Default: undefined

Listbox.Trigger

A button which toggles the listbox's open state.

Property Type Description
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 listbox's open state.

data-disabled
''

Present when the listbox is disabled.

data-listbox-trigger
''

Present on the trigger element.

Listbox.Content

The element which contains the listbox's items.

Property Type Description
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
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
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
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
dir
enum

The reading direction of the app.

Default: ltr
loop
boolean

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

Default: false
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
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 listbox's open state.

data-listbox-content
''

Present on the content element.

CSS Variable Description
--bits-listbox-content-transform-origin

The transform origin of the listbox content element.

--bits-listbox-content-available-width

The available width of the listbox content element.

--bits-listbox-content-available-height

The available height of the listbox content element.

--bits-listbox-trigger-width

The width of the listbox trigger element.

--bits-listbox-trigger-height

The height of the listbox trigger element.

Listbox.Item

A listbox item, which must be a child of the Listbox.Content component.

Property Type Description
value required prop
string

The value of the item.

Default: undefined
label
string

The label of the item, which is what the list will be filtered by using typeahead behavior.

Default: undefined
disabled
boolean

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

Default: false
onHighlight
function

A callback that is fired when the item is highlighted.

Default: undefined
onUnhighlight
function

A callback that is fired when the item is unhighlighted.

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-value
string

The value of the listbox item.

data-label
string

The label of the listbox item.

data-disabled
''

Present when the item is disabled.

data-highlighted
''

Present when the item is highlighted, which is either via keyboard navigation of the menu or hover.

data-selected
''

Present when the item is selected.

data-listbox-item
''

Present on the item element.

Listbox.Viewport

An optional element to track the scroll position of the listbox 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-listbox-viewport
''

Present on the viewport element.

Listbox.ScrollUpButton

An optional scroll up button element to improve the scroll experience within the listbox. Should be used in conjunction with the Listbox.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-listbox-scroll-up-button
''

Present on the scroll up button element.

Listbox.ScrollDownButton

An optional scroll down button element to improve the scroll experience within the listbox. Should be used in conjunction with the Listbox.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-listbox-scroll-down-button
''

Present on the scroll down button element.

Listbox.Group

A group of related listbox 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-listbox-group
''

Present on the group element.

Listbox.GroupLabel

A label for the parent listbox group. This is used to describe a group of related listbox 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-listbox-group-label
''

Present on the group label element.

Listbox.Arrow

An optional arrow element which points to the content 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.