Renders a dropdown menu with toggle button, floating menu panel, and optional submenus.

The toggle defaults to a <.button> with the label text and a chevron icon. When the :toggle slot is provided, it replaces the default button while preserving all ARIA attributes on the wrapper element. The menu panel is positioned via Floating UI and supports both click and hover interactions.

Examples

<.dropdown>
  <.dropdown_link navigate={~p"/profile"}>Profile</.dropdown_link>
  <.dropdown_link navigate={~p"/settings"}>Settings</.dropdown_link>
</.dropdown>

<.dropdown label="Actions" placement="bottom-end" class="w-48">
  <.dropdown_button phx-click="edit">Edit</.dropdown_button>
  <.dropdown_button phx-click="duplicate">Duplicate</.dropdown_button>
  <.dropdown_separator />
  <.dropdown_button phx-click="delete" class="text-red-600">Delete</.dropdown_button>
</.dropdown>

<.dropdown open_on_hover hover_open_delay={150} hover_close_delay={200}>
  <:toggle>
    <span class="text-sm underline cursor-pointer">Hover me</span>
  </:toggle>
  <.dropdown_link navigate={~p"/option-a"}>Option A</.dropdown_link>
  <.dropdown_link navigate={~p"/option-b"}>Option B</.dropdown_link>
</.dropdown>

Attributes

• id (:string) - The unique identifier for the dropdown component. If not provided, one will be automatically generated.

• label (:string) - The text label for the default dropdown toggle button. Only used when no custom toggle is provided via the :toggle slot.

  Defaults to "Menu".

• class (:any) - Additional CSS classes for the dropdown menu panel. Useful for controlling width, max-height, and other menu-specific styles.

  Defaults to nil.

• container_class (:string) - Additional CSS classes for the dropdown's outer container. Affects the positioning wrapper element.

  Defaults to nil.

• toggle_class (:string) - Additional CSS classes for the dropdown toggle button. Only applies to the default toggle button, not custom toggles.

  Defaults to nil.

• disabled (:boolean) - When true, disables the dropdown toggle and prevents the menu from opening. Defaults to false.

• placement (:string) - Controls the placement of the dropdown menu relative to its toggle button. Supports different positions with automatic repositioning when needed.

  The possible values are: top, top-start, top-end, right, right-start, right-end, bottom, bottom-start, bottom-end, left, left-start, left-end

  Defaults to "bottom-start".

• animation (:string) - Base animation classes applied to the dropdown menu. Controls the transition timing and easing function.

  Defaults to "transition ease-in-out duration-150".

• animation_enter (:string) - Classes applied when the dropdown menu enters. Usually defines the final state of the animation.

  Defaults to "opacity-100 scale-100".

• animation_leave (:string) - Classes applied when the dropdown menu leaves. Usually defines the initial state of the exit animation.

  Defaults to "opacity-0 scale-95".

• open_on_hover (:boolean) - When true, opens the dropdown menu on mouse hover instead of click. Can be combined with hover delays for better user experience.

  Defaults to false.

• hover_open_delay (:integer) - Delay in milliseconds before opening the menu when hovering. Only applies when open_on_hover is true.

  Defaults to 0.

• hover_close_delay (:integer) - Delay in milliseconds before closing the menu when mouse leaves. Only applies when open_on_hover is true.

  Defaults to 0.

Slots

• inner_block (required) - The content of the dropdown menu. Usually contains dropdown_link, dropdown_button, or other dropdown components.

• toggle - Optional custom toggle element. When provided, replaces the default button toggle while maintaining proper accessibility attributes.

  Accepts attributes:

  • class (:any) - Additional CSS classes for the wrapper of the custom toggle element.

• submenu - Defines a submenu panel that opens when its trigger is activated. Each submenu must have a unique id that matches the submenu attribute of the corresponding dropdown_submenu_trigger. Submenus are rendered as siblings to the main menu panel to avoid overflow clipping issues.

  Accepts attributes:

  • id (:string) (required) - Unique ID referenced by trigger's submenu attribute.
  • class (:any) - Additional CSS classes for the submenu panel.
  • placement (:string) - Placement relative to trigger: right-start, right-end, left-start, left-end.

