Nav Link

Updated Oct 19, 2026 v0.0.10

v0.0.10StableHeadlessStatelessAccessibleApache-2.0

Installation mix mishka.ui.gen.headless nav_link

Source View Source

Overview of the Phoenix and LiveView Headless Nav Link Component

The Mishka Chelekom Headless Nav Link is a navigation item for Phoenix and LiveView. Without children it renders a LiveView link (href, navigate or patch) and, when active is set, adds data-active and aria-current="page". With a children slot it renders a native <details> disclosure whose <summary> opens and closes the nested links, so a group needs no JavaScript.

An item can have a leading icon slot and a trailing slot, such as a chevron. The text comes from label or from the default slot. The root takes class, and the parts take control_class, icon_class, label_class, trailing_class and children_class.

Base UI Nav Link example - sidebar with a collapsible group (Phoenix headless)

Home is the active leaf. Projects has a children slot, so it renders as a <details> group, and its trailing chevron turns a quarter turn while the group is open ([&[open]_[data-part=trailing]]:rotate-90). The same class list goes on every item, so the code assigns it once and passes it to each one.

heex

def sidebar(assigns) do
  assigns =
    assign(assigns, :nlc, [
      "block rounded-md text-sm",
      "[&[data-part=link]]:flex [&[data-part=link]]:items-center [&[data-part=link]]:gap-2 [&[data-part=link]]:px-3 [&[data-part=link]]:py-1.5 [&[data-part=link]:hover]:bg-neutral-100 dark:[&[data-part=link]:hover]:bg-neutral-800 [&[data-part=link][data-active]]:bg-neutral-900 [&[data-part=link][data-active]]:text-white dark:[&[data-part=link][data-active]]:bg-white dark:[&[data-part=link][data-active]]:text-neutral-900",
      "[&_[data-part=control]]:flex [&_[data-part=control]]:cursor-pointer [&_[data-part=control]]:list-none [&_[data-part=control]]:items-center [&_[data-part=control]]:gap-2 [&_[data-part=control]]:rounded-md [&_[data-part=control]]:px-3 [&_[data-part=control]]:py-1.5 [&_[data-part=control]:hover]:bg-neutral-100 dark:[&_[data-part=control]:hover]:bg-neutral-800",
      "[&_[data-part=label]]:flex-1 [&_[data-part=trailing]]:transition-transform [&[open]_[data-part=trailing]]:rotate-90",
      "[&_[data-part=children]]:mt-1 [&_[data-part=children]]:ml-4 [&_[data-part=children]]:space-y-1 [&_[data-part=children]]:border-l [&_[data-part=children]]:border-neutral-200 dark:[&_[data-part=children]]:border-neutral-700 [&_[data-part=children]]:pl-2"
    ])

  ~H"""
  <nav class="w-56 space-y-1 text-neutral-700 dark:text-neutral-300">
    <.nav_link label="Home" href="#" active class={@nlc} />
    <.nav_link label="Projects" class={@nlc}>
      <:trailing>
        <.icon name="hero-chevron-right" class="size-4" />
      </:trailing>
      <:children>
        <.nav_link label="Active" href="#" class={@nlc} />
        <.nav_link label="Archived" href="#" class={@nlc} />
      </:children>
    </.nav_link>
    <.nav_link label="Team" href="#" class={@nlc} />
  </nav>
  """
end

Leaf links

A leaf is a link with data-part="link". Pass the label as label or as the default slot, and set active on the one that matches the current page. On a group, active only sets data-active on the <details>.

heex

<.nav_link navigate={~p"/dashboard"} active={@active_tab == :dashboard}>
  <:icon><.icon name="hero-home" class="size-4" /></:icon>
  Dashboard
</.nav_link>

Keeping a group open in a LiveView

default_opened opens a group on first render, which is enough on a static page. Inside a LiveView, pass opened instead. It is the server's truth for the group and overrides default_opened. on_toggle is a phx-click on the control row, so use it to flip the value you pass as opened.

heex

<.nav_link label="Projects" opened={@projects_open} on_toggle="toggle_projects">
  <:children>
    <.nav_link label="Active" navigate={~p"/projects/active"} />
    <.nav_link label="Archived" navigate={~p"/projects/archived"} />
  </:children>
</.nav_link>

elixir

def handle_event("toggle_projects", _params, socket) do
  {:noreply, update(socket, :projects_open, &(!&1))}
end

Parts & data attributes

Each part carries a stable data-part and a structural chelekom-nav-link__* class you can target, plus the state attributes below. The root of a leaf has data-part="link" and the root of a group has data-part="root".

Part	data-part	State / ARIA	Purpose
Link (leaf root)	link	data-active, aria-current	The LiveView link of an item with no children.
Root (group)	root	data-active, open	The details element of an item with children.
Control	control	-	The summary that toggles the group. on_toggle is attached here.
Icon	icon	-	Wraps the icon slot. Rendered only when the slot is given.
Label	label	-	The text of the item.
Trailing	trailing	-	Wraps the trailing slot, for example a chevron.
Children	children	-	The container of the nested links.

Accessibility

There is no formal WAI-ARIA APG pattern for a navigation link. The active leaf carries aria-current="page". A group uses the native details and summary disclosure: the summary is focusable, Enter and Space toggle it, and browsers expose its open state to assistive technology. Put the links inside a <nav> with an aria-label of your own.

Attributes

Name	Type	Default	Values	Required	Description
`id`	`string`	—	—	No	Optional unique id
`label`	`string`	—	—	No	Label text (or use the default slot)
`href`	`string`	—	—	No	Leaf link href
`navigate`	`string`	—	—	No	LiveView navigate
`patch`	`string`	—	—	No	LiveView patch
`active`	`boolean`	`false`	—	No	Marks the item current (data-active + aria-current)
`default_opened`	`boolean`	`false`	—	No	Open nested children initially
`opened`	`boolean`	—	—	No	Server-controlled open state (overrides default_opened; survives LiveView patches)
`on_toggle`	`any`	—	—	No	phx-click for the control row — flip `opened` server-side when controlling the group
`class`	`any`	—	—	No	Extra classes for the root
`control_class`	`any`	—	—	No	—
`icon_class`	`any`	—	—	No	—
`label_class`	`any`	—	—	No	—
`trailing_class`	`any`	—	—	No	—
`children_class`	`any`	—	—	No	Extra classes for the nested container
`rest`	`global`	—	—	No	—

Slots

Name	Required	Description
`icon`	No	Leading icon
`trailing`	No	Trailing content (e.g. a chevron)
`inner_block`	No	Label content, used when the label attr is not set
`children`	No	Nested nav links — when present, the item becomes a disclosure

Options

Each option takes one or more of its values, separated by commas.

Option	Values
`--type`	`nav_link`
`--module`	A module name of your own

What it generates

Functions nav_link

Helpers None

Generated with it None

Command mix mishka.ui.gen.headless nav_link