Navigation

Top App Bar

MD3 top app bars are surface-colored: the bar sits on surface and turns surface-container once content scrolls under it (a CSS scroll-driven animation; scrolled forces it). small and center_aligned are 64dp; medium and large are the Expressive flexible layouts, with the title below the icons, and subtitle adds a second line. Icon buttons inside need no color.

variant

small

center_aligned

medium

With a subtitle

large

With a subtitle

Option	Type	Default	Description
`color`	`"surface" \| "transparent"`	`"surface"`
`paperize`	`boolean`	`true`
`position`	`"static" \| "relative" \| "sticky" \| "fixed" \| "absolute"`	`"static"`
`scrolled`	`boolean`	`false`	force the scrolled-under color
`subtitle`	`string`	`nil`	a second line under the title (Expressive)
`variant`	`"small" \| "center_aligned" \| "medium" \| "large"`	`"small"`

Slot	Attrs	Description
`:actions`		trailing icon buttons
`:inner_block` required		the title
`:leading`		the navigation icon (menu/back)

Show code

<.pp_top_app_bar position="sticky">
  <:leading><.pp_navigation_rail_toggle for="app-rail" modal_only /></:leading>
  Inbox
  <:actions>
    <.pp_icon_button icon="hero-magnifying-glass" label="Search" />
    <.pp_icon_button icon="hero-ellipsis-vertical" label="More" />
  </:actions>
</.pp_top_app_bar>

<.pp_top_app_bar variant="large" subtitle="12 unread">
  <:leading><.pp_icon_button icon="hero-arrow-left" label="Back" /></:leading>
  Inbox
</.pp_top_app_bar>

Navigation Rail

M3 Expressive's navigation rail, which replaces the navigation drawer: collapsed (96dp, icons over labels) or expanded (280dp, icons beside labels), animating on the Expressive spring. responsive (the default, used by this site's own sidebar) is a modal over a scrim below md and a collapsed rail that its menu button expands from md up. Pure CSS. The :fab slot morphs into an extended FAB when expanded.

collapsed and expanded (sized down for the demo with !static !h-80)