Renders an action menu item as a <button type="button">.

Use this for menu items that trigger actions (event handlers, JS commands) rather than navigation. The item renders with role="menuitem" and participates in keyboard navigation. Clicking or activating the item via Enter / Space fires the button's click event and closes the dropdown.

Supports the standard disabled attribute. Disabled buttons are visually dimmed and skipped during keyboard navigation.

Examples

<.dropdown_button phx-click={JS.push("update-view", value: %{view: "grid"})}>
  Grid
</.dropdown_button>

<.dropdown_button phx-click="update-view" phx-value-view="list">
  List
</.dropdown_button>

<.dropdown_button phx-click={Fluxon.open_dialog("new-user-dialog")}>
  New User
</.dropdown_button>

<.dropdown_button disabled>
  Unavailable Option
</.dropdown_button>

Attributes

• id (:string) - Optional unique identifier for the button element. When not provided, no id attribute will be rendered.

  Defaults to nil.

• class (:any) - Additional CSS classes for the button element. The new classes will be merged with the default styles. Defaults to nil.

• Global attributes are accepted. Additional HTML attributes to apply to the button element. Useful for adding event handlers or data attributes. Supports all globals plus: ["autofocus", "disabled", "form", "formaction", "formenctype", "formmethod", "formnovalidate", "formtarget", "name", "type", "value"].

Slots

• inner_block (required) - The content of the button item. Usually contains text but can include icons or other elements.

Renders an arbitrary content area within a dropdown menu.

Custom content is excluded from keyboard navigation (ArrowUp / ArrowDown skip it entirely). However, focusable elements inside the container remain accessible via Tab. Hovering a custom content area clears the current item highlight and closes any open child submenu, matching the behavior of headers and separators.

Examples

<.dropdown_custom class="flex items-center p-2">
  <img src="https://i.pravatar.cc/150?u=1" alt="Avatar" class="size-9 rounded-full" />
  <div class="flex flex-col ml-3 mr-10">
    <span class="text-sm font-medium leading-snug">Emma Johnson</span>
    <span class="text-xs text-zinc-500 leading-snug">emma@acme.com</span>
  </div>
  <.badge color="red" class="ml-auto">PRO</.badge>
</.dropdown_custom>

<.dropdown_custom class="flex items-center gap-x-10 bg-zinc-100/70 rounded-lg p-2">
  <div class="flex flex-col">
    <span class="text-sm font-medium">Available Tokens</span>
    <span class="text-sm text-zinc-500">Only 75 tokens available</span>
  </div>
  <.button size="xs" class="ml-auto">Manage</.button>
</.dropdown_custom>

Attributes

• class (:any) - Additional CSS classes for the custom content container. The new classes will be merged with the default styles. Defaults to nil.
• Global attributes are accepted. Additional HTML attributes to apply to the custom content container.

Slots

• inner_block (required) - The custom content to be rendered. Can contain any HTML or components for creating complex dropdown items.

Renders a non-interactive section header within a dropdown menu.

Headers label groups of related menu items with smaller, muted text. They are not part of keyboard navigation and cannot be selected. Hovering a header clears the current item highlight and closes any open submenu at the same level.

Examples

<.dropdown_header>Account Settings</.dropdown_header>
<.dropdown_link patch={~p"/profile"}>Edit Profile</.dropdown_link>
<.dropdown_link patch={~p"/settings"}>Preferences</.dropdown_link>

<.dropdown_header>Help & Support</.dropdown_header>
<.dropdown_link navigate={~p"/faq"}>FAQ</.dropdown_link>
<.dropdown_link navigate={~p"/contact"}>Contact Us</.dropdown_link>

Attributes

