Report an issue

Dropdown Menu

Displays a menu of items that users can select from when triggered.

Structure

	<script lang="ts">
	import { DropdownMenu } from "bits-ui";
</script>
 
<DropdownMenu.Root>
	<DropdownMenu.Trigger />
 
	<DropdownMenu.Content>
		<DropdownMenu.Label />
		<DropdownMenu.Item />
 
		<DropdownMenu.Group>
			<DropdownMenu.Item />
		</DropdownMenu.Group>
 
		<DropdownMenu.CheckboxItem>
			<DropdownMenu.CheckboxIndicator />
		</DropdownMenu.CheckboxItem>
 
		<DropdownMenu.RadioGroup>
			<DropdownMenu.RadioItem>
				<DropdownMenu.RadioIndicator />
			</DropdownMenu.RadioItem>
		</DropdownMenu.RadioGroup>
 
		<DropdownMenu.Sub>
			<DropdownMenu.SubTrigger />
			<DropdownMenu.SubContent />
		</DropdownMenu.Sub>
 
		<DropdownMenu.Separator />
		<DropdownMenu.Arrow />
	</DropdownMenu.Content>
</DropdownMenu.Root>

API Reference

DropdownMenu.Root

The root component which manages & scopes the state of the dropdown menu.

Property Type Description
preventScroll
boolean

Whether or not to prevent scroll on the body when the menu is open.

Default: true
closeOnEscape
boolean

Whether to close the menu when the escape key is pressed.

Default: true
closeOnOutsideClick
boolean

Whether to close the menu when a click occurs outside of it.

Default: true
loop
boolean

Whether or not to loop through the menu items when navigating with the keyboard.

Default: false
open
boolean

The open state of the menu.

Default: false
onOpenChange
function

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

Default: undefined
dir
enum

The direction of the menu.

Default: undefined
portal
union

Where to render the menu when it is open. Defaults to the body. Can be disabled by passing null

Default: undefined
closeFocus
FocusProp

Override the focus when the menu is closed.

Default: undefined
typeahead
boolean

Whether or not to enable typeahead functionality. When enabled, the user can type to navigate to menu items.

Default: true
disableFocusFirstItem
boolean

Whether or not to disable focus on the first item when the menu is opened.

Default: false
closeOnItemClick
boolean

Whether or not to close the menu when an item is clicked.

Default: true
onOutsideClick
function

A callback function called when a click occurs outside of the element. If event.preventDefault() is called, the default behavior of closing the element will be prevented.

Default: undefined
Slot Property Type Description
ids
object

The ids of the elements within the component, useful when you don't necessarily want to provide a custom ID, but still want access to the ID being assigned (if any).

DropdownMenu.Trigger

The button element which toggles the dropdown menu.

Property Type Description
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLButtonElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default: undefined
Slot Property Type Description
builder
object

The builder attributes and actions to apply to the element if using the asChild prop with delegation.
Data Attribute Value Description
data-state
enum

The open state of the menu or submenu the element controls or belongs to.

data-menu-trigger
——

Present on the trigger element.

DropdownMenu.Content

The content displayed when the dropdown menu is open.

Property Type Description
transition
function

A Svelte transition function to use when transitioning the content in and out.

Default: undefined
transitionConfig
TransitionConfig

The configuration to apply to the transition.

Default: undefined
inTransition
function

A Svelte transition function to use when transitioning the content in and out.

Default: undefined
inTransitionConfig
TransitionConfig

The configuration to apply to the transition.

Default: undefined
outTransition
function

A Svelte transition function to use when transitioning the content in and out.

Default: undefined
outTransitionConfig
TransitionConfig

The configuration to apply to the transition.

Default: undefined
side
enum

The preferred side of the anchor to render against when open. Will be reversed when collisions occur. Floating UI reference.

Default: undefined
sideOffset
number

The amount of offset to apply to the menu's position on the x-axis. Floating UI reference.

Default: 0
align
enum

The preferred alignment of the anchor to render against when open. Floating UI reference.

Default: undefined
alignOffset
number

An offset in pixels from the 'start' or 'end' alignment options. Floating UI reference.

Default: 0
avoidCollisions
boolean

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

Default: true
collisionBoundary
union

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

Default: undefined
collisionPadding
number

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

Default: 0
fitViewport
boolean

Whether the floating element should be constrained to the viewport. Floating UI reference.

