Dropdown Menu

A menu of actions or options, triggered by a button.

Installation

Shadwire follows shadcn/ui's open code model: the component's source is copied into your application and becomes yours. Install it with the CLI:

shadwire add dropdown-menu --yes

The dropdown-menu registry item installs these files:

app/components/ui_component.rb
app/components/ui/dropdown_menu_component.rb
app/components/ui/dropdown_menu/trigger_component.rb
app/components/ui/dropdown_menu/content_component.rb
app/components/ui/dropdown_menu/item_component.rb
app/components/ui/dropdown_menu/label_component.rb
app/components/ui/dropdown_menu/separator_component.rb
app/components/ui/dropdown_menu/group_component.rb
app/components/ui/dropdown_menu/shortcut_component.rb
app/components/ui/button_component.rb
app/helpers/ui/dropdown_menu_helper.rb
app/helpers/ui/button_helper.rb
app/javascript/controllers/ui_dropdown_menu_controller.js
vendor/shadwire/shadwire.css

This component uses Stimulus, so the application needs importmap-rails and stimulus-rails with automatic controller loading.

Haven't installed the CLI yet? gem install shadwire, then shadwire init.

Usage

The ui-dropdown-menu controller implements the WAI-ARIA menu pattern: roving focus across the items, ↑/↓ with wrapping, Home/End, typeahead matching, and closing with Esc, Tab, or a click outside.

<%= ui_dropdown_menu do %>
  <%= ui_dropdown_menu_trigger(variant: :outline) { "Open" } %>
  <%= ui_dropdown_menu_content do %>
    <%= ui_dropdown_menu_label { "My account" } %>
    <%= ui_dropdown_menu_separator %>
    <%= ui_dropdown_menu_item do %>
      Profile
      <%= ui_dropdown_menu_shortcut { "⇧⌘P" } %>

<%= ui_dropdown_menu do %>
  <%= ui_dropdown_menu_trigger(variant: :outline) { "Open" } %>
  <%= ui_dropdown_menu_content do %>
    <%= ui_dropdown_menu_label { "My account" } %>
    <%= ui_dropdown_menu_separator %>
    <%= ui_dropdown_menu_item do %>
      Profile
      <%= ui_dropdown_menu_shortcut { "⇧⌘P" } %>
    <% end %>
  <% end %>
<% end %>

Or render the components directly:

<%= render Ui::DropdownMenuComponent.new do %>
  <%= render Ui::DropdownMenu::TriggerComponent.new do %>
    Open
  <% end %>
  <%= render Ui::DropdownMenu::ContentComponent.new do %>
    <%= render Ui::DropdownMenu::ItemComponent.new(variant: :destructive) do %>
      Delete
    <% end %>

<%= render Ui::DropdownMenuComponent.new do %>
  <%= render Ui::DropdownMenu::TriggerComponent.new do %>
    Open
  <% end %>
  <%= render Ui::DropdownMenu::ContentComponent.new do %>
    <%= render Ui::DropdownMenu::ItemComponent.new(variant: :destructive) do %>
      Delete
    <% end %>
  <% end %>
<% end %>

Composition

DropdownMenu (data-controller="ui-dropdown-menu")
|-- DropdownMenu::Trigger (Button, aria-haspopup="menu")
`-- DropdownMenu::Content (role="menu")
    |-- DropdownMenu::Label
    |-- DropdownMenu::Separator
    |-- DropdownMenu::Group
    |   `-- DropdownMenu::Item (button/link) > DropdownMenu::Shortcut
    `-- DropdownMenu::Item (variant: :destructive)

DropdownMenu (data-controller="ui-dropdown-menu")
|-- DropdownMenu::Trigger (Button, aria-haspopup="menu")
`-- DropdownMenu::Content (role="menu")
    |-- DropdownMenu::Label
    |-- DropdownMenu::Separator
    |-- DropdownMenu::Group
    |   `-- DropdownMenu::Item (button/link) > DropdownMenu::Shortcut
    `-- DropdownMenu::Item (variant: :destructive)

CheckboxItem, RadioItem and submenus are out of scope for this version.

Examples

Default

A label, groups, and items with shortcuts. Arrows navigate, typeahead matches by prefix, Esc closes.

<%= ui_dropdown_menu do %>
  <%= ui_dropdown_menu_trigger(variant: :outline) { "Open" } %>
  <%= ui_dropdown_menu_content(class: "w-56") do %>
    <%= ui_dropdown_menu_label { "My account" } %>
    <%= ui_dropdown_menu_separator %>
    <%= ui_dropdown_menu_group do %>
      <%= ui_dropdown_menu_item do %>
        Profile

<%= ui_dropdown_menu do %>
  <%= ui_dropdown_menu_trigger(variant: :outline) { "Open" } %>
  <%= ui_dropdown_menu_content(class: "w-56") do %>
    <%= ui_dropdown_menu_label { "My account" } %>
    <%= ui_dropdown_menu_separator %>
    <%= ui_dropdown_menu_group do %>
      <%= ui_dropdown_menu_item do %>
        Profile
        <%= ui_dropdown_menu_shortcut { "⇧⌘P" } %>
      <% end %>
      <%= ui_dropdown_menu_item do %>
        Settings
        <%= ui_dropdown_menu_shortcut { "⌘," } %>
      <% end %>
    <% end %>
  <% end %>
<% end %>

Inset, links and destructive

inset: lines up with items that have icons; tag: :a makes it a link; variant: :destructive marks dangerous actions.

<%= ui_dropdown_menu do %>
  <%= ui_dropdown_menu_trigger(variant: :outline) { "Actions" } %>
  <%= ui_dropdown_menu_content(class: "w-56") do %>
    <%= ui_dropdown_menu_label(inset: true) { "Application" } %>
    <%= ui_dropdown_menu_item(inset: true) { "Duplicate" } %>
    <%= ui_dropdown_menu_item(disabled: true, inset: true) { "Unavailable" } %>
    <%= ui_dropdown_menu_separator %>
    <%= ui_dropdown_menu_item(tag: :a, href: "#docs", inset: true) { "Documentation" } %>

<%= ui_dropdown_menu do %>
  <%= ui_dropdown_menu_trigger(variant: :outline) { "Actions" } %>
  <%= ui_dropdown_menu_content(class: "w-56") do %>
    <%= ui_dropdown_menu_label(inset: true) { "Application" } %>
    <%= ui_dropdown_menu_item(inset: true) { "Duplicate" } %>
    <%= ui_dropdown_menu_item(disabled: true, inset: true) { "Unavailable" } %>
    <%= ui_dropdown_menu_separator %>
    <%= ui_dropdown_menu_item(tag: :a, href: "#docs", inset: true) { "Documentation" } %>
    <%= ui_dropdown_menu_separator %>
    <%= ui_dropdown_menu_item(variant: :destructive) do %>
      <%= ui_icon("trash-2") %>
      Delete
    <% end %>
  <% end %>
<% end %>

API reference

Every part accepts class / class_name and **attrs.

Component	Argument	Default	Description
`DropdownMenu::Trigger`	`variant`, `size`	`:outline`, `:default`	Passed to the `Ui::ButtonComponent` it renders.
`DropdownMenu::Content`	`side`, `align`	`:bottom`, `:start`	Menu positioning, through utilities.
`DropdownMenu::Item`	`variant`	`:default`	`:destructive` marks dangerous actions.
`DropdownMenu::Item`	`inset`, `disabled`	`false`	Indents to line up with icons; a disabled item is skipped during navigation.
`DropdownMenu::Item`	`tag`	`:button`	Use `:a` with `href` for link items.