Skip to content
Statix Design System

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

Controls
<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.

PropTypeDefault
open bindboolean

Whether the menu is open.

false
onOpenChange (open: boolean) => void

Called when the menu opens or closes.

–

DropdownMenu.Trigger

renders <button> and accepts its attributes

Opens the menu. Use the child snippet to render a Button.

Data attributeMeaning
data-state"open" or "closed".

DropdownMenu.Content

renders <div role="menu"> and accepts its attributes

The menu surface: white, 16px radius, hairline border, overlay shadow. At least 208px wide or as wide as the trigger.

PropTypeDefault
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 attributeMeaning
data-slot="dropdown-menu-content"Always present.
data-sideThe side it ended up on.
data-state"open" or "closed".

DropdownMenu.Item

renders <div role="menuitem"> and accepts its attributes

40px high, 15px text, rounded-sm. The hover and focus fill is bg-2.

PropTypeDefault
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 attributeMeaning
data-variant"default" or "destructive".
data-highlightedPresent while the item has focus.
data-disabledPresent when disabled.

DropdownMenu.CheckboxItem

renders <div role="menuitemcheckbox"> and accepts its attributes

An item with a check mark on the right. Stays open on select by default.

PropTypeDefault
checked bindboolean

Whether it is checked.

false
indeterminate bindboolean

Shows a dash instead of the check.

false
closeOnSelect boolean

Closes the menu after toggling.

false
Data attributeMeaning
data-state"checked", "unchecked" or "indeterminate".

DropdownMenu.RadioGroup

renders <div role="group"> and accepts its attributes

Groups radio items.

PropTypeDefault
value bindstring

The selected value.

–

DropdownMenu.RadioItem

renders <div role="menuitemradio"> and accepts its attributes

One option in a radio group. Shows a check mark when selected.

PropTypeDefault
value * string

Value of this option.

–
closeOnSelect boolean

Closes the menu after choosing.

false

DropdownMenu.Label

renders <div> and accepts its attributes

A 13px muted heading above a group. Not focusable.

PropTypeDefault
inset boolean

Indents the label.

false

DropdownMenu.Group / GroupHeading

renders <div role="group"> and accepts its attributes

Groups items. GroupHeading labels the group for screen readers.

DropdownMenu.Separator

renders <div role="separator"> and accepts its attributes

A 1px hairline across the full menu width.

DropdownMenu.Shortcut

renders <span> and accepts its attributes

Right-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.

PropTypeDefault
open bindboolean

On Sub: whether the submenu is open.

false
inset boolean

On SubTrigger: indents the label.

false