Default: false
sameWidth
boolean

Whether the content should be the same width as the trigger. Floating UI reference.

Default: false
strategy
enum

The positioning strategy to use for the floating element. Floating UI reference.

Default: absolute
overlap
boolean

Whether the floating element can overlap the reference element. Floating UI reference.

Default: false
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default: undefined
Slot Property Type Description
builder
object

The builder attributes and actions to apply to the element if using the asChild prop with delegation.
Data Attribute Value Description
data-state
enum

The open state of the menu or submenu the element controls or belongs to.

data-menu-content
——

Present on the content element.

DropdownMenu.Item

A menu item within the dropdown menu.

Property Type Description
disabled
boolean

Whether or not the menu item is disabled.

Default: false
href
string

An optional prop that when passed converts the dropdown item into an anchor tag.

Default: undefined
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default: undefined
Slot Property Type Description
builder
object

The builder attributes and actions to apply to the element if using the asChild prop with delegation.
Data Attribute Value Description
data-orientation
vertical
data-highlighted
——

Present when the menu item is highlighted.

data-disabled
——

Present when the menu item is disabled.

data-menu-item
——

Present on the item element.

DropdownMenu.CheckboxItem

A menu item that can be controlled and toggled like a checkbox.

Property Type Description
disabled
boolean

Whether or not the checkbox menu item is disabled. Disabled items cannot be interacted with and are skipped when navigating with the keyboard.

Default: false
checked
boolean | 'indeterminate'

The checkbox menu item's checked state.

Default: false
onCheckedChange
function

A callback that is fired when the checkbox menu item's checked state changes.

Default: undefined
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default: undefined
Slot Property Type Description
builder
object

The builder attributes and actions to apply to the element if using the asChild prop with delegation.
Data Attribute Value Description
data-orientation
vertical
data-highlighted
——

Present when the menu item is highlighted.

data-disabled
——

Present when the menu item is disabled.

data-state
enum

The checkbox menu item's checked state.

DropdownMenu.CheckboxIndicator

A visual indicator of the checkbox menu item's checked state. It passed the item's checked state as a slot prop checked and can be used to render a custom indicator.

Property Type Description
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default: undefined
Slot Property Type Description
attrs
object

Additional attributes to apply to the element if using the asChild prop with delegation.
checked
boolean

Whether or not the checkbox is checked.
Data Attribute Value Description
data-menu-checkbox-indicator
——

Present on the checkbox indicator element.

DropdownMenu.RadioGroup

A group of radio menu items, where only one can be checked at a time.

Property Type Description
value
string

The value of the currently checked radio menu item.

Default: undefined
onValueChange
function

A callback that is fired when the radio group's value changes.

Default: undefined
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default: undefined
Slot Property Type Description
builder
object

The builder attributes and actions to apply to the element if using the asChild prop with delegation.
Data Attribute Value Description
data-menu-radio-group
——

Present on the radio group element.

DropdownMenu.RadioItem

A menu item that can be controlled and toggled like a radio button. It must be a child of a RadioGroup.

Property Type Description
value
*
Required
string

The value of the radio item. When checked, the parent RadioGroup's value will be set to this value.

Default: undefined
disabled
false

Whether or not the radio menu item is disabled. Disabled items cannot be interacted with and are skipped when navigating with the keyboard.

Default: undefined
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default: undefined
Slot Property Type Description
builder
object

The builder attributes and actions to apply to the element if using the asChild prop with delegation.
Data Attribute Value Description
data-orientation
vertical
data-highlighted
——

Present when the menu item is highlighted.

data-disabled
——

Present when the menu item is disabled.

data-state
enum

The radio menu item's checked state.

data-value
——

The value of the radio item.

data-menu-radio-item
——

Present on the radio item element.

DropdownMenu.RadioIndicator

A visual indicator helper for RadioItems. It only renders it's children when the radio item is checked.

Property Type Description
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default: undefined
Slot Property Type Description
attrs
object

Additional attributes to apply to the element if using the asChild prop with delegation.
checked
boolean

Whether or not the checkbox is checked.
Data Attribute Value Description
data-menu-radio-indicator
——

Present on the radio indicator element.

DropdownMenu.Separator

A horizontal line to visually separate menu items.

Property Type Description
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default: undefined
Slot Property Type Description
builder
object

The builder attributes and actions to apply to the element if using the asChild prop with delegation.
Data Attribute Value Description
data-orientation
vertical

