Corex.Menu (Corex v0.1.0-rc.1)

Phoenix implementation of Zag.js Menu.

Anatomy

List

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

The value for each item is optional in maps passed to Corex.Tree.new/1 (auto-generated when omitted).

You can specify disabled for each item and nested children.

<.menu
  class="menu"
  items={[
    %Corex.Tree.Item{
      value: "edit",
      label: "Edit"
    },
    %Corex.Tree.Item{
      value: "duplicate",
      label: "Duplicate"
    },
    %Corex.Tree.Item{
      value: "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{
      value: "new-tab",
      label: "New tab"
    },
    %Corex.Tree.Item{
      value: "share",
      label: "Share",
      children: [
        %Corex.Tree.Item{
          value: "messages",
          label: "Messages"
        },
        %Corex.Tree.Item{
          value: "airdrop",
          label: "Airdrop"
        },
        %Corex.Tree.Item{
          value: "whatsapp",
          label: "WhatsApp"
        }
      ]
    },
    %Corex.Tree.Item{
      value: "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{
      value: "share",
      label: "Share",
      children: [
        %Corex.Tree.Item{value: "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{
      value: "edit",
      label: "Edit",
      group: "Actions"
    },
    %Corex.Tree.Item{
      value: "duplicate",
      label: "Duplicate",
      group: "Actions"
    },
    %Corex.Tree.Item{
      value: "account-1",
      label: "Account 1",
      group: "Accounts"
    },
    %Corex.Tree.Item{
      value: "account-2",
      label: "Account 2",
      group: "Accounts"
    }
  ]}
>
  <:trigger>Actions</:trigger>
  <:indicator>
    <.heroicon name="hero-chevron-down" />
  </:indicator>
</.menu>

Patterns

Navigation

Set redirect on the component so selecting an item navigates to the item's value (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{value: "/", label: "Home"},
    %Corex.Tree.Item{value: "/docs", label: "Docs"},
    %Corex.Tree.Item{value: "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 value).

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{value: "/", label: "Home"},
        %Corex.Tree.Item{value: "/docs", label: "Docs"}
      ]}
    >
      <:trigger>Navigate</:trigger>
      <:indicator>
        <.heroicon name="hero-chevron-down" />
      </:indicator>
    </.menu>
    """
  end
end

API

Requires a stable id on <.menu>.

Function	Action	Returns
`set_open/2`	Set open state (client)	`%Phoenix.LiveView.JS{}`
`set_open/3`	Set open state (server)	`socket`

set_open

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

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

Events

Server events

Event	When	Payload
`on_select="menu_selected"`	Item selected	`%{"id" => id, "value" => value}`
`on_open_change="menu_open_changed"`	Open state changes	`%{"id" => id, "open" => open}`

on_select

<.menu
  class="menu"
  on_select="menu_selected"
  items={[
    %Corex.Tree.Item{value: "menu", label: "Menu"},
    %Corex.Tree.Item{value: "combobox", label: "Combobox"},
    %Corex.Tree.Item{value: "select", label: "Select"}
  ]}
>
  <:trigger>Actions</:trigger>
  <:indicator><.heroicon name="hero-chevron-down" /></:indicator>
</.menu>

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

on_open_change

<.menu
  class="menu"
  on_open_change="menu_open_changed"
  items={[
    %Corex.Tree.Item{value: "menu", label: "Menu"},
    %Corex.Tree.Item{value: "combobox", label: "Combobox"},
    %Corex.Tree.Item{value: "select", label: "Select"}
  ]}
>
  <:trigger>Actions</:trigger>
  <:indicator><.heroicon name="hero-chevron-down" /></:indicator>
</.menu>

Client events

Event	When	`event.detail`
`on_select_client="menu-selected"`	Item selected	`id`, `value`
`on_open_change_client="menu-open-changed"`	Open state changes	`id`, `open`

Summary

Components

menu(assigns)

Renders a menu component.

API

set_open(menu_id, open)

Set menu open state from a control (phx-click). Targets the root with id menu:<id>.

set_open(socket, menu_id, open)

Set open state from handle_event. Pushes menu_set_open.

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:

:value - Unique value for the item (used by the client and for value / selection APIs)
: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 value (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)

Set menu open state from a control (phx-click). Targets the root with id menu:<id>.

<.action phx-click={Corex.Menu.set_open("my-menu", true)}>Open</.action>
<.menu id="my-menu" class="menu" items={[%Corex.Tree.Item{label: "Edit", value: "edit"}]}>
  <:trigger>Actions</:trigger>
</.menu>

document.querySelector('[id="menu:my-menu"]')?.dispatchEvent(
  new CustomEvent("corex:menu:set-open", {
    bubbles: false,
    detail: { open: true },
  })
);

set_open(socket, menu_id, open)

Set open state from handle_event. Pushes menu_set_open.

<.action phx-click="open_menu">Open</.action>
<.menu id="my-menu" class="menu" items={[%Corex.Tree.Item{label: "Edit", value: "edit"}]}>
  <:trigger>Actions</:trigger>
</.menu>

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