The sidebar layout puts all navigation in a left-hand panel — no desktop header bar. This is the default layout in Petal Pro.

• Desktop: sidebar always visible, collapses to icon-only rail if collapsible is set
• Mobile: sticky top bar with a hamburger button slides the sidebar in as an overlay
• Structure: logo at the top, scrollable menu in the middle, optional bottom_section_content at the bottom (for user profile, settings, etc.)

Quick example

Collapsible sidebar

Add the collapsible attr to let users collapse the sidebar to a narrow icon-only rail. Collapse state persists across page loads via Alpine.js $persist() in localStorage.

<.sidebar_layout collapsible current_page={@current_page} main_menu_items={@menu_items}>
  ...
</.sidebar_layout>

Also available:

• collapsed_only — sidebar is always collapsed, no toggle button shown
• default_collapsed — sidebar starts collapsed on first visit (before localStorage is set)

Collapsible requires the Alpine Persist plugin. Petal Pro includes it by default.

Bottom section

Use the :bottom_section_content slot for anything that should anchor to the bottom of the sidebar — user profile, settings link, auth buttons. It renders above a border separator.

<.sidebar_layout ...>
  <:bottom_section_content>
    <.user_dropdown_menu
      user_menu_items={@user_menu_items}
      avatar_src={@avatar_src}
      current_user_name={@current_user.name}
    />
  </:bottom_section_content>
  ...
</.sidebar_layout>

Sidebar layout properties

The stacked layout has a top navbar with the menu across the header. Good for apps with fewer nav items or a more traditional web app feel.

Get up and running

The same menu item data structure works for both layouts, making it easy to switch.

• Stacked layout properties
• Installing a layout
• Menu item structure
• Handling signed in users
• Custom menu items

Installation

Define your layout in app.html.heex (or a new file like sidebar.html.heex). Since you’ll want access to @socket, put your layout in the app layout rather than the root layout.

If you create a new layout file, wire it up as a live layout.

Here is an example:

Set current_page in every live view:

def mount(_params, _session, socket) do
  socket = assign(socket,
    current_page: :dashboard,
    page_title: "Dashboard"
  )
  {:ok, socket}
end

For controllers:

def index(conn, _params) do
  conn
  |> assign(:current_page, :dashboard)
  |> assign(:page_title, "Dashboard")
  |> render("index.html")
end

Menu item structure

main_menu_items is a list of maps. For the sidebar layout the items appear in the sidebar panel; for stacked they appear in the header.

Each item has:

• name — atom, used to highlight the current page
• label — display text
• icon — a Heroicon name string, raw HTML string, or function component (&my_icon/1)
• path — navigation target
• patch_group — optional module atom; items sharing the same value use patch navigation between them

[
  %{name: :dashboard, label: "Dashboard", icon: "hero-home", path: ~p"/"},
  %{name: :settings, label: "Settings", icon: "hero-cog-6-tooth", path: ~p"/settings"}
]

Nested menu items

Provide a menu_items key to create a collapsible dropdown group (Alpine JS required):

[
  %{
    name: :company,
    label: "Company",
    icon: "hero-building-office",
    menu_items: [
      %{name: :reports, label: "Reports", icon: "hero-chart-pie", path: ~p"/reports"},
      %{name: :company_settings, label: "Settings", icon: "hero-cog-6-tooth", path: ~p"/company/settings"}
    ]
  }
]

Grouped menu items

Wrap items in a group map with a title key to render labeled sections in the sidebar:

[
  %{
    title: "Main",
    menu_items: [
      %{name: :dashboard, label: "Dashboard", icon: "hero-home", path: ~p"/"}
    ]
  },
  %{
    title: "Settings",
    menu_items: [
      %{name: :settings, label: "Account", icon: "hero-user", path: ~p"/settings"}
    ]
  }
]

User menu items

user_menu_items follows the same structure and populates the dropdown attached to the user avatar. Nesting and grouping are not supported there.

Patching between menu items

If multiple menu items link to the same live view, set patch_group to the same value on each. Navigation between them will use patch instead of navigate, avoiding a full remount:

[
  %{name: :settings, label: "Settings", icon: "hero-cog", path: ~p"/settings", patch_group: MyAppWeb.SettingsLive},
  %{name: :settings_profile, label: "Profile", icon: "hero-user", path: ~p"/settings/profile", patch_group: MyAppWeb.SettingsLive},
  %{name: :settings_billing, label: "Billing", icon: "hero-credit-card", path: ~p"/settings/billing", patch_group: MyAppWeb.SettingsLive}
]

Handling signed in users

For the sidebar layout, put the user profile in the :bottom_section_content slot:

<.sidebar_layout ...>
  <:bottom_section_content>
    <.user_dropdown_menu
      user_menu_items={@user_menu_items}
      avatar_src={@current_user.avatar}
      current_user_name={@current_user.name}
    />
  </:bottom_section_content>
  ...
</.sidebar_layout>

For the stacked layout, pass user attrs directly:

<.stacked_layout
  avatar_src={@current_user.avatar}
  current_user_name={@current_user.name}
  user_menu_items={@user_menu_items}
  ...
/>

Custom menu items (sidebar layout only)

Sometimes you need a menu item that does something other than navigate — like toggling a flyout panel. Use this structure to render any component as a menu item:

# :main_menu_items
[
  %{
    custom_assigns: %{id: "id-you-apply-in-func"},
    custom_component: &render_me/1
  },
  # live components also work
  %{
    custom_assigns: %{id: "required-id-for-lc", current_user: @current_user},
    custom_component: MyApp.SomeLiveComponent
  }
]

If you’re using the collapsible sidebar, handle the isCollapsed Alpine JS state in your custom component markup.