Dropdown Menu

Dropdown menus reveal secondary actions, settings, and grouped choices without permanently occupying layout space.

Basic Usage

Use a simple trigger and a short action list for the most common menu pattern.

Grouped Options

Labels, separators, check items, radio items, and shortcuts help organize denser menu content without losing scanability.

Different Triggers

Menus often sit behind different trigger styles depending on whether the action is primary, contextual, or account-related.

Submenus

Submenus are useful for deeper action trees, but they should stay narrow and clearly grouped.

Selection Items

Use checkbox and radio items for menu options that change persistent view or sorting state.

Item Icons

Leading icons go in the item’s prefix slot (or start).

Sizes

size on DropdownMenu scales items, labels, and icons together.

Slotted labels and host metrics

Item labels live in light DOM (default slot). They inherit type metrics from the DropdownItem :host — not from the shadow .item row, and not from the menu host or page. Size tokens set --pk-dropdown-item-font-size / --pk-dropdown-item-line-height on the item host so Craft CP (tight body line-height) and Tailwind-scoped hosts get the same row rhythm without consumer CSS.

Do not put font-size / line-height on DropdownMenu (or a wrapper) expecting item labels to pick them up for layout — ancestor noise can crush rows until the kit :host pin is present. After that pin, consumers should remove temporary menu-host type overrides.

Stress this in the workshop playground at /tools/slotted-host: Craft vs Tailwind hosts, ellipsis + icon menus, a text-trigger type picker, an ancestor line-height: normal case, selects, overlay mode, and Measure popups.

API

DropdownMenu

Slots

Name	Description
trigger	Menu trigger (when not using for)
(default)	pk-dropdown-item elements

Props

Name	Description
distance	Type number Default 4
for	External trigger id — preferred over slot="trigger" when set (TipTap toolbar). Type string
open	Type boolean Default false
placement	Type PkPopupPlacement Default bottom-start
sideOffset	Type number Default 4
size	Type PkDropdownMenuSize Default default
skidding	Type number Default 0

Events

Name	Description
onPkOpenChange	—

CSS Parts

Name	Description	CSS selector
panel	Menu panel	::part(panel)

Dependencies

This component registers the following elements when it loads.

Name	Description
pk-popup	—

DropdownItem

Slots

Name	Description
(default)	Item label
start	Leading icon (preferred; matches pk-button)
prefix	Alias for start (legacy)
details	Trailing shortcut text
submenu	Nested menu items (pk-dropdown-item, separators, labels)

Props

Name	Description
active	Roving highlight index for keyboard nav (active). Visual styling uses :focus-visible / hover — not this flag — so mouse-open does not paint the first item selected (initial open). Type boolean Default false
checked	Type boolean Default false
destructive	Type boolean Default false
disabled	Type boolean Default false
radioGroup	Type string
submenuOpen	Type boolean Default false
type	Type PkDropdownItemType Default normal
value	Type string

Methods

Name	Description
focusControl()	—

Events

Name	Description
onPkSubmenuOpen	—

CSS Parts

Name	Description	CSS selector
check	Checkbox/radio selected indicator	::part(check)
item	Menu item button	::part(item)
label	Item label wrapper	::part(label)
prefix	Leading icon wrapper (hidden when empty)	::part(prefix)

DropdownLabel

No public API metadata found in the custom elements manifest.

DropdownSeparator

No public API metadata found in the custom elements manifest.