@data-slot/dropdown-menu

Headless dropdown menu for vanilla JavaScript. Supports action items, single-select radio items, and multi-select checkbox items with full keyboard navigation and ARIA support.

Installation

npm install @data-slot/dropdown-menu

Usage

Action Menu

<div data-slot="dropdown-menu">
  <button data-slot="dropdown-menu-trigger">Actions</button>
  <div data-slot="dropdown-menu-content">
    <button data-slot="dropdown-menu-item" data-value="edit">Edit</button>
    <button data-slot="dropdown-menu-item" data-value="copy">Copy</button>
    <button data-slot="dropdown-menu-item" data-variant="destructive" data-value="delete">
      Delete
    </button>
  </div>
</div>

Single-Select Menu

<div data-slot="dropdown-menu" data-default-value="pro">
  <button data-slot="dropdown-menu-trigger">Plan</button>
  <div data-slot="dropdown-menu-content">
    <button data-slot="dropdown-menu-radio-item" data-value="starter">Starter</button>
    <button data-slot="dropdown-menu-radio-item" data-value="pro">Pro</button>
    <button data-slot="dropdown-menu-radio-item" data-value="team">Team</button>
  </div>
</div>

Multi-Select Menu

<div
  data-slot="dropdown-menu"
  data-close-on-select="false"
  data-default-values='["email","push"]'
>
  <button data-slot="dropdown-menu-trigger">Channels</button>
  <div data-slot="dropdown-menu-content">
    <button data-slot="dropdown-menu-checkbox-item" data-value="email">Email</button>
    <button data-slot="dropdown-menu-checkbox-item" data-value="sms">SMS</button>
    <button data-slot="dropdown-menu-checkbox-item" data-value="push">Push</button>
  </div>
</div>

JavaScript

import { create, createDropdownMenu } from "@data-slot/dropdown-menu";

const controllers = create();

const root = document.querySelector('[data-slot="dropdown-menu"]');
const controller = createDropdownMenu(root, {
  onOpenChange: (open) => console.log("open:", open),
  onSelect: (value) => console.log("activation:", value),
  onValueChange: (value) => console.log("radio value:", value),
  onValuesChange: (values) => console.log("checkbox values:", values),
});

controller.set({ value: "pro" });
controller.set({ values: ["email", "push"] });
controller.set({ open: true, highlightedValue: "push" });
controller.destroy();

createDropdownMenu(root) is idempotent per root. Calling it again for the same element returns the existing controller.

API

Initialization

create(scope?)

Find and bind uninitialized [data-slot="dropdown-menu"] descendants of scope (defaults to document). Returns DropdownMenuController[] for newly bound roots. To initialize the scope element itself, use createDropdownMenu.

import { create } from "@data-slot/dropdown-menu";

const controllers = create();

createDropdownMenu(root, options?)

Create a DropdownMenuController for one root element. JavaScript options take precedence over the corresponding data attributes. Calling this again for a bound root returns its existing controller; destroy it before rebinding with new options.

import { createDropdownMenu } from "@data-slot/dropdown-menu";

const controller = createDropdownMenu(element, {});

Slots

Runtime Slots

• dropdown-menu - Root container.
• dropdown-menu-trigger - Required button that toggles the menu and anchors its position.
• dropdown-menu-content - Required menu panel containing action and selection items.
• dropdown-menu-item - Action item with no owned selection state.
• dropdown-menu-radio-item - Single-select menu item.
• dropdown-menu-checkbox-item - Multi-select menu item.
• dropdown-menu-positioner - Optional authored positioning wrapper.
• dropdown-menu-portal - Optional authored portal wrapper that contains dropdown-menu-positioner.

Style-only Slots

• dropdown-menu-group - Groups related items.
• dropdown-menu-label - Non-interactive label.
• dropdown-menu-separator - Visual divider.
• dropdown-menu-shortcut - Optional keyboard shortcut hint; displaying it does not register a keyboard shortcut.

Composed Portal Markup

<div data-slot="dropdown-menu">
  <button data-slot="dropdown-menu-trigger">Options</button>
  <div data-slot="dropdown-menu-portal">
    <div data-slot="dropdown-menu-positioner">
      <div data-slot="dropdown-menu-content">...</div>
    </div>
  </div>
</div>

Data Attributes

Root and Content

Items

Defaults and Options

Default precedence is:

1. JavaScript options
2. Root data attributes
3. Item data-default-checked
4. Empty state

For radio items, root defaults win over item defaults. For checkbox items, root data-default-values wins over item data-default-checked.

Options

Notes:

• closeOnSelect defaults to true. Multi-select menus usually want false.
• onSelect tracks accepted user activation. It does not fire for programmatic state changes.
• onValueChange and onValuesChange follow the same silence rules as their DOM events.

Controller