Option	Type	Default	Description
`pp_navigation_rail default_expanded`	`boolean`	`false`	responsive rails only: start expanded on md and up
`pp_navigation_rail default_open`	`boolean`	`false`	responsive rails only: start with the small-screen modal open
`pp_navigation_rail id`	`string (required)`
`pp_navigation_rail label`	`string`	`"Main navigation"`	the nav landmark's aria-label
`pp_navigation_rail menu_button`	`boolean`	`true`	render the menu (expand/collapse) button at the top of a responsive rail
`pp_navigation_rail paperize`	`boolean`	`true`
`pp_navigation_rail variant`	`"responsive" \| "collapsed" \| "expanded"`	`"responsive"`
`pp_navigation_rail_item active`	`boolean`	`false`	the current destination; sets aria-current
`pp_navigation_rail_item active_icon`	`string`	`nil`	icon shown while active (MD3's filled glyph)
`pp_navigation_rail_item badge`	`any`	`nil`	true for a dot, or a count
`pp_navigation_rail_item href`	`any`	`nil`
`pp_navigation_rail_item icon`	`string (required)`		a hero-* icon name
`pp_navigation_rail_item label`	`string (required)`
`pp_navigation_rail_item navigate`	`any`	`nil`
`pp_navigation_rail_item paperize`	`boolean`	`true`
`pp_navigation_rail_item patch`	`any`	`nil`
`pp_navigation_rail_item ripple`	`boolean`	`true`
`pp_navigation_rail_toggle for`	`string (required)`		the pp_navigation_rail/1's id
`pp_navigation_rail_toggle label`	`string`	`"Toggle navigation"`
`pp_navigation_rail_toggle modal_only`	`boolean`	`false`	hide from md up — for a second toggle in the top app bar
`pp_navigation_rail_toggle paperize`	`boolean`	`true`

Slot	Attrs	Description
`pp_navigation_rail :fab`	`icon, label, href, navigate, patch, on_click`	the rail's FAB, extended when the rail is
`pp_navigation_rail :footer`		content pinned to the bottom (settings, account)
`pp_navigation_rail :header`		extra content at the top (a logo), under the menu button
`pp_navigation_rail :inner_block` required		the pp_navigation_rail_item/1 destinations

Show code

<%!-- responsive (default): modal below md, collapsible rail from md --%>
<.pp_navigation_rail id="app-rail">
  <:fab icon="hero-pencil" label="Compose" navigate={~p"/compose"} />
  <.pp_navigation_rail_item
    icon="hero-inbox"
    active_icon="hero-inbox-solid"
    label="Inbox"
    navigate={~p"/"}
    active
    badge={4}
  />
  <.pp_navigation_rail_item icon="hero-paper-airplane" label="Sent" navigate={~p"/sent"} />
</.pp_navigation_rail>

<%!-- In the top app bar, so small screens can open the modal rail --%>
<.pp_navigation_rail_toggle for="app-rail" modal_only />

Navigation Bar

The Expressive flexible bottom bar for 3–5 top-level destinations on small screens: 64dp on surface-container, each item an icon in a secondary-container indicator with its label under it (vertical) or beside it (horizontal); responsive switches at sm. position="fixed" pins it to the viewport bottom. Pair it with a navigation rail on larger screens.

item_layout

Option	Type	Default	Description
`pp_navigation_bar item_layout`	`"responsive" \| "vertical" \| "horizontal"`	`"responsive"`
`pp_navigation_bar label`	`string`	`"Main navigation"`	the nav landmark's aria-label
`pp_navigation_bar paperize`	`boolean`	`true`
`pp_navigation_bar position`	`"static" \| "fixed" \| "sticky"`	`"static"`
`pp_navigation_bar_item active`	`boolean`	`false`
`pp_navigation_bar_item active_icon`	`string`	`nil`
`pp_navigation_bar_item badge`	`any`	`nil`	true for a dot, or a count
`pp_navigation_bar_item href`	`any`	`nil`
`pp_navigation_bar_item icon`	`string (required)`
`pp_navigation_bar_item label`	`string (required)`
`pp_navigation_bar_item navigate`	`any`	`nil`
`pp_navigation_bar_item paperize`	`boolean`	`true`
`pp_navigation_bar_item patch`	`any`	`nil`
`pp_navigation_bar_item ripple`	`boolean`	`true`

Slot	Attrs	Description
`pp_navigation_bar :inner_block` required		the pp_navigation_bar_item/1 destinations

Show code

<.pp_navigation_bar position="fixed" class="md:hidden">
  <.pp_navigation_bar_item icon="hero-home" active_icon="hero-home-solid" label="Home" navigate={~p"/"} active />
  <.pp_navigation_bar_item icon="hero-magnifying-glass" label="Search" navigate={~p"/search"} />
  <.pp_navigation_bar_item icon="hero-bell" label="Alerts" navigate={~p"/alerts"} badge={3} />
</.pp_navigation_bar>

Toolbar

An M3 Expressive toolbar, MD3's replacement for the bottom app bar: a row (or column) of actions for the current page. docked is a full-width 64dp bar; floating is a rounded pill sized to its items, optionally paired with a FAB. vibrant puts it on primary-container; give icon buttons color="inherit" there.

docked, and floating vibrant with a FAB

Option	Type	Default	Description
`color`	`"standard" \| "vibrant"`	`"standard"`
`label`	`string`	`nil`	aria-label of the toolbar
`orientation`	`"horizontal" \| "vertical"`	`"horizontal"`
`paperize`	`boolean`	`true`
`position`	`"static" \| "relative" \| "fixed" \| "absolute" \| "sticky"`	`"static"`
`variant`	`"docked" \| "floating"`	`"docked"`

Slot	Attrs	Description
`:fab`		a FAB paired with a floating toolbar
`:inner_block` required

Show code

<.pp_toolbar position="fixed">
  <.pp_icon_button icon="hero-archive-box" label="Archive" />
  <.pp_icon_button icon="hero-trash" label="Delete" />
</.pp_toolbar>

<.pp_toolbar variant="floating" color="vibrant" position="fixed" class="bottom-4 inset-x-0 mx-auto">
  <.pp_icon_button icon="hero-bold" label="Bold" color="inherit" />
  <.pp_icon_button icon="hero-italic" label="Italic" color="inherit" />
  <:fab><.pp_fab icon="hero-check" label="Done" color="secondary-container" /></:fab>
</.pp_toolbar>

Tabs

Tabs, Tab and TabPanel switch client-side via Phoenix.LiveView.JS commands, no round trip. primary tabs have an indicator under the label and content; secondary tabs a thinner full-width one. layout="scrollable" scrolls a long row. They follow the ARIA keyboard model: only the selected tab is a Tab stop, and Left/Right (mirrored in RTL), Home and End move between tabs, skipping disabled ones. With the JS hook (Getting Started, step 4) the indicator slides between tabs.

primary, with icons and a badge

Upcoming flights.

secondary

Overview content.

Option	Type	Default	Description
`pp_tabs id`	`string (required)`		shared with every Tab/TabPanel in the group
`pp_tabs layout`	`"fixed" \| "scrollable"`	`"fixed"`
`pp_tabs paperize`	`boolean`	`true`
`pp_tabs variant`	`"primary" \| "secondary"`	`"primary"`
`pp_tab badge`	`any`	`nil`	true for a dot, or a count
`pp_tab default_selected`	`boolean`	`false`
`pp_tab disabled`	`boolean`	`false`
`pp_tab id`	`string (required)`		shared with the parent Tabs and matching TabPanel
`pp_tab paperize`	`boolean`	`true`
`pp_tab ripple`	`boolean`	`true`
`pp_tab value`	`string (required)`		unique within the group; matches a TabPanel
`pp_tab_panel default_selected`	`boolean`	`false`
`pp_tab_panel id`	`string (required)`		the same id passed to the parent pp_tabs/1
`pp_tab_panel paperize`	`boolean`	`true`
`pp_tab_panel value`	`string (required)`		matches the corresponding pp_tab/1's value

Slot	Attrs	Description
`pp_tabs :inner_block` required
`pp_tab :icon`		an optional icon — stacked above the label on primary tabs
`pp_tab :inner_block` required
`pp_tab_panel :inner_block` required

Show code

<.pp_tabs id="trip-tabs">
  <.pp_tab id="trip-tabs" value="flights" default_selected>
    <:icon><.pp_icon name="hero-paper-airplane" /></:icon>
    Flights
  </.pp_tab>
  <.pp_tab id="trip-tabs" value="trips" badge={2}>Trips</.pp_tab>
</.pp_tabs>
<.pp_tab_panel id="trip-tabs" value="flights" default_selected>Upcoming flights.</.pp_tab_panel>
<.pp_tab_panel id="trip-tabs" value="trips">Your trips.</.pp_tab_panel>

<.pp_tabs id="spec-tabs" variant="secondary" layout="scrollable">...</.pp_tabs>

Breadcrumbs

New

A trail of :items built from MD3 parts: each linked item is a compact text button in primary, the current page (the item left without a link) is plain on-surface text with aria-current, and chevrons separate them. Long trails wrap instead of collapsing.

Links and the current page

Option	Type	Default	Description
`paperize`	`boolean`	`true`

Slot	Attrs	Description
`:item` required	`href, navigate, patch`

Show code

<.pp_breadcrumbs>
  <:item navigate={~p"/"}>Home</:item>
  <:item navigate={~p"/catalog"}>Catalog</:item>
  <:item>Current product</:item>
</.pp_breadcrumbs>

Pagination

New

Page navigation from MD3 standard icon buttons: previous and next around the first and last page, the current page and one on each side, the rest collapsed into an ellipsis (so the control keeps its width as you page). The current page takes secondary-container and aria-current. Pages are 1-based; give path a function for links (patch by default), or on_change an event name.

Events (on_change): page 5 of 12

disabled

Option	Type	Default	Description
`count`	`integer (required)`		the number of pages
`disabled`	`boolean`	`false`
`link`	`"patch" \| "navigate" \| "href"`	`"patch"`	the kind of link path produces
`on_change`	`any`	`nil`	an event name (or JS) for phx-click; the page is sent as phx-value-page
`page`	`integer (required)`		the current page, 1-based
`paperize`	`boolean`	`true`
`path`	`any`	`nil`	a function from a page number to a URL; makes every page a link
`target`	`any`	`nil`	phx-target for on_change

Show code

<%!-- Links: the page lives in the URL and handle_params/3 loads it --%>
<.pp_pagination page={@page} count={@total_pages} path={&~p"/users?page=#{&1}"} />

<%!-- Events: each button sends phx-value-page --%>
<.pp_pagination page={@page} count={@total_pages} on_change="paginate" />

# In the LiveView
def handle_event("paginate", %{"page" => page}, socket),
  do: {:noreply, assign(socket, :page, String.to_integer(page))}

A trigger that opens an anchored list of actions; closes on selecting an item, clicking outside, or Escape (JS commands and phx-click-away, no hook). The trigger is an icon button (trigger_icon + trigger_label) or your own :trigger content with trigger_variant. Items are pp_menu_item/1: a leading icon, supporting and trailing text, selected. color="vibrant" is the tertiary-container Expressive menu. pp_submenu/1 cascades a submenu beside an item (hover, focus or tap). With the JS hook and an id, menus and submenus flip to the other side when they'd overflow the viewport.

Try it

Option	Type	Default	Description
`pp_menu anchor`	`"bottom-start" \| "bottom-end" \| "top-start" \| "top-end"`	`"bottom-start"`
`pp_menu color`	`"standard" \| "vibrant"`	`"standard"`
`pp_menu id`	`string (required)`
`pp_menu paperize`	`boolean`	`true`
`pp_menu trigger_class`	`any`	`nil`
`pp_menu trigger_color`	`string`	`nil`	color of the trigger button
`pp_menu trigger_icon`	`string`	`nil`	renders an icon-button trigger
`pp_menu trigger_label`	`string`	`nil`	the icon trigger's accessible name
`pp_menu trigger_variant`	`"standard" \| "filled" \| "tonal" \| "elevated" \| "outlined" \| "text" \| "none"`	`nil`	variant of the trigger button; none = bare button
`pp_menu_item disabled`	`boolean`	`false`
`pp_menu_item href`	`any`	`nil`
`pp_menu_item icon`	`string`	`nil`	a leading hero-* icon
`pp_menu_item navigate`	`any`	`nil`
`pp_menu_item paperize`	`boolean`	`true`
`pp_menu_item patch`	`any`	`nil`
`pp_menu_item selected`	`boolean`	`false`
`pp_menu_item supporting_text`	`string`	`nil`
`pp_menu_item trailing_text`	`string`	`nil`	e.g. a keyboard shortcut
`pp_submenu disabled`	`boolean`	`false`
`pp_submenu icon`	`string`	`nil`	a leading hero-* icon
`pp_submenu id`	`string (required)`
`pp_submenu label`	`string (required)`		the submenu trigger's text
`pp_submenu paperize`	`boolean`	`true`
`pp_submenu side`	`"end" \| "start"`	`"end"`	which side it opens on

Slot	Attrs	Description
`pp_menu :inner_block` required		pp_menu_item/1s, dividers, ...
`pp_menu :trigger`		the trigger button's label (button and bare triggers)
`pp_menu_item :inner_block` required		the item label
`pp_menu_item :trailing`		custom trailing content, instead of trailing_text
`pp_submenu :inner_block` required		the submenu's pp_menu_item/1s

Show code

<%!-- Your own trigger content, styled with trigger_variant --%>
<.pp_menu id="actions-menu" trigger_variant="outlined">
  <:trigger>Actions <.pp_icon name="hero-chevron-down" size="sm" /></:trigger>
  <.pp_menu_item icon="hero-pencil-square" trailing_text="⌘E" phx-click="edit">Edit</.pp_menu_item>
  <.pp_divider />
  <.pp_menu_item icon="hero-trash" phx-click="delete">Delete</.pp_menu_item>
</.pp_menu>

<%!-- An icon-button trigger: trigger_icon + trigger_label --%>
<.pp_menu id="profile-menu" anchor="bottom-end" trigger_icon="hero-ellipsis-vertical" trigger_label="More">
  <.pp_menu_item navigate={~p"/users/settings"}>Settings</.pp_menu_item>
  <%!-- A cascading submenu --%>
  <.pp_submenu id="profile-menu-share" label="Share" icon="hero-share">
    <.pp_menu_item phx-click="share_email">Email</.pp_menu_item>
    <.pp_menu_item phx-click="share_link">Copy link</.pp_menu_item>
  </.pp_submenu>
  <.pp_menu_item href={~p"/users/log-out"} method="delete">Log out</.pp_menu_item>
</.pp_menu>

Search Bar

A 56dp rounded surface-container-high bar with a leading search icon (or your :leading), the input and a :trailing slot. Given :results, it opens into MD3's search view while it has focus: docked under the bar (view="docked", default), full screen ("fullscreen", with a back button), or full screen only below sm ("responsive"). Pure CSS (:focus-within), so render the results from your LiveView as the query changes. Type below.

Try it (docked search view)

view="responsive": full screen below sm (narrow the window and focus it)

Inbox Drafts Archive

Option	Type	Default	Description
`back_label`	`string`	`"Back"`	full-screen view's back button label
`full_width`	`boolean`	`false`
`id`	`string`	`nil`
`label`	`string`	`nil`	aria-label; defaults to the placeholder
`name`	`string`	`"q"`
`paperize`	`boolean`	`true`
`placeholder`	`string`	`"Search"`
`results_open`	`boolean`	`false`	keep the search view open
`value`	`string`	`nil`
`view`	`"docked" \| "fullscreen" \| "responsive"`	`"docked"`	the search view while focused: docked under the bar, full screen, or full screen below sm

Slot	Attrs	Description
`:leading`		replaces the search icon (a menu or back icon button)
`:results`		the docked search view's content, shown while focused
`:trailing`		trailing icon buttons or an avatar

Show code

<form phx-change="search" phx-submit="search">
  <.pp_search_bar name="q" value={@query} placeholder="Search folders" phx-debounce="150">
    <:trailing><.pp_avatar>AL</.pp_avatar></:trailing>
    <:results>
      <.pp_list>
        <.pp_list_item :for={hit <- @hits} navigate={hit.path}>{hit.title}</.pp_list_item>
      </.pp_list>
    </:results>
  </.pp_search_bar>
</form>

# In the LiveView:
def handle_event("search", %{"q" => q}, socket),
  do: {:noreply, assign(socket, query: q, hits: MyApp.Search.run(q))}

List

MD3 list rows: one line (56dp), or two with :secondary (72dp), in body-large. Items render as links, buttons or plain rows depending on their attrs; the active item is secondary-container. :leading holds an icon or a pp_avatar, :trailing a count, icon or action. For a heading over a group, use a title-small pp_typography; to show and hide a group, render its items conditionally.

Icons with a heading, and avatars with two lines

Main

Home Overview Inbox 3

Billing Coming soon

AL Ada Lovelace ada@example.com GH Grace Hopper grace@example.com AT Alan Turing alan@example.com

Option	Type	Default	Description
`pp_list paperize`	`boolean`	`true`
`pp_list_item active`	`boolean`	`false`
`pp_list_item disabled`	`boolean`	`false`
`pp_list_item href`	`any`	`nil`
`pp_list_item navigate`	`any`	`nil`
`pp_list_item paperize`	`boolean`	`true`
`pp_list_item patch`	`any`	`nil`
`pp_list_item ripple`	`boolean`	`true`	the Material ripple effect on click/tap — off whenever paperize is false, see PhoenixPaper.Ripple

Slot	Attrs	Description
`pp_list :inner_block` required
`pp_list_item :inner_block` required		the primary line of text
`pp_list_item :leading`		an icon or avatar
`pp_list_item :secondary`		a secondary line of text below the primary one
`pp_list_item :trailing`		a trailing icon, badge, or action

Show code

<.pp_list>
  <.pp_typography variant="title-small" color="on-surface-variant" class="px-4 pt-2 pb-1">
    Main
  </.pp_typography>
  <.pp_list_item navigate={~p"/"} active>
    <:leading><.pp_icon name="hero-home" /></:leading>
    Home
    <:secondary>Overview</:secondary>
  </.pp_list_item>
  <.pp_list_item navigate={~p"/inbox"}>
    <:leading><.pp_icon name="hero-inbox" /></:leading>
    Inbox
    <:trailing><.pp_typography variant="label-medium">3</.pp_typography></:trailing>
  </.pp_list_item>
</.pp_list>

<%!-- pp_avatar in :leading: an image, falling back to initials --%>
<.pp_list>
  <.pp_list_item :for={user <- @users} navigate={~p"/users/#{user.id}"}>
    <:leading><.pp_avatar src={user.avatar_url}>{user.initials}</.pp_avatar></:leading>
    {user.name}
    <:secondary>{user.email}</:secondary>
  </.pp_list_item>
</.pp_list>

Theme

Top App Bar

variant

Navigation Rail

collapsed and expanded (sized down for the demo with !static !h-80)

Navigation Bar

item_layout

Tabs

primary, with icons and a badge

secondary

Menu

Try it

Search Bar

Try it (docked search view)

view="responsive": full screen below sm (narrow the window and focus it)

List

Icons with a heading, and avatars with two lines

Main