LanternUI.Components.Layout (LanternUI v0.8.2)

App shell — a full-width top bar (brand + inline context + actions) over a fixed, collapsible left sidebar and a main content column. Breadcrumb chrome is a first-class layout region (goprint-style sticky trail under the appbar), not a per-app one-off.

<.app_shell id="app">
  <:brand><.icon name="bolt" /> <span class="lui-brand-name">Acme</span></:brand>
  <:header>…switchers…</:header>
  <:actions>…user menu…</:actions>
  <:breadcrumb>
    <.breadcrumb items={@breadcrumbs} />
  </:breadcrumb>
  <:sidebar>
    <.nav_group label="Workspace">
      <.nav_item label="Dashboard" icon="chart-bar" navigate="/" active />
      <.nav_item label="Buckets" icon="cloud" navigate="/buckets" />
    </.nav_group>
  </:sidebar>
  <:sidebar_footer>
    <.nav_link label="Documentation" icon="book-open" href="/docs" />
    <.nav_link label="Terms" href="/terms" />
  </:sidebar_footer>

  <.page_header title="Buckets" description="Object storage.">
    <:actions><.button>New</.button></:actions>
  </.page_header>
  main content…
</.app_shell>

page_header/1 can also be used on its own. breadcrumb_bar/1 is the standalone breadcrumb region used by app_shell/1 and can wrap a breadcrumb/1 plus an optional actions slot.

The brand sits top-left; :header is inline context in the appbar (switchers); :breadcrumb is the compact sticky trail under the appbar; optional :breadcrumb_actions are right-aligned on that same bar (Linear pattern); :actions is top-right of the appbar. A collapse control at the sidebar's foot toggles the icon rail; the state persists per id in localStorage via the LanternSidebar hook.

On narrow viewports the sidebar becomes an off-canvas drawer opened by the hamburger in the bar, over a scrim. It closes on scrim click, Escape, and on tapping a nav item — so a navigate link doesn't leave the drawer covering the page it just went to.

Summary

Functions

app_shell(assigns)

breadcrumb_bar(assigns)

Compact sticky breadcrumb region for use outside app_shell (or when the host app still owns the outer shell). Same chrome app_shell's :breadcrumb slot renders.

nav_group(assigns)

A labelled group of nav items. The label hides when the rail is collapsed.

nav_item(assigns)

A sidebar nav item. Renders a link when given navigate/patch/href, or a button when given phx-click. Collapses to an icon-only rail item (with a tooltip) when the sidebar is collapsed.

nav_link(assigns)

A quiet link for the shell's :sidebar_footer — support, docs, legal.

page_header(assigns)

Page title row — compact, goprint-density. Renders under the breadcrumb bar inside main content. Title + optional description + right-side actions.

Functions

app_shell(assigns)

Attributes

id (:string) (required) - stable id — the collapse state is persisted per id.
collapsed (:boolean) - Initial sidebar collapsed (icon-rail) state. Defaults to false.
class (:any) - Extra classes merged onto the root element. Defaults to nil.
Global attributes are accepted. Arbitrary HTML/phx-* attributes passed through.

Slots

brand (required) - logo/name, top-left corner.
header - inline context after the brand (switchers, etc.).
actions - top-right of the bar (user menu, etc.).
breadcrumb - compact sticky trail under the appbar (pass <.breadcrumb>).
breadcrumb_actions - Right-side actions on the breadcrumb bar (same region as breadcrumb_bar/1 :actions). Omitted when empty so existing call sites stay unchanged. Accepts attributes:
- label (:string) - Label used when this entry collapses into the breadcrumb overflow menu.
- phx-click (:string) - LiveView click event on the overflow menu item.
- phx-value-id (:string) - Optional phx-value-id for the overflow menu item.
- phx-target (:any) - LiveView target for the overflow menu item.
- disabled (:boolean) - Disable the overflow menu item.
- navigate (:string) - Destination for a NAVIGATING entry. REQUIRED on any entry whose inline button navigates: a folded item renders from these attrs, not from the slot body, so an entry carrying a path only on its inner button becomes a menu item with no click target and silently does nothing.
- patch (:string) - Live-patch destination for a folded navigating entry.
- href (:any) - Plain href for a folded navigating entry.
- data-confirm (:string) - Confirmation prompt for the folded menu item. REQUIRED on destructive entries: a folded item renders from these attrs, not from the slot body, so a confirm set only on an inner button is lost once the entry passes :max_inline.
sidebar (required) - nav_group / nav_item.
sidebar_footer - Persistent links pinned below the nav and above the collapse control (support, docs, legal). Pass nav_link/1s. Hidden on the icon rail, where there is no room for text-only links.
inner_block (required) - Main content column.

breadcrumb_bar(assigns)

Compact sticky breadcrumb region for use outside app_shell (or when the host app still owns the outer shell). Same chrome app_shell's :breadcrumb slot renders.

With an :actions slot, the bar is the Linear-style action row: trail on the left, actions right-aligned. At most :max_inline entries (default 2) render as quick buttons; everything after that folds into a More menu (the APG menu/1 — no extra JS).

The cap is fixed, not width-based. A responsive cap would have to hide an inline button that is not in the menu, which makes that action unreachable at narrow widths; a fixed split keeps every action reachable at every size.

<.breadcrumb_bar>
  <.breadcrumb home="/" items={@crumbs} />
  <:actions>
    <.button size="sm">New project</.button>
  </:actions>
</.breadcrumb_bar>

