# Dropdown Menu Documentation Displays a menu of items that users can select from when triggered. This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue. Copy Page ```svelte ``` ## Structure ```svelte ``` ## Reusable Components If you're planning to use Dropdown Menu in multiple places, you can create a reusable component that wraps the Dropdown Menu component. This example shows you how to create a Dropdown Menu component that accepts a few custom props that make it more capable. MyDropdownMenu.svelte ```svelte {buttonText} {#each items as item} {item} {/each} ``` You can then use the `MyDropdownMenu` component like this: ```svelte ``` ## Managing Open State This section covers how to manage the `open` state of the menu. ### Two-Way Binding Use `bind:open` for simple, automatic state synchronization: ```svelte ``` ### Fully Controlled Use a [Function Binding](https://svelte.dev/docs/svelte/bind#Function-bindings) for complete control over the state's reads and writes. ```svelte ``` ## Groups To group related menu items, you can use the `DropdownMenu.Group` component along with either a `DropdownMenu.GroupHeading` or an `aria-label` attribute on the `DropdownMenu.Group` component. ```svelte File New Open Save Save As New Open Save Save As ``` ### Group Heading The `DropdownMenu.GroupHeading` component must be a child of either a `DropdownMenu.Group` or `DropdownMenu.RadioGroup` component. If used on its own, an error will be thrown during development. ```svelte File Favorite color ``` ## Radio Groups You can combine the `DropdownMenu.RadioGroup` and `DropdownMenu.RadioItem` components to create a radio group within a menu. ```svelte Favorite number {#each values as value} {#snippet children({ checked })} {#if checked} ✅ {/if} {value} {/snippet} {/each} ``` The `value` state does not persist between menu open/close cycles. To persist the state, you must store it in a `$state` variable and pass it to the `value` prop. ## Checkbox Items You can use the `DropdownMenu.CheckboxItem` component to create a `menuitemcheckbox` element to add checkbox functionality to menu items. ```svelte {#snippet children({ checked, indeterminate })} {#if indeterminate} - {:else if checked} ✅ {/if} Notifications {/snippet} ``` The `checked` state does not persist between menu open/close cycles. To persist the state, you must store it in a `$state` variable and pass it to the `checked` prop. ## Checkbox Groups You can use the `DropdownMenu.CheckboxGroup` component around a set of `DropdownMenu.CheckboxItem` components to create a checkbox group within a menu, where the `value` prop is an array of the selected values. ```svelte Favorite color {#snippet children({ checked })} {#if checked} ✅ {/if} Red {/snippet} {#snippet children({ checked })} {#if checked} ✅ {/if} Blue {/snippet} {#snippet children({ checked })} {#if checked} ✅ {/if} Green {/snippet} ``` The `value` state does not persist between menu open/close cycles. To persist the state, you must store it in a `$state` variable and pass it to the `value` prop. ## Nested Menus You can create nested menus using the `DropdownMenu.Sub` component to create complex menu structures. ```svelte Item 1 Item 2 Open Sub Menu Sub Item 1 Sub Item 2 ``` ## Svelte Transitions You can use the `forceMount` prop along with the `child` snippet to forcefully mount the `DropdownMenu.Content` component to use Svelte Transitions or another animation library that requires more control. ```svelte {#snippet child({ wrapperProps, props, open })} {#if open}

Item 1 Item 2

{/if} {/snippet} ``` Of course, this isn't the prettiest syntax, so it's recommended to create your own reusable content component that handles this logic if you intend to use this approach. For more information on using transitions with Bits UI components, see the [Transitions](/docs/transitions) documentation. Expand Code ```svelte ``` ## Custom Anchor By default, the `DropdownMenu.Content` is anchored to the `DropdownMenu.Trigger` component, which determines where the content is positioned. If you wish to instead anchor the content to a different element, you can pass either a selector `string` or an `HTMLElement` to the `customAnchor` prop of the `DropdownMenu.Content` component. ```svelte