interface DropdownMenuController {
  open(): void;
  close(): void;
  toggle(): void;
  set(detail: DropdownMenuSetDetail): void;
  readonly isOpen: boolean;
  readonly value: string | null;
  readonly values: string[];
  readonly highlightedValue: string | null;
  destroy(): void;
}

DropdownMenuSetDetail is a partial update:

interface DropdownMenuSetDetail {
  open?: boolean;
  value?: string | null;
  values?: string[];
  highlightedValue?: string | null;
  source?: "programmatic" | "restore";
}

Use value: null to clear radio selection, values: [] to clear checkbox selection, and highlightedValue: null to clear the highlight. source defaults to "programmatic".

set() applies fields in this order: value, values, open, highlightedValue.

• set({ value }) commits radio selection.
• set({ values }) commits checkbox selection.
• set({ open }) opens or closes the menu.
• set({ highlightedValue }) updates highlight only while the menu is open.
• Programmatic set() never emits dropdown-menu:select.
• No-op updates are silent.
• Unknown value / values targets are ignored, not thrown.

Downstream Wrapper Contract

This package does not ship Astro components, but downstream wrappers should mirror this authoring model:

• DropdownMenuItem renders data-slot="dropdown-menu-item".
• DropdownMenuRadioItem renders data-slot="dropdown-menu-radio-item" and requires value.
• DropdownMenuCheckboxItem renders data-slot="dropdown-menu-checkbox-item" and requires value.
• Radio and checkbox wrappers may expose defaultChecked, but root defaults still take precedence over item defaults.

Controller Destruction

destroy() permanently disposes the controller and hides any open surface without emitting an additional change event. Repeated destruction is safe; methods on the old controller become no-ops. Create a new controller on the same root to rebind it.

Focus restoration already queued by a close survives destruction.

Events

Outbound Events

dropdown-menu:select behavior:

• Fires only for user activation attempts. Disabled items and programmatic updates do not emit it.
• If event.preventDefault() is called, no selection state changes and no auto-close from selection occur.
• Programmatic updates never emit it.

dropdown-menu:value-change, dropdown-menu:values-change, onValueChange, and onValuesChange are silent on:

• initialization
• no-op commits
• ignored unknown targets

For dropdown-menu:values-change, changedValue, checked, and item are null when one programmatic update changes more than one checkbox at once.

Inbound Events

root.dispatchEvent(
  new CustomEvent("dropdown-menu:set", {
    detail: { value: "pro", source: "restore" },
  })
);

root.dispatchEvent(
  new CustomEvent("dropdown-menu:set", {
    detail: { values: ["email", "push"], open: true },
  })
);

Event Order

User radio selection:

1. dropdown-menu:select
2. dropdown-menu:value-change
3. dropdown-menu:open-change if the menu closes

User checkbox selection:

1. dropdown-menu:select
2. dropdown-menu:values-change
3. dropdown-menu:open-change if the menu closes

Programmatic selection:

1. dropdown-menu:set or controller.set(...)
2. dropdown-menu:value-change or dropdown-menu:values-change
3. No dropdown-menu:select

If closing the menu also clears an existing highlight, dropdown-menu:highlight-change is emitted before the close-side dropdown-menu:open-change.

Styling

Positioning

Placement attributes (data-side, data-align, data-side-offset, data-align-offset, data-avoid-collisions, data-collision-padding) resolve in this order:

1. JavaScript option
2. dropdown-menu-content
3. dropdown-menu-positioner
4. dropdown-menu root

The dropdown menu uses position: fixed by default and automatically positions itself relative to the trigger:

createDropdownMenu(root, {
  side: "bottom",
  align: "start",
  sideOffset: 4,
  alignOffset: 0,
  avoidCollisions: true,
  collisionPadding: 8,
});

When avoidCollisions is enabled, the menu may flip sides or shift within the viewport. The positioned element also receives --transform-origin for animation origins.

Keyboard Navigation

Migration Notes

If you currently use dropdown-menu as a picker:

• Replace picker-style dropdown-menu-item usage with dropdown-menu-radio-item or dropdown-menu-checkbox-item.
• Stop manually writing data-selected or data-checked.
• Listen to dropdown-menu:value-change or dropdown-menu:values-change for committed state.
• Push external restore/randomize/popstate/storage changes back in through controller.set(...) or dropdown-menu:set.
• Switch open-state listeners from dropdown-menu:change to dropdown-menu:open-change.

Deprecated APIs

The following compatibility APIs are deprecated and will be removed in the next major release:

// Deprecated open-state alias
root.addEventListener("dropdown-menu:change", (event) => {
  console.log(event.detail.open);
});

// Deprecated programmatic shape
root.dispatchEvent(
  new CustomEvent("dropdown-menu:set", { detail: { value: true } })
);

Use dropdown-menu:open-change and dropdown-menu:set { open: boolean } instead.

License

MIT