<.breadcrumb_bar>
  <.breadcrumb home="/" items={@crumbs} />
  <:actions><.button size="sm">New</.button></:actions>
  <:actions label="Import" phx-click="import">
    <.button size="sm" phx-click="import">Import</.button>
  </:actions>
  <:actions label="Export" phx-click="export">
    <.button size="sm" phx-click="export">Export</.button>
  </:actions>
</.breadcrumb_bar>

Without :actions, markup is unchanged from the trail-only chrome.

Attributes

class (:any) - Extra classes merged onto the root element. Defaults to nil.
id (:string) - Stable id for the overflow menu when multi-entry actions collapse; auto-generated when omitted. Defaults to nil.
max_inline (:integer) - How many entries render as quick buttons before the rest fold into the More menu. Defaults to 2.
Global attributes are accepted. Arbitrary HTML/phx-* attributes passed through.

Slots

inner_block (required) - Usually a single <.breadcrumb>.
actions - Right-side actions. The first :max_inline entries render as quick buttons; the rest fold into a More menu. Accepts attributes:
- label (:string) - Label used for this entry when it is collapsed into the overflow menu.
- phx-click (:string) - LiveView click event on the overflow menu item.
- phx-value-id (:string) - Optional phx-value-id for the overflow menu item.
- phx-target (:any) - LiveView target for the overflow menu item.
- disabled (:boolean) - Disable the overflow menu item.
- navigate (:string) - Destination for a NAVIGATING entry. REQUIRED on any entry whose inline button navigates: a folded item renders from these attrs, not from the slot body, so an entry carrying a path only on its inner button becomes a menu item with no click target and silently does nothing.
- patch (:string) - Live-patch destination for a folded navigating entry.
- href (:any) - Plain href for a folded navigating entry.
- data-confirm (:string) - Confirmation prompt for the folded menu item. REQUIRED on destructive entries: a folded item renders from these attrs, not from the slot body, so a confirm set only on an inner button is lost once the entry passes :max_inline.

nav_group(assigns)

A labelled group of nav items. The label hides when the rail is collapsed.

Attributes

label (:string) - Group heading; hides when the rail is collapsed. Defaults to nil.
class (:any) - Extra classes merged onto the root element. Defaults to nil.

Slots

inner_block (required) - nav_item children in this group.

nav_item(assigns)

A sidebar nav item. Renders a link when given navigate/patch/href, or a button when given phx-click. Collapses to an icon-only rail item (with a tooltip) when the sidebar is collapsed.

Pass badge to hang a count off the item — how many things are waiting behind the link. It sits at the end of the row and becomes a dot on the collapsed rail, where there is no room for a number and none is needed: the point of a count on a rail is that there is something.

Pass a :subnav slot of nested nav_items to make it an expandable section (Fluxon parity): the item becomes a toggle with a chevron, and the subnav slides open/closed client-side. Use expanded for the initial open state (e.g. expanded={@in_this_section?}). The subnav is hidden on the icon rail.

Attributes

label (:string) (required) - Nav label; becomes the collapsed-rail tooltip.
expanded (:boolean) - Initial open state when a :subnav is present. Defaults to false.
icon (:string) - Leading icon. A lantern icon-set name (e.g. chart-bar), or a host heroicon name (hero-*) rendered as a CSS-mask span so an app can keep its own icons. Defaults to nil.
badge (:any) - A count or short marker for what is waiting behind this link. Sits at the end of the row, and shrinks to a dot on the collapsed rail. Pass nil for none — a badge reading 0 is a badge saying there is nothing to see. Defaults to nil.
active (:boolean) - Highlight as the current page. Defaults to false.
navigate (:string) - LiveView navigate target; renders as a link. Defaults to nil.
patch (:string) - LiveView patch target; renders as a link. Defaults to nil.
href (:string) - External or full-page href; renders as a link. Defaults to nil.
class (:any) - Extra classes merged onto the root element. Defaults to nil.
Global attributes are accepted. Arbitrary HTML/phx-* attributes passed through. Supports all globals plus: ["phx-click", "phx-value-id", "phx-target"].

Slots

subnav - Nested nav_items. When present the item becomes an expandable section.

nav_link(assigns)

A quiet link for the shell's :sidebar_footer — support, docs, legal.

Deliberately not a nav_item: these are standing links that never represent the current page, so they carry no active state and sit at a smaller, lower-contrast weight than the nav above them.

<.nav_link label="Contact us" icon="hero-lifebuoy" navigate="/help" />
<.nav_link label="Terms" href="/terms" external />

Attributes

label (:string) (required) - Link text.
icon (:string) - Optional leading icon — a lantern icon-set name or a host hero-* name. Defaults to nil.
navigate (:string) - LiveView navigate target. Defaults to nil.
patch (:string) - LiveView patch target. Defaults to nil.
href (:string) - Plain href. Defaults to nil.
external (:boolean) - Marks the link as leaving the app: opens in a new tab and shows an outbound glyph. Defaults to false.
class (:any) - Extra classes merged onto the root element. Defaults to nil.
Global attributes are accepted. Arbitrary HTML/phx-* attributes passed through.

page_header(assigns)

Page title row — compact, goprint-density. Renders under the breadcrumb bar inside main content. Title + optional description + right-side actions.

Attributes

title (:string) - Page heading. Defaults to nil.
description (:string) - Optional supporting line under the title. Defaults to nil.
class (:any) - Extra classes merged onto the root element. Defaults to nil.
Global attributes are accepted. Arbitrary HTML/phx-* attributes passed through.

Slots

actions - Right-side actions (buttons, menus).
inner_block - Optional body under the title row (rarely needed).