Corex.Menu (Corex v0.1.0-beta.4)

Phoenix implementation of Zag.js Menu.

Examples

List

You must use Corex.Tree.Item struct for items.

The value for each item is optional, useful for the API to identify the item.

You can specify disabled for each item and nested children.

<.menu
  class="menu"
  items={[
    %Corex.Tree.Item{
      id: "edit",
      label: "Edit"
    },
    %Corex.Tree.Item{
      id: "duplicate",
      label: "Duplicate"
    },
    %Corex.Tree.Item{
      id: "delete",
      label: "Delete"
    }
  ]}
>
  <:trigger>Actions</:trigger>
  <:indicator>
    <.heroicon name="hero-chevron-down" />
  </:indicator>
</.menu>

Nested Menu

Use children in Corex.Tree.Item to create nested menus.

<.menu
  class="menu"
  items={[
    %Corex.Tree.Item{
      id: "new-tab",
      label: "New tab"
    },
    %Corex.Tree.Item{
      id: "share",
      label: "Share",
      children: [
        %Corex.Tree.Item{
          id: "messages",
          label: "Messages"
        },
        %Corex.Tree.Item{
          id: "airdrop",
          label: "Airdrop"
        },
        %Corex.Tree.Item{
          id: "whatsapp",
          label: "WhatsApp"
        }
      ]
    },
    %Corex.Tree.Item{
      id: "print",
      label: "Print..."
    }
  ]}
>
  <:trigger>Click me</:trigger>
</.menu>

Nested Menu with Custom Indicator

Use the :nested_indicator slot to customize the indicator shown on items with nested menus (defaults to arrow right →).

<.menu
  class="menu"
  items={[
    %Corex.Tree.Item{
      id: "share",
      label: "Share",
      children: [
        %Corex.Tree.Item{id: "messages", label: "Messages"}
      ]
    }
  ]}
>
  <:trigger>Click me</:trigger>
  <:nested_indicator>
    <.heroicon name="hero-arrow-right" />
  </:nested_indicator>
</.menu>

Grouped Items

Use group in Corex.Tree.Item to group related items. The group value is used as the section label (same as select).

<.menu
  class="menu"
  items={[
    %Corex.Tree.Item{
      id: "edit",
      label: "Edit",
      group: "Actions"
    },
    %Corex.Tree.Item{
      id: "duplicate",
      label: "Duplicate",
      group: "Actions"
    },
    %Corex.Tree.Item{
      id: "account-1",
      label: "Account 1",
      group: "Accounts"
    },
    %Corex.Tree.Item{
      id: "account-2",
      label: "Account 2",
      group: "Accounts"
    }
  ]}
>
  <:trigger>Actions</:trigger>
  <:indicator>
    <.heroicon name="hero-chevron-down" />
  </:indicator>
</.menu>

Use as Navigation

Set redirect on the component so selecting an item navigates to the item's id (e.g. path). Per item, choose the navigation kind explicitly via the item's :redirect field:

:href (default) - full page redirect via window.location (safe everywhere)
:patch - LiveView js().patch(url) (caller asserts: same LV mount + matching live route)
:navigate - LiveView js().navigate(url) (caller asserts: another LV in the same live_session)
false - disable redirect for this item (e.g. let your on_select server handler decide)

Set new_tab: true on an item to open its destination in a new tab via window.open.

Breaking change

Earlier versions were no-ops when LiveView was connected (the server handler was expected to call redirect/2). The hook now performs a hard :href redirect by default. Opt back into the old behavior by setting the per-item redirect: false, or opt into LV-aware navigation with redirect: :patch / redirect: :navigate.

Controller

When not connected to LiveView, the hook always performs a full page redirect via window.location.

<.menu
  class="menu"
  redirect
  items={[
    %Corex.Tree.Item{id: "/", label: "Home"},
    %Corex.Tree.Item{id: "/docs", label: "Docs"},
    %Corex.Tree.Item{id: "https://example.com", label: "External", new_tab: true}
  ]}
>
  <:trigger>Navigate</:trigger>
  <:indicator>
    <.heroicon name="hero-chevron-down" />
  </:indicator>
</.menu>

LiveView

When connected to LiveView, use on_select and redirect in the callback. The payload includes value (the item id).

defmodule MyAppWeb.NavMenuLive do
  use MyAppWeb, :live_view

  def handle_event("handle_select", %{"value" => value}, socket) do
    {:noreply, push_navigate(socket, to: value)}
  end

  def render(assigns) do
    ~H"""
    <.menu
      class="menu"
      redirect
      on_select="handle_select"
      items={[
        %Corex.Tree.Item{id: "/", label: "Home"},
        %Corex.Tree.Item{id: "/docs", label: "Docs"}
      ]}
    >
      <:trigger>Navigate</:trigger>
      <:indicator>
        <.heroicon name="hero-chevron-down" />
      </:indicator>
    </.menu>
    """
  end
end

API Control

