PUI.Layout (pui v1.0.0-beta.10)

Reusable application shell primitives for documentation sites, dashboards, and other two-pane LiveView layouts.

The layout API is split into small components so applications can compose their own shell without inheriting opinionated navigation data structures.

Basic Usage

<.app_layout id="docs-shell">
  <:sidebar>
    <.sidebar>
      <:header>
        <div class="px-4 py-3 font-semibold">PUI</div>
      </:header>

      <nav class="p-3">
        <.sidebar_menu_item title="Getting Started" icon="hero-rocket-launch" href="/docs" />
      </nav>
    </.sidebar>
  </:sidebar>

  <:header>
    <.content_header shell_id="docs-shell" breadcrumb_current="Getting Started" />
  </:header>

  Content goes here.
</.app_layout>

Collapsible Navigation

Use collapsible={true} on sidebar_menu_item/1 when an item owns nested links. The submenu state is handled by the bundled PUI.Sidebar hook.

<.sidebar_menu_item
  title="Components"
  icon="hero-squares-2x2"
  collapsible
  expanded
>
  <:subitem>
    <.link href="/docs/button" class="block rounded-md px-2 py-1.5 text-sm">Button</.link>
  </:subitem>
</.sidebar_menu_item>

Components

Component	Description
`app_layout/1`	Root shell with collapsible sidebar state
`sidebar/1`	Sidebar surface with header and footer slots
`sidebar_menu_item/1`	Sidebar link row with optional collapsible submenu
`content_header/1`	Sticky content header with sidebar toggle and breadcrumbs

Summary

Functions

app_layout(assigns)

Renders a two-pane application shell.

content_header(assigns)

Renders a sticky shell header with a sidebar toggle and breadcrumb.

sidebar(assigns)

Renders a collapsible sidebar surface.

sidebar_menu_item(assigns)

Renders a sidebar item as a link or as a collapsible submenu trigger.

Functions

app_layout(assigns)

Renders a two-pane application shell.

Attributes

Name	Type	Default	Description
`id`	`string`	`"app-layout"`	Shell DOM id, used by `content_header/1` toggle
`class`	`string`	`""`	Additional classes for the root shell
`content_class`	`string`	`"w-full px-4 py-4"`	Classes for the scrollable main content element
`collapsed`	`boolean`	`false`	Initial sidebar collapsed state rendered by the server

Slots

Name	Required	Description
`sidebar`	Yes	Sidebar content, usually `sidebar/1`
`header`	No	Sticky header content, usually `content_header/1`
`inner_block`	Yes	Main page content

Attributes

id (:string) - Defaults to "app-layout".
class (:string) - Defaults to "".
content_class (:string) - Defaults to "w-full px-4 py-4".
collapsed (:boolean) - Defaults to false.

Slots

sidebar (required)
header
inner_block (required)

content_header(assigns)

Renders a sticky shell header with a sidebar toggle and breadcrumb.

Attributes

Name	Type	Default	Description
`shell_id`	`string`	`"app-layout"`	Target shell id for collapse toggling
`class`	`string`	`""`	Additional classes for the header
`toggle_class`	`string`	`""`	Additional classes for the toggle button
`title`	`string`	`nil`	Small eyebrow text above the breadcrumb
`breadcrumb_parent`	`string`	`nil`	Optional parent breadcrumb
`breadcrumb_current`	`string`	required	Current page breadcrumb

Slots

Name	Required	Description
`right_actions`	No	Right-aligned buttons, menus, or theme controls

Attributes

shell_id (:string) - Defaults to "app-layout".
class (:string) - Defaults to "".
toggle_class (:string) - Defaults to "".
title (:string) - Defaults to nil.
breadcrumb_parent (:string) - Defaults to nil.
breadcrumb_current (:string) (required)

Slots

right_actions

sidebar(assigns)

Renders a collapsible sidebar surface.

Attributes

Name	Type	Default	Description
`id`	`string`	`"app-sidebar"`	Sidebar DOM id
`class`	`string`	`""`	Additional classes for the sidebar
`expanded_width_class`	`string`	`"w-72"`	Width class when the shell is expanded
`collapsed_width_class`	`string`	`"group-data-[collapsed=true]/pui-layout:w-12"`	Width class when collapsed

Slots

Name	Required	Description
`header`	No	Logo, workspace switcher, or sidebar title
`inner_block`	Yes	Sidebar navigation/content
`footer`	No	Account controls or secondary actions

Attributes

id (:string) - Defaults to "app-sidebar".
class (:string) - Defaults to "".
expanded_width_class (:string) - Defaults to "w-72".
collapsed_width_class (:string) - Defaults to "group-data-[collapsed=true]/pui-layout:w-12".

Slots

header
inner_block (required)
footer

sidebar_menu_item(assigns)

Renders a sidebar item as a link or as a collapsible submenu trigger.

Attributes

Name	Type	Default	Description
`id`	`string`	derived from `title`	Stable DOM id
`title`	`string`	required	Visible item label and link title
`icon`	`string`	required	Heroicon class, such as `"hero-home"`
`navigate`	`string`	`nil`	LiveView navigation target
`href`	`string`	`nil`	Link href
`patch`	`string`	`nil`	LiveView patch target
`collapsible`	`boolean`	`false`	Render a submenu trigger instead of a link
`expanded`	`boolean`	`false`	Initial submenu state
`current`	`boolean`	`false`	Applies active item styling
`class`	`string`	`""`	Additional classes for the row

Slots

Name	Required	Description
`trailing`	No	Badge, count, or secondary row content
`subitem`	No	Repeated submenu rows for collapsible items

Attributes

id (:string) - Defaults to nil.
title (:string) (required)
icon (:string) (required)
navigate (:string) - Defaults to nil.
href (:string) - Defaults to nil.
patch (:string) - Defaults to nil.
collapsible (:boolean) - Defaults to false.
expanded (:boolean) - Defaults to false.
class (:string) - Defaults to "".
current (:boolean) - Defaults to false.

Slots

trailing
subitem