Dropdown Menu

Displays a menu to the user — such as a set of actions or functions — triggered by a button.

Requires JS

This component requires the dropdown_menu and dropdown_menu_sub stimulus controller.

Caveats

When using as_child: true, it sanitizes the output of the child element's children with Rails sanitize helper.

To allow more tags or attributes, edit Base#sanitize_as_child according to your preference.

Anatomy

DropdownMenu do |d|
  d.trigger

  d.content do
    d.label
    d.separator
    
    d.group do
      d.item
      d.item

      d.sub do |sub|
        sub.trigger
        
        sub.content do
          d.item
          d.item
        end
      end
    end
  end
end

API Reference

DropdownMenu

Name	Type	Default
`open:`	`boolean`	`false`
Controls the initial open state of the dropdown menu. When true, the menu will be visible on render.
`attributes`	`keyword arguments`

DropdownMenu#trigger

Name	Type	Default
`as_child:`	`boolean`	`false`
When true, merges the trigger functionality with the child element instead of creating a wrapper div.
`attributes`	`keyword arguments`

DropdownMenu#content

The container for the dropdown menu items. Positioned relative to the trigger with configurable placement and alignment.

Name	Type	Default
`side:`	`symbol`	`:bottom`
Controls which side of the trigger the content appears on. `:top \| :left \| :bottom \| :right`
`align:`	`symbol`	`:center`
Controls the alignment of the content relative to the trigger. `:start \| :center \| :end`
`attributes`	`keyword arguments`

DropdownMenu#label

Name	Type
`attributes`	`keyword arguments`

DropdownMenu#item

Name	Type	Default
`variant:`	`symbol`	`:default`
Visual style variant for the item. `:default \| :destructive`
`as_child:`	`boolean`	`false`
When true, merges the item functionality with the child element instead of creating a wrapper div.
`disabled:`	`boolean`	`false`
When true, the item is visually disabled and cannot be selected or focused.
`attributes`	`keyword arguments`

DropdownMenu#item_to

A Rails-integrated menu item that wraps button_to for form submissions. Inherits all button_to functionality while maintaining dropdown styling.

Name	Type	Default
`name`	`string`	`nil`
The text content of the button (first argument to button_to).
`options`	`hash`	`nil`
URL or path options passed to button_to (second argument).
`html_options`	`hash`	`nil`
HTML attributes and options passed to button_to. Also supports `variant:` and `disabled:` options.

DropdownMenu#separator

A visual separator line between menu items. Includes proper ARIA attributes for accessibility.

Name	Type
`attributes`	`keyword arguments`

DropdownMenu#group

A semantic grouping container for related menu items. Provides proper ARIA role for screen readers.

Name	Type
`attributes`	`keyword arguments`

DropdownMenu#sub

Creates a nested submenu within the dropdown. Generates unique ARIA IDs for proper accessibility relationships.

Name	Type	Default
`sub_trigger`	`method`
Use sub_trigger method to create the trigger for opening the submenu.
`sub_content`	`method`
Use sub_content method to create the submenu content container.
`attributes`	`keyword arguments`

DropdownMenuSub#trigger

The trigger element for opening a submenu. Only available within a sub block. Handles submenu-specific keyboard interactions.

Name	Type	Default
`as_child:`	`boolean`	`false`
When true, merges the trigger functionality with the child element instead of creating a wrapper div.
`attributes`	`keyword arguments`

DropdownMenuSub#content

The container for submenu items. Only available within a sub block. Positioned relative to the sub trigger with automatic collision detection.

Name	Type	Default
`side:`	`symbol`	`:right`
Controls which side of the sub trigger the content appears on. `:top \| :left \| :bottom \| :right`
`align:`	`symbol`	`:start`
Controls the alignment of the submenu content relative to the trigger. `:start \| :center \| :end`
`attributes`	`keyword arguments`

Keyboard Interactions

Key	Description
Space	When focus is on trigger, opens the dropdown menu and focuses the first item. When focus is on an item, activates the focused item.
Enter	When focus is on trigger, opens the dropdown menu and focuses the first item. When focus is on an item, activates the focused item.
ArrowDown	When focus is on trigger, opens the dropdown menu. When focus is on an item, moves focus to the next item.
ArrowUp	When focus is on an item, moves focus to the previous item.
Esc	Closes the dropdown menu and moves focus to trigger.

Examples

On This Page

Anatomy
API Reference
Keyboard Interactions
Examples

Getting Started

Components