``` ## API Reference ### DropdownMenu.Root The root component which manages & scopes the state of the dropdown menu. | Property | Type | Description | Details | | ---------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------ | ------- | | `open` $bindable | `boolean` | The open state of the menu.`Default: false` | | | `onOpenChange` | `function` - (open: boolean) => void | A callback function called when the open state changes.`Default: —— undefined` | | | `onOpenChangeComplete` | `function` - (open: boolean) => void | A callback function called after the open state changes and all animations have completed.`Default: —— undefined` | | | `dir` | `enum` - 'ltr' \| 'rtl' | The reading direction of the app.`Default: 'ltr'` | | | `children` | `Snippet` | The children content to render.`Default: —— undefined` | | ### DropdownMenu.Trigger The button element which toggles the dropdown menu. | Property | Type | Description | Details | | --------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | `disabled` | `boolean` | Whether or not the menu trigger is disabled.`Default: false` | | | `ref` $bindable | `HTMLButtonElement` | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default: null` | | | `children` | `Snippet` | The children content to render.`Default: —— undefined` | | | `child` | `Snippet` - type SnippetProps = { props: Record\; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default: —— undefined` | | | Data Attribute | Value | Description | Details | | ---------------------------- | --------------------------- | ------------------------------------------------------------------------- | ------- | | `data-state` | `enum` - 'open' \| 'closed' | The open state of the menu or submenu the element controls or belongs to. | | | `data-dropdown-menu-trigger` | `''` | Present on the trigger element. | | ### DropdownMenu.Portal A component that portals the content of the dropdown menu to the body or a custom target (if provided). | Property | Type | Description | Details | | ---------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ------- | | `to` | `union` - Element \| string | Where to render the content when it is open. Defaults to the body.`Default: document.body` | | | `disabled` | `boolean` | Whether the portal is disabled or not. When disabled, the content will be rendered in its original DOM location.`Default: false` | | | `children` | `Snippet` | The children content to render.`Default: —— undefined` | | ### DropdownMenu.Content The content displayed when the dropdown menu is open. | Property | Type | Description | Details | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | | `side` | `enum` - 'top' \| 'bottom' \| 'left' \| 'right' | 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` - 'start' \| 'center' \| 'end' | 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` - Element \| null | A boundary element or array of elements to check for collisions against.`Default: —— undefined` | | | `collisionPadding` | `union` - number \| Partial\> | The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision.`Default: 0` | | | `sticky` | `enum` - 'partial' \| 'always' | 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` - 'optimized' \| 'always' | 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` - 'fixed' \| 'absolute' | 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` | | | `customAnchor` | `union` - string \| HTMLElement \| Measurable \| null | Use an element other than the trigger to anchor the content to. If provided, the content will be anchored to the provided element instead of the trigger.`Default: null` | | | `onEscapeKeydown` | `function` - (event: KeyboardEvent) => void | 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` - 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | 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` - (event: PointerEvent) => void | Callback fired when an outside interaction event occurs, which is a `pointerdown` event. You can call `event.preventDefault()` to prevent the default behavior of handling the outside interaction.`Default: —— undefined` | | | `onFocusOutside` | `function` - (event: FocusEvent) => void | Callback fired when focus leaves the dismissible layer. You can call `event.preventDefault()` to prevent the default behavior on focus leaving the layer.`Default: —— undefined` | | | `interactOutsideBehavior` | `enum` - 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | 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'` | | | `onOpenAutoFocus` | `function` - (event: Event) => void | Event handler called when auto-focusing the content as it is opened. Can be prevented.`Default: —— undefined` | | | `onCloseAutoFocus` | `function` - (event: Event) => void | Event handler called when auto-focusing the content as it is closed. Can be prevented.`Default: —— undefined` | | | `trapFocus` | `boolean` | Whether or not to trap the focus within the content when open.`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` | | | `preventOverflowTextSelection` | `boolean` | When `true`, prevents the text selection from overflowing the bounds of the element.`Default: true` | | | `dir` | `enum` - 'ltr' \| 'rtl' | The reading direction of the app.`Default: 'ltr'` | | | `loop` | `boolean` | Whether or not to loop through the menu items in when navigating with the keyboard.`Default: false` | | | `ref` $bindable | `HTMLDivElement` | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default: null` | | | `children` | `Snippet` | The children content to render.`Default: —— undefined` | | | `child` | `Snippet` - type ChildSnippetProps = { /\*\* \* Props for the positioning wrapper \* Do not style this element - \* styling should be applied to the content element \*/ wrapperProps: Record\; /\*\* \* Props for your content element \* Apply your custom styles here \*/ props: Record\; /\*\* \* Content visibility state \* Use this for conditional rendering with \* Svelte transitions \*/ open: boolean; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default: —— undefined` | | | Data Attribute | Value | Description | Details | | ---------------------------- | --------------------------- | ------------------------------------------------------------------------- | ------- | | `data-state` | `enum` - 'open' \| 'closed' | The open state of the menu or submenu the element controls or belongs to. | | | `data-dropdown-menu-content` | `''` | Present on the content element. | | | CSS Variable | Description | Details | | ----------------------------------------------- | -------------------------------------------- | ------- | | `--bits-dropdown-menu-content-transform-origin` | The transform origin of the content element. | | | `--bits-dropdown-menu-content-available-width` | The available width of the content element. | | | `--bits-dropdown-menu-content-available-height` | The available height of the content element. | | | `--bits-dropdown-menu-anchor-width` | The width of the anchor element. | | | `--bits-dropdown-menu-anchor-height` | The height of the anchor element. | | ### DropdownMenu.ContentStatic The content displayed when the dropdown menu is open. (Static/No Floating UI) | Property | Type | Description | Details | | ------------------------------ | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | | `onEscapeKeydown` | `function` - (event: KeyboardEvent) => void | 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` - 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | 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` - (event: PointerEvent) => void | Callback fired when an outside interaction event occurs, which is a `pointerdown` event. You can call `event.preventDefault()` to prevent the default behavior of handling the outside interaction.`Default: —— undefined` | | | `onFocusOutside` | `function` - (event: FocusEvent) => void | Callback fired when focus leaves the dismissible layer. You can call `event.preventDefault()` to prevent the default behavior on focus leaving the layer.`Default: —— undefined` | | | `interactOutsideBehavior` | `enum` - 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | 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'` | | | `onOpenAutoFocus` | `function` - (event: Event) => void | Event handler called when auto-focusing the content as it is opened. Can be prevented.`Default: —— undefined` | | | `onCloseAutoFocus` | `function` - (event: Event) => void | Event handler called when auto-focusing the content as it is closed. Can be prevented.`Default: —— undefined` | | | `trapFocus` | `boolean` | Whether or not to trap the focus within the content when open.`Default: true` | | | `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` | | | `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` | | | `preventOverflowTextSelection` | `boolean` | When `true`, prevents the text selection from overflowing the bounds of the element.`Default: true` | | | `dir` | `enum` - 'ltr' \| 'rtl' | The reading direction of the app.`Default: 'ltr'` | | | `loop` | `boolean` | Whether or not to loop through the menu items in when navigating with the keyboard.`Default: false` | | | `ref` $bindable | `HTMLDivElement` | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default: null` | | | `children` | `Snippet` | The children content to render.`Default: —— undefined` | | | `child` | `Snippet` - type ChildSnippetProps = { open: boolean; props: Record\; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default: —— undefined` | | | Data Attribute | Value | Description | Details | | ---------------------------- | --------------------------- | ------------------------------------------------------------------------- | ------- | | `data-state` | `enum` - 'open' \| 'closed' | The open state of the menu or submenu the element controls or belongs to. | | | `data-dropdown-menu-content` | `''` | Present on the content element. | | ### DropdownMenu.Item A menu item within the dropdown menu. | Property | Type | Description | Details | | --------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | `disabled` | `boolean` | Whether or not the menu item is disabled.`Default: false` | | | `textValue` | `string` | The text value of the checkbox menu item. This is used for typeahead.`Default: —— undefined` | | | `onSelect` | `function` - () => void | A callback that is fired when the menu item is selected.`Default: —— undefined` | | | `closeOnSelect` | `boolean` | Whether or not the menu item should close when selected.`Default: true` | | | `ref` $bindable | `HTMLDivElement` | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default: null` | | | `children` | `Snippet` | The children content to render.`Default: —— undefined` | | | `child` | `Snippet` - type SnippetProps = { props: Record\; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default: —— undefined` | | | Data Attribute | Value | Description | Details | | ------------------------- | ---------- | ------------------------------------------ | ------- | | `data-orientation` | `vertical` | The orientation of the menu. | | | `data-highlighted` | `''` | Present when the menu item is highlighted. | | | `data-disabled` | `''` | Present when the menu item is disabled. | | | `data-dropdown-menu-item` | `''` | Present on the item element. | | ### DropdownMenu.CheckboxGroup A group of checkbox menu items, where multiple can be checked at a time. | Property | Type | Description | Details | | ----------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | `value` $bindable | `string[]` | The value of the group. This is an array of the values of the checked checkboxes within the group.`Default: []` | | | `onValueChange` | `function` - (value: string\[]) => void | A callback that is fired when the checkbox group's value state changes.`Default: —— undefined` | | | `ref` $bindable | `HTMLDivElement` | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default: null` | | | `children` | `Snippet` | The children content to render.`Default: —— undefined` | | | `child` | `Snippet` - type SnippetProps = { props: Record\; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default: —— undefined` | | | Data Attribute | Value | Description | Details | | ----------------------------------- | ----- | -------------------------------------- | ------- | | `data-dropdown-menu-checkbox-group` | `''` | Present on the checkbox group element. | | ### DropdownMenu.CheckboxItem A menu item that can be controlled and toggled like a checkbox. | Property | Type | Description | Details | | ------------------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | `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` $bindable | `boolean` | The checked state of the checkbox.`Default: false` | | | `onCheckedChange` | `function` - (checked: boolean) => void | A callback that is fired when the checked state changes.`Default: —— undefined` | | | `indeterminate` $bindable | `boolean` | The indeterminate state of the checkbox.`Default: false` | | | `onIndeterminateChange` | `function` - (indeterminate: boolean) => void | A callback that is fired when the indeterminate state changes.`Default: —— undefined` | | | `value` | `string` | The value of the checkbox item when used in a `*Menu.CheckboxGroup`.`Default: —— undefined` | | | `textValue` | `string` | The text value of the checkbox menu item. This is used for typeahead.`Default: —— undefined` | | | `onSelect` | `function` - () => void | A callback that is fired when the menu item is selected.`Default: —— undefined` | | | `closeOnSelect` | `boolean` | Whether or not the menu item should close when selected.`Default: true` | | | `ref` $bindable | `HTMLDivElement` | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default: null` | | | `children` | `Snippet` - type ChildrenSnippetProps = { checked: boolean; indeterminate: boolean; }; | The children content to render.`Default: —— undefined` | | | `child` | `Snippet` - type ChildSnippetProps = { props: Record\; checked: boolean; indeterminate: boolean; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default: —— undefined` | | | Data Attribute | Value | Description | Details | | ---------------------------------- | ---------------------------------------------------- | ------------------------------------------ | ------- | | `data-orientation` | `vertical` | The orientation of the menu. | | | `data-highlighted` | `''` | Present when the menu item is highlighted. | | | `data-disabled` | `''` | Present when the menu item is disabled. | | | `data-state` | `enum` - 'checked' \| 'unchecked' \| 'indeterminate' | The checkbox menu item's checked state. | | | `data-dropdown-menu-checkbox-item` | `''` | Present on the checkbox item element. | | ### DropdownMenu.RadioGroup A group of radio menu items, where only one can be checked at a time. | Property | Type | Description | Details | | ----------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | `value` $bindable | `string` | The value of the currently checked radio menu item.`Default: —— undefined` | | | `onValueChange` | `function` - (value: string) => void | A callback that is fired when the radio group's value changes.`Default: —— undefined` | | | `ref` $bindable | `HTMLDivElement` | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default: null` | | | `children` | `Snippet` | The children content to render.`Default: —— undefined` | | | `child` | `Snippet` - type SnippetProps = { props: Record\; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default: —— undefined` | | | Data Attribute | Value | Description | Details | | -------------------------------- | ----- | ----------------------------------- | ------- | | `data-dropdown-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 | Details | | ---------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | `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` | `boolean` | Whether or not the radio menu item is disabled. Disabled items cannot be interacted with and are skipped when navigating with the keyboard.`Default: false` | | | `textValue` | `string` | The text value of the checkbox menu item. This is used for typeahead.`Default: —— undefined` | | | `onSelect` | `function` - () => void | A callback that is fired when the menu item is selected.`Default: —— undefined` | | | `closeOnSelect` | `boolean` | Whether or not the menu item should close when selected.`Default: true` | | | `ref` $bindable | `HTMLDivElement` | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default: null` | | | `children` | `Snippet` - type ChildrenSnippetProps = { checked: boolean; }; | The children content to render.`Default: —— undefined` | | | `child` | `Snippet` - type ChildSnippetProps = { props: Record\; checked: boolean; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default: —— undefined` | | | Data Attribute | Value | Description | Details | | ------------------------------- | --------------------------------- | ------------------------------------------ | ------- | | `data-orientation` | `vertical` | The orientation of the menu. | | | `data-highlighted` | `''` | Present when the menu item is highlighted. | | | `data-disabled` | `''` | Present when the menu item is disabled. | | | `data-state` | `enum` - 'checked' \| 'unchecked' | The radio menu item's checked state. | | | `data-value` | `''` | The value of the radio item. | | | `data-dropdown-menu-radio-item` | `''` | Present on the radio item element. | | ### DropdownMenu.Separator A horizontal line to visually separate menu items. | Property | Type | Description | Details | | --------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | `ref` $bindable | `HTMLDivElement` | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default: null` | | | `children` | `Snippet` | The children content to render.`Default: —— undefined` | | | `child` | `Snippet` - type SnippetProps = { props: Record\; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default: —— undefined` | | | Data Attribute | Value | Description | Details | | ------------------------------ | ---------- | --------------------------------- | ------- | | `data-orientation` | `vertical` | The orientation of the separator. | | | `data-menu-separator` | `''` | Present on the separator element. | | | `data-dropdown-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 | Details | | --------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | `width` | `number` | The width of the arrow in pixels.`Default: 8` | | | `height` | `number` | The height of the arrow in pixels.`Default: 8` | | | `ref` $bindable | `HTMLDivElement` | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default: null` | | | `children` | `Snippet` | The children content to render.`Default: —— undefined` | | | `child` | `Snippet` - type SnippetProps = { props: Record\; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default: —— undefined` | | | Data Attribute | Value | Description | Details | | -------------------------- | --------------------------- | ------------------------------------------------------------------------- | ------- | | `data-state` | `enum` - 'open' \| 'closed' | The open state of the menu or submenu the element controls or belongs to. | | | `data-dropdown-menu-arrow` | `''` | Present on the arrow element. | | ### DropdownMenu.Group A group of menu items. It should be passed an `aria-label` or have a child `DropdownMenu.GroupHeading` component to provide a label for a group of menu items. | Property | Type | Description | Details | | --------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | `ref` $bindable | `HTMLDivElement` | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default: null` | | | `children` | `Snippet` | The children content to render.`Default: —— undefined` | | | `child` | `Snippet` - type SnippetProps = { props: Record\; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default: —— undefined` | | | Data Attribute | Value | Description | Details | | -------------------------- | ----- | ----------------------------- | ------- | | `data-dropdown-menu-group` | `''` | Present on the group element. | | ### DropdownMenu.GroupHeading A heading for a group which will be skipped when navigating with the keyboard. It is used to provide a description for a group of menu items and must be a child of either a `DropdownMenu.Group` or `DropdownMenu.RadioGroup` component. | Property | Type | Description | Details | | --------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | `ref` $bindable | `HTMLDivElement` | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default: null` | | | `children` | `Snippet` | The children content to render.`Default: —— undefined` | | | `child` | `Snippet` - type SnippetProps = { props: Record\; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default: —— undefined` | | | Data Attribute | Value | Description | Details | | ---------------------------------- | ----- | ------------------------------------- | ------- | | `data-dropdown-menu-group-heading` | `''` | Present on the group heading element. | | ### DropdownMenu.Sub A submenu belonging to the parent dropdown menu. Responsible for managing the state of the submenu. | Property | Type | Description | Details | | ---------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------ | ------- | | `open` $bindable | `boolean` | The open state of the submenu.`Default: false` | | | `onOpenChange` | `function` - (open: boolean) => void | A callback function called when the open state changes.`Default: —— undefined` | | | `onOpenChangeComplete` | `function` - (open: boolean) => void | A callback function called after the open state changes and all animations have completed.`Default: —— undefined` | | | `children` | `Snippet` | The children content to render.`Default: —— undefined` | | ### DropdownMenu.SubTrigger A menu item which when pressed or hovered, opens the submenu it is a child of. | Property | Type | Description | Details | | --------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | `disabled` | `boolean` | Whether or not the submenu trigger is disabled.`Default: false` | | | `openDelay` | `number` | The amount of time in ms from when the mouse enters the subtrigger until the submenu opens.`Default: 100` | | | `textValue` | `string` | The text value of the checkbox menu item. This is used for typeahead.`Default: —— undefined` | | | `onSelect` | `function` - () => void | A callback that is fired when the menu item is selected.`Default: —— undefined` | | | `ref` $bindable | `HTMLDivElement` | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default: null` | | | `children` | `Snippet` | The children content to render.`Default: —— undefined` | | | `child` | `Snippet` - type SnippetProps = { props: Record\; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default: —— undefined` | | | Data Attribute | Value | Description | Details | | -------------------------------- | --------------------------- | ------------------------------------------------------------------------- | ------- | | `data-orientation` | `vertical` | The orientation of the menu. | | | `data-highlighted` | `''` | Present when the menu item is highlighted. | | | `data-disabled` | `''` | Present when the menu item is disabled. | | | `data-state` | `enum` - 'open' \| 'closed' | The open state of the menu or submenu the element controls or belongs to. | | | `data-dropdown-menu-sub-trigger` | `''` | Present on the submenu trigger element. | | ### DropdownMenu.SubContent The submenu content displayed when the parent submenu is open. | Property | Type | Description | Details | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | | `side` | `enum` - 'top' \| 'bottom' \| 'left' \| 'right' | 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` - 'start' \| 'center' \| 'end' | 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` - Element \| null | A boundary element or array of elements to check for collisions against.`Default: —— undefined` | | | `collisionPadding` | `union` - number \| Partial\> | The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision.`Default: 0` | | | `sticky` | `enum` - 'partial' \| 'always' | 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` - 'optimized' \| 'always' | 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` - 'fixed' \| 'absolute' | 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` | | | `customAnchor` | `union` - string \| HTMLElement \| Measurable \| null | Use an element other than the trigger to anchor the content to. If provided, the content will be anchored to the provided element instead of the trigger.`Default: null` | | | `onEscapeKeydown` | `function` - (event: KeyboardEvent) => void | 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` - 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | 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` - (event: PointerEvent) => void | Callback fired when an outside interaction event occurs, which is a `pointerdown` event. You can call `event.preventDefault()` to prevent the default behavior of handling the outside interaction.`Default: —— undefined` | | | `onFocusOutside` | `function` - (event: FocusEvent) => void | Callback fired when focus leaves the dismissible layer. You can call `event.preventDefault()` to prevent the default behavior on focus leaving the layer.`Default: —— undefined` | | | `interactOutsideBehavior` | `enum` - 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | 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'` | | | `onOpenAutoFocus` | `function` - (event: Event) => void | Event handler called when auto-focusing the content as it is opened. Can be prevented.`Default: —— undefined` | | | `onCloseAutoFocus` | `function` - (event: Event) => void | Event handler called when auto-focusing the content as it is closed. Can be prevented.`Default: —— undefined` | | | `trapFocus` | `boolean` | Whether or not to trap the focus within the content when open.`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` | | | `preventOverflowTextSelection` | `boolean` | When `true`, prevents the text selection from overflowing the bounds of the element.`Default: true` | | | `dir` | `enum` - 'ltr' \| 'rtl' | The reading direction of the app.`Default: 'ltr'` | | | `loop` | `boolean` | Whether or not to loop through the menu items in when navigating with the keyboard.`Default: false` | | | `ref` $bindable | `HTMLDivElement` | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default: null` | | | `children` | `Snippet` | The children content to render.`Default: —— undefined` | | | `child` | `Snippet` - type ChildSnippetProps = { /\*\* \* Props for the positioning wrapper \* Do not style this element - \* styling should be applied to the content element \*/ wrapperProps: Record\; /\*\* \* Props for your content element \* Apply your custom styles here \*/ props: Record\; /\*\* \* Content visibility state \* Use this for conditional rendering with \* Svelte transitions \*/ open: boolean; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default: —— undefined` | | | Data Attribute | Value | Description | Details | | -------------------------------- | --------------------------- | ------------------------------------------------------------------------- | ------- | | `data-state` | `enum` - 'open' \| 'closed' | The open state of the menu or submenu the element controls or belongs to. | | | `data-dropdown-menu-sub-content` | `''` | Present on the submenu content element. | | ### DropdownMenu.SubContentStatic The submenu content displayed when the parent submenu menu is open. (Static/No Floating UI) | Property | Type | Description | Details | | ------------------------------ | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | | `onEscapeKeydown` | `function` - (event: KeyboardEvent) => void | 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` - 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | 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` - (event: PointerEvent) => void | Callback fired when an outside interaction event occurs, which is a `pointerdown` event. You can call `event.preventDefault()` to prevent the default behavior of handling the outside interaction.`Default: —— undefined` | | | `onFocusOutside` | `function` - (event: FocusEvent) => void | Callback fired when focus leaves the dismissible layer. You can call `event.preventDefault()` to prevent the default behavior on focus leaving the layer.`Default: —— undefined` | | | `interactOutsideBehavior` | `enum` - 'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore' | 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'` | | | `onOpenAutoFocus` | `function` - (event: Event) => void | Event handler called when auto-focusing the content as it is opened. Can be prevented.`Default: —— undefined` | | | `onCloseAutoFocus` | `function` - (event: Event) => void | Event handler called when auto-focusing the content as it is closed. Can be prevented.`Default: —— undefined` | | | `trapFocus` | `boolean` | Whether or not to trap the focus within the content when open.`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` | | | `preventOverflowTextSelection` | `boolean` | When `true`, prevents the text selection from overflowing the bounds of the element.`Default: true` | | | `dir` | `enum` - 'ltr' \| 'rtl' | The reading direction of the app.`Default: 'ltr'` | | | `loop` | `boolean` | Whether or not to loop through the menu items when reaching the end of the list when using the keyboard.`Default: true` | | | `ref` $bindable | `HTMLDivElement` | The underlying DOM element being rendered. You can bind to this to get a reference to the element.`Default: null` | | | `children` | `Snippet` | The children content to render.`Default: —— undefined` | | | `child` | `Snippet` - type ChildSnippetProps = { open: boolean; props: Record\; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default: —— undefined` | | | Data Attribute | Value | Description | Details | | -------------------------------- | --------------------------- | ------------------------------------------------------------------------- | ------- | | `data-state` | `enum` - 'open' \| 'closed' | The open state of the menu or submenu the element controls or belongs to. | | | `data-dropdown-menu-sub-content` | `''` | Present on the submenu content element. | | [Previous Dialog](/docs/components/dialog) [Next Label](/docs/components/label)