• class (:any) - Additional CSS classes for the header element. The new classes will be merged with the default styles. Defaults to nil.
• Global attributes are accepted. Additional HTML attributes to apply to the header element.

Slots

• inner_block (required) - The content of the header. Usually contains text but can include other elements for complex headers.

Renders a navigable menu item as a Phoenix <.link>.

Supports LiveView navigation (navigate, patch) and standard links (href). The item renders with role="menuitem" and participates in keyboard navigation. Clicking or activating the item via Enter / Space triggers navigation and closes the dropdown.

Disable a link item with the data-disabled attribute, since HTML anchors do not support the native disabled attribute. Disabled links are visually dimmed and skipped during keyboard navigation.

Examples

<.dropdown_link navigate={~p"/dashboard"}>
  Dashboard
</.dropdown_link>

<.dropdown_link patch={~p"/settings"}>
  Settings
</.dropdown_link>

<.dropdown_link href="https://example.com" target="_blank">
  External Link
</.dropdown_link>

<.dropdown_link navigate={~p"/admin"} data-disabled>
  Admin Panel
</.dropdown_link>

Attributes

• id (:string) - Optional unique identifier for the link element. When not provided, no id attribute will be rendered.

  Defaults to nil.

• class (:any) - Additional CSS classes for the link element. The new classes will be merged with the default styles. Defaults to nil.

• Global attributes are accepted. Additional HTML attributes for the link element. Supports both standard anchor attributes and LiveView navigation options. Supports all globals plus: ["navigate", "patch", "href", "replace", "method", "csrf_token", "download", "hreflang", "referrerpolicy", "rel", "target", "type"].

Slots

• inner_block (required) - The content of the link item. Usually contains text but can include icons or other elements.

Renders a horizontal divider between groups of dropdown items.

The separator renders as a <div> with aria-hidden="true" so it is invisible to assistive technologies. It is not part of keyboard navigation. Hovering a separator clears the current item highlight.

Examples

<.dropdown_link patch={~p"/profile"}>Edit Profile</.dropdown_link>
<.dropdown_link patch={~p"/settings"}>Preferences</.dropdown_link>
<.dropdown_separator />
<.dropdown_link href={~p"/sign_out"} method="delete">Sign Out</.dropdown_link>

Attributes

• class (:any) - Additional CSS classes for the separator element. The new classes will be merged with the default styles. Defaults to nil.
• Global attributes are accepted. Additional HTML attributes to apply to the separator element.

Renders a menu item that opens a linked submenu panel.

The trigger displays the slot content with a right-pointing chevron icon. It links to a sibling :submenu slot by matching the submenu attribute to the slot's id. The trigger and panel are rendered as DOM siblings (flat structure) to avoid overflow clipping.

Opening behavior:

• Keyboard: ArrowRight opens the submenu and highlights its first item. Enter / Space also opens the submenu (same as ArrowRight).
• Mouse: Hovering the trigger opens the submenu after an 80ms intent delay. Moving the cursor away before the delay elapses cancels the open.

The trigger receives aria-haspopup="menu", aria-expanded, and aria-controls attributes automatically. Its id defaults to "{submenu}-trigger".

Examples

<.dropdown>
  <.dropdown_link navigate={~p"/profile"}>Profile</.dropdown_link>

  <.dropdown_submenu_trigger submenu="more-options">
    More Options
  </.dropdown_submenu_trigger>

  <:submenu id="more-options">
    <.dropdown_link navigate={~p"/settings"}>Settings</.dropdown_link>
    <.dropdown_link navigate={~p"/preferences"}>Preferences</.dropdown_link>
  </:submenu>
</.dropdown>

Attributes

• submenu (:string) (required) - The ID of the submenu panel this trigger opens. Must match the id attribute of a :submenu slot.

• class (:any) - Additional CSS classes for the submenu trigger. Defaults to nil.

• disabled (:boolean) - When true, the submenu trigger is disabled and cannot be activated. Defaults to false.

Slots

• inner_block (required) - The content of the trigger. Usually text describing the submenu.