The orientation of the separator.

data-menu-separator
——

Present on the separator element.

DropdownMenu.Arrow

An optional arrow which points to the dropdown menu's anchor/trigger point.

Property Type Description
size
number

The height and width of the arrow in pixels.

Default: 8
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default: undefined
Slot Property Type Description
builder
object

The builder attributes and actions to apply to the element if using the asChild prop with delegation.
Data Attribute Value Description
data-state
enum

The open state of the menu or submenu the element controls or belongs to.

data-menu-arrow
——

Present on the arrow element.

DropdownMenu.Group

A group of menu items. It can be used along with the Menu.Label component to provide a visual label for a group of menu items. When a label is within a group, appropriate aria attributes will be applied to the group.

Property Type Description
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default: undefined
Slot Property Type Description
builder
object

The builder attributes and actions to apply to the element if using the asChild prop with delegation.
Data Attribute Value Description
data-menu-group
——

Present on the group element.

DropdownMenu.Label

A label which will be skipped when navigating with the keyboard. It is used to provide a visual label for a group of menu items. When a label is within a Menu.Group, appropriate aria attributes will be applied to the group.

Property Type Description
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default: undefined
Slot Property Type Description
builder
object

The builder attributes and actions to apply to the element if using the asChild prop with delegation.
Data Attribute Value Description
data-menu-label
——

Present on the group label element.

DropdownMenu.Sub

A submenu belonging to the parent dropdown menu. Responsible for managing the state of the submenu.

Property Type Description
disabled
boolean

Whether or not the submenu is disabled.

Default: undefined
open
boolean

The open state of the submenu.

Default: false
onOpenChange
function

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

Default: undefined
Slot Property Type Description
subIds
object

The ids of the elements within the component, useful when you don't necessarily want to provide a custom ID, but still want access to the ID being assigned (if any).

DropdownMenu.SubTrigger

A menu item which when pressed or hovered, opens the submenu.

Property Type Description
disabled
boolean

Whether or not the submenu trigger is disabled.

Default: false
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default: undefined
Slot Property Type Description
builder
object

The builder attributes and actions to apply to the element if using the asChild prop with delegation.
Data Attribute Value Description
data-orientation
vertical
data-highlighted
——

Present when the menu item is highlighted.

data-disabled
——

Present when the menu item is disabled.

data-state
enum

The open state of the menu or submenu the element controls or belongs to.

data-menu-subtrigger
——

Present on the submenu trigger element.

DropdownMenu.SubContent

The submenu content displayed when the parent submenu is open.

Property Type Description
transition
function

A Svelte transition function to use when transitioning the content in and out.

Default: undefined
transitionConfig
TransitionConfig

The configuration to apply to the transition.

Default: undefined
inTransition
function

A Svelte transition function to use when transitioning the content in and out.

Default: undefined
inTransitionConfig
TransitionConfig

The configuration to apply to the transition.

Default: undefined
outTransition
function

A Svelte transition function to use when transitioning the content in and out.

Default: undefined
outTransitionConfig
TransitionConfig

The configuration to apply to the transition.

Default: undefined
side
enum

The preferred side of the anchor to render against when open. Will be reversed when collisions occur. Floating UI reference.

Default: undefined
sideOffset
number

The amount of offset to apply to the menu's position on the x-axis. Floating UI reference.

Default: 0
align
enum

The preferred alignment of the anchor to render against when open. Floating UI reference.

Default: undefined
alignOffset
number

An offset in pixels from the 'start' or 'end' alignment options. Floating UI reference.

Default: 0
avoidCollisions
boolean

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

Default: true
collisionBoundary
union

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

Default: undefined
collisionPadding
number

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

Default: 0
fitViewport
boolean

Whether the floating element should be constrained to the viewport. Floating UI reference.

Default: false
sameWidth
boolean

Whether the content should be the same width as the trigger. Floating UI reference.

Default: false
strategy
enum

The positioning strategy to use for the floating element. Floating UI reference.

Default: absolute
overlap
boolean

Whether the floating element can overlap the reference element. Floating UI reference.

Default: false
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default: undefined
Slot Property Type Description
builder
object

The builder attributes and actions to apply to the element if using the asChild prop with delegation.
Data Attribute Value Description
data-state
enum

The open state of the menu or submenu the element controls or belongs to.

data-menu-subcontent
——

Present on the submenu content element.