In order to use the API, you must use an id on the component

Client-side

<button phx-click={Corex.Menu.set_open("my-menu", true)}>
  Open Menu
</button>

Server-side

def handle_event("open_menu", _, socket) do
  {:noreply, Corex.Menu.set_open(socket, "my-menu", true)}
end

Styling

Use data attributes to target elements:

[data-scope="menu"][data-part="root"] {}
[data-scope="menu"][data-part="trigger"] {}
[data-scope="menu"][data-part="positioner"] {}
[data-scope="menu"][data-part="content"] {}
[data-scope="menu"][data-part="item"] {}
[data-scope="menu"][data-part="separator"] {}
[data-scope="menu"][data-part="item-group"] {}
[data-scope="menu"][data-part="item-group-label"] {}

If you wish to use the default Corex styling, you can use the class menu on the component. This requires to install Mix.Tasks.Corex.Design first and import the component css file.

@import "../corex/main.css";
@import "../corex/tokens/themes/neo/light.css";
@import "../corex/components/menu.css";

You can then use modifiers

<.menu class="menu menu--accent menu--lg">
</.menu>

Summary

Components

menu(assigns)

Renders a menu component.

API

set_open(menu_id, open)

Sets the menu open state from client-side. Returns a Phoenix.LiveView.JS command.

set_open(socket, menu_id, open)

Sets the menu open state from server-side. Pushes a LiveView event.

Components

menu(assigns)

Renders a menu component.

You can use either:

The :items attribute for programmatic item generation from a list of %Corex.Tree.Item{} structs
Manual item definition with full control using slots

When using :items, each item MUST be a %Corex.Tree.Item{} struct with:

:id (required) - unique identifier for the item
:label (required) - label text for the item
:children (optional) - list of nested %Corex.Tree.Item{} structs for nested menus
:disabled (optional, default: false) - whether the item is disabled
:group (optional) - group identifier for grouping items
:meta (optional) - map containing additional metadata

Attributes

id (:string) - The id of the menu, useful for API to identify the menu.
items (:list) - The items of the menu, must be a list of %Corex.Tree.Item{} structs. Defaults to nil.
positioning (Corex.Positioning) - Floating UI positioning (placement, gutter, flip, etc.). Defaults to %Corex.Positioning{hide_when_detached: true, strategy: "fixed", placement: "bottom", gutter: 8, shift: 0, overflow_padding: 0, arrow_padding: 4, flip: true, slide: false, overlap: false, same_width: false, fit_viewport: true, offset: nil}.
close_on_select (:boolean) - Whether to close the menu when an item is selected. Defaults to true.
loop_focus (:boolean) - Whether to loop focus when navigating with keyboard. Defaults to false.
typeahead (:boolean) - Whether to enable typeahead navigation. Defaults to true.
composite (:boolean) - Whether the menu is composed with other composite widgets. Defaults to false.
value (:string) - The value of the item to highlight when the menu opens. Defaults to nil.
disabled (:boolean) - Whether the menu trigger is disabled. Defaults to false.
dir (:string) - The direction of the menu. When nil, derived from document (html lang + config :rtl_locales). Defaults to nil. Must be one of nil, "ltr", or "rtl".
orientation (:string) - Layout orientation for CSS and ignored attribute lists. Defaults to "vertical". Must be one of "horizontal", or "vertical".
aria_label (:string) - The aria-label for the menu. Defaults to nil.
on_select (:string) - The server event name when an item is selected. Defaults to nil.
on_select_client (:string) - The client event name when an item is selected. Defaults to nil.
redirect (:boolean) - When true, selecting an item triggers redirect-on-select using the item's id (or :to) as the destination. Each item picks the navigation kind via its :redirect field (:href (default) | :patch | :navigate | false); set :new_tab to open in a new tab.
Defaults to false.
on_open_change (:string) - The server event name when the menu opens or closes. Defaults to nil.
on_open_change_client (:string) - The client event name when the menu opens or closes. Defaults to nil.
Global attributes are accepted.

Slots

trigger (required) - The trigger button content. Accepts attributes:
- class (:string)
indicator - Optional indicator content (e.g., icon or arrow). Accepts attributes:
- class (:string)
nested_indicator - Optional indicator content for nested menu triggers (defaults to arrow right). Accepts attributes:
- class (:string)
item - Optional. Custom content for each menu item. Use :let={item} to receive the item (Corex.Tree.Item). Accepts attributes:
- class (:string)

API

set_open(menu_id, open)

Sets the menu open state from client-side. Returns a Phoenix.LiveView.JS command.

Examples

<button phx-click={Corex.Menu.set_open("my-menu", true)}>
  Open Menu
</button>

set_open(socket, menu_id, open)

Sets the menu open state from server-side. Pushes a LiveView event.

Examples

def handle_event("open_menu", _params, socket) do
  socket = Corex.Menu.set_open(socket, "my-menu", true)
  {:noreply, socket}
end