Overlays
Dropdown Menu
A list of actions or options that opens from a button. Use it for account menus and for actions on one item, such as a website row.
import * as DropdownMenu from '@statix/ui/dropdown-menu';Playground
<DropdownMenu.Root>
<DropdownMenu.Trigger>
{#snippet child({ props })}
<Button variant="outline" {...props}>My account</Button>
{/snippet}
</DropdownMenu.Trigger>
<DropdownMenu.Content>
<DropdownMenu.Label>anna@yoga-berger.de</DropdownMenu.Label>
<DropdownMenu.Item>
<SettingsIcon />
Settings
</DropdownMenu.Item>
<DropdownMenu.Item>
<ReceiptIcon />
Invoices
</DropdownMenu.Item>
<DropdownMenu.Item>
<FileTextIcon />
Contracts
</DropdownMenu.Item>
<DropdownMenu.Separator />
<DropdownMenu.Item>
<LogOutIcon />
Sign out
</DropdownMenu.Item>
</DropdownMenu.Content>
</DropdownMenu.Root>Examples
Account menu
Name and email in a label, then the account pages. Icons in items are 16px and ink-2.
<script lang="ts">
import * as DropdownMenu from '@statix/ui/dropdown-menu';
import * as Avatar from '@statix/ui/avatar';
import { Button } from '@statix/ui/button';
import ChevronDownIcon from '@lucide/svelte/icons/chevron-down';
import SettingsIcon from '@lucide/svelte/icons/settings';
import ReceiptIcon from '@lucide/svelte/icons/receipt';
import FileTextIcon from '@lucide/svelte/icons/file-text';
import LogOutIcon from '@lucide/svelte/icons/log-out';
</script>
<DropdownMenu.Root>
<DropdownMenu.Trigger>
{#snippet child({ props })}
<Button variant="ghost" class="pl-1.5" {...props}>
<Avatar.Root class="size-8">
<Avatar.Fallback>AB</Avatar.Fallback>
</Avatar.Root>
Anna Berger
<ChevronDownIcon data-icon="inline-end" />
</Button>
{/snippet}
</DropdownMenu.Trigger>
<DropdownMenu.Content align="end" class="w-60">
<DropdownMenu.Label class="grid">
<span class="text-body text-ink">Anna Berger</span>
<span class="font-normal">anna@yoga-berger.de</span>
</DropdownMenu.Label>
<DropdownMenu.Separator />
<DropdownMenu.Group>
<DropdownMenu.Item>
<SettingsIcon />
Settings
</DropdownMenu.Item>
<DropdownMenu.Item>
<ReceiptIcon />
Invoices
</DropdownMenu.Item>
<DropdownMenu.Item>
<FileTextIcon />
Contracts
</DropdownMenu.Item>
</DropdownMenu.Group>
<DropdownMenu.Separator />
<DropdownMenu.Item>
<LogOutIcon />
Sign out
</DropdownMenu.Item>
</DropdownMenu.Content>
</DropdownMenu.Root>Actions with a submenu
Actions for one website behind an icon button. Put destructive items last, after a separator, with variant="destructive".
<script lang="ts">
import * as DropdownMenu from '@statix/ui/dropdown-menu';
import { Button } from '@statix/ui/button';
import EllipsisIcon from '@lucide/svelte/icons/ellipsis';
import ExternalLinkIcon from '@lucide/svelte/icons/external-link';
import RotateCcwIcon from '@lucide/svelte/icons/rotate-ccw';
import DownloadIcon from '@lucide/svelte/icons/download';
import PencilIcon from '@lucide/svelte/icons/pencil';
import TrashIcon from '@lucide/svelte/icons/trash-2';
const backups = ['Today, 03:10', 'Yesterday, 22:05', 'Yesterday, 03:10', '16 Nov, 03:10'];
</script>
<DropdownMenu.Root>
<DropdownMenu.Trigger>
{#snippet child({ props })}
<Button variant="secondary" size="icon" aria-label="Actions for yoga-berger.de" {...props}>
<EllipsisIcon />
</Button>
{/snippet}
</DropdownMenu.Trigger>
<DropdownMenu.Content align="end">
<DropdownMenu.Item>
<ExternalLinkIcon />
Open website
</DropdownMenu.Item>
<DropdownMenu.Item>
<PencilIcon />
Rename
<DropdownMenu.Shortcut>⌘R</DropdownMenu.Shortcut>
</DropdownMenu.Item>
<DropdownMenu.Sub>
<DropdownMenu.SubTrigger>
<RotateCcwIcon />
Restore backup
</DropdownMenu.SubTrigger>
<DropdownMenu.SubContent>
<DropdownMenu.Label>Backups</DropdownMenu.Label>
{#each backups as backup (backup)}
<DropdownMenu.Item>{backup}</DropdownMenu.Item>
{/each}
</DropdownMenu.SubContent>
</DropdownMenu.Sub>
<DropdownMenu.Item>
<DownloadIcon />
Download backup
</DropdownMenu.Item>
<DropdownMenu.Separator />
<DropdownMenu.Item variant="destructive">
<TrashIcon />
Delete website
</DropdownMenu.Item>
</DropdownMenu.Content>
</DropdownMenu.Root>Checkbox items
Settings that can be on or off. The menu stays open while you toggle them.
<script lang="ts">
import * as DropdownMenu from '@statix/ui/dropdown-menu';
import { Button } from '@statix/ui/button';
import BellIcon from '@lucide/svelte/icons/bell';
let backupReports = $state(true);
let invoices = $state(true);
let productNews = $state(false);
</script>
<DropdownMenu.Root>
<DropdownMenu.Trigger>
{#snippet child({ props })}
<Button variant="outline" {...props}>
<BellIcon data-icon="inline-start" />
Email notifications
</Button>
{/snippet}
</DropdownMenu.Trigger>
<DropdownMenu.Content class="w-64">
<DropdownMenu.Label>Send me an email about</DropdownMenu.Label>
<DropdownMenu.CheckboxItem bind:checked={backupReports}>
Weekly backup report
</DropdownMenu.CheckboxItem>
<DropdownMenu.CheckboxItem bind:checked={invoices}>New invoices</DropdownMenu.CheckboxItem>
<DropdownMenu.CheckboxItem bind:checked={productNews}>Product news</DropdownMenu.CheckboxItem>
</DropdownMenu.Content>
</DropdownMenu.Root>Radio items
Pick one option, for example a sort order. Pass closeOnSelect to close the menu after the choice.
<script lang="ts">
import * as DropdownMenu from '@statix/ui/dropdown-menu';
import { Button } from '@statix/ui/button';
import ArrowDownUpIcon from '@lucide/svelte/icons/arrow-down-up';
const options = [
{ value: 'newest', label: 'Newest first' },
{ value: 'oldest', label: 'Oldest first' },
{ value: 'amount', label: 'Highest amount' },
{ value: 'open', label: 'Open invoices first' }
];
let sort = $state('newest');
const current = $derived(options.find((option) => option.value === sort)?.label);
</script>
<DropdownMenu.Root>
<DropdownMenu.Trigger>
{#snippet child({ props })}
<Button variant="outline" {...props}>
<ArrowDownUpIcon data-icon="inline-start" />
{current}
</Button>
{/snippet}
</DropdownMenu.Trigger>
<DropdownMenu.Content>
<DropdownMenu.Label>Sort invoices</DropdownMenu.Label>
<DropdownMenu.RadioGroup bind:value={sort}>
{#each options as option (option.value)}
<DropdownMenu.RadioItem value={option.value} closeOnSelect>
{option.label}
</DropdownMenu.RadioItem>
{/each}
</DropdownMenu.RadioGroup>
</DropdownMenu.Content>
</DropdownMenu.Root>Guidelines
Do
- Start item labels with a verb when they run an action: "Download backup".
- Group related items and separate groups with DropdownMenu.Separator.
- Put the destructive item last and confirm it with an Alert Dialog.
Don't
- Don’t hide the main action of a page in a menu. Show it as a button.
- Don’t nest submenus more than one level deep.
- Don’t use a dropdown menu to pick a form value. Use Select.
Accessibility
- The trigger gets aria-haspopup="menu" and aria-expanded. The content has role="menu".
- Enter, Space and Arrow Down open the menu and focus the first item. Arrow keys move, Home and End jump, typing a letter finds an item.
- Arrow Right opens a submenu, Arrow Left closes it. Escape closes the menu and returns focus to the trigger.
- Checkbox and radio items expose aria-checked. Disabled items are skipped.
- Icon-only triggers need an aria-label that names the object, for example "Actions for yoga-berger.de".
API reference
DropdownMenu.Root
Holds the open state. Renders no element.
| Prop | Type | Default |
|---|---|---|
open bind | boolean Whether the menu is open. | false |
onOpenChange | (open: boolean) => void Called when the menu opens or closes. | – |
DropdownMenu.Trigger
renders<button> and accepts its attributesOpens the menu. Use the child snippet to render a Button.
| Data attribute | Meaning |
|---|---|
data-state | "open" or "closed". |
DropdownMenu.Content
renders<div role="menu"> and accepts its attributesThe menu surface: white, 16px radius, hairline border, overlay shadow. At least 208px wide or as wide as the trigger.
| Prop | Type | Default |
|---|---|---|
side | 'top' | 'right' | 'bottom' | 'left' Preferred side. | 'bottom' |
align | 'start' | 'center' | 'end' Alignment against the trigger. | 'start' |
sideOffset | number Gap to the trigger in pixels. | 6 |
loop | boolean Wraps arrow key focus from the last item to the first. | false |
portalProps | DropdownMenu.PortalProps Props for the portal. | – |
class | ClassValue Merged with the surface classes, for example w-60. | – |
| Data attribute | Meaning |
|---|---|
data-slot="dropdown-menu-content" | Always present. |
data-side | The side it ended up on. |
data-state | "open" or "closed". |
DropdownMenu.Item
renders<div role="menuitem"> and accepts its attributes40px high, 15px text, rounded-sm. The hover and focus fill is bg-2.
| Prop | Type | Default |
|---|---|---|
variant | 'default' | 'destructive' destructive colours the text and icon red and uses a soft red fill on focus. | 'default' |
inset | boolean Indents the label to line up with items that have an icon. | false |
disabled | boolean Skips the item in keyboard navigation and fades it. | false |
onSelect | (event: Event) => void Called when the item is chosen. Call event.preventDefault() to keep the menu open. | – |
closeOnSelect | boolean Closes the menu after selecting. | true |
| Data attribute | Meaning |
|---|---|
data-variant | "default" or "destructive". |
data-highlighted | Present while the item has focus. |
data-disabled | Present when disabled. |
DropdownMenu.CheckboxItem
renders<div role="menuitemcheckbox"> and accepts its attributesAn item with a check mark on the right. Stays open on select by default.
| Prop | Type | Default |
|---|---|---|
checked bind | boolean Whether it is checked. | false |
indeterminate bind | boolean Shows a dash instead of the check. | false |
closeOnSelect | boolean Closes the menu after toggling. | false |
| Data attribute | Meaning |
|---|---|
data-state | "checked", "unchecked" or "indeterminate". |
DropdownMenu.RadioGroup
renders<div role="group"> and accepts its attributesGroups radio items.
| Prop | Type | Default |
|---|---|---|
value bind | string The selected value. | – |
DropdownMenu.RadioItem
renders<div role="menuitemradio"> and accepts its attributesOne option in a radio group. Shows a check mark when selected.
| Prop | Type | Default |
|---|---|---|
value * | string Value of this option. | – |
closeOnSelect | boolean Closes the menu after choosing. | false |
DropdownMenu.Label
renders<div> and accepts its attributesA 13px muted heading above a group. Not focusable.
| Prop | Type | Default |
|---|---|---|
inset | boolean Indents the label. | false |
DropdownMenu.Group / GroupHeading
renders<div role="group"> and accepts its attributesGroups items. GroupHeading labels the group for screen readers.
DropdownMenu.Separator
renders<div role="separator"> and accepts its attributesA 1px hairline across the full menu width.
DropdownMenu.Shortcut
renders<span> and accepts its attributesRight-aligned keyboard hint inside an item. Decorative only.
DropdownMenu.Sub / SubTrigger / SubContent
A nested menu. SubTrigger is an item with a chevron; SubContent uses the same surface as Content.
| Prop | Type | Default |
|---|---|---|
open bind | boolean On Sub: whether the submenu is open. | false |
inset | boolean On SubTrigger: indents the label. | false |