A tabbed interface for splitting related content into sibling panels that swap inside the same view.

Tabs is a compound component family with client-side behavior. The server renders a tablist of buttons and a matching set of panels, and the client keeps the selected tab and panel visibility in sync as the user clicks tabs or navigates with the keyboard. Inactive panels are hidden and pulled out of the layout without unmounting, so their DOM and any LiveComponent state inside them survive every tab switch.

The component family is composed of pieces that are designed to be used together:

• tabs/1: the container that scopes a single tab instance and enables its client behavior. Required wrapper.
• tabs_list/1: the tablist row that holds the interactive tab buttons. Owns the visual variant and size.
• tabs_panel/1: the content panel rendered for one tab.

A typical structure looks like this:

tabs
├── tabs_list
│   ├── :tab slot (button)
│   ├── :tab slot (button)
│   └── :tab slot (button)
├── tabs_panel (one per tab, matched by `name`)
├── tabs_panel
└── tabs_panel

Each :tab slot is paired to a tabs_panel by matching the slot's name against the panel's name attribute. That pairing determines which panel becomes visible when the tab is selected.

Usage

A static tabbed interface with three panels and a hard-coded initial selection:

<.tabs id="account">
  <.tabs_list active_tab="profile">
    <:tab name="profile">Profile</:tab>
    <:tab name="settings">Settings</:tab>
    <:tab name="notifications">Notifications</:tab>
  </.tabs_list>

  <.tabs_panel name="profile" active>
    Profile content here.
  </.tabs_panel>

  <.tabs_panel name="settings">
    Settings content here.
  </.tabs_panel>

  <.tabs_panel name="notifications">
    Notifications content here.
  </.tabs_panel>
</.tabs>

Each :tab name must match exactly one tabs_panel name. The active tab is determined by active_tab on tabs_list for initial render and by the active boolean on tabs_panel for panel visibility. When LiveView is in charge, both should be derived from the same assign so they stay in lockstep across patches.

Visual Variants

The variant attribute on tabs_list selects between distinct visual treatments. Each variant ships with the styles for the underlying buttons too, so a single attribute switches the entire tablist look.

<!-- Underlined tabs (default) -->
<.tabs id="default-tabs">
  <.tabs_list variant="default" active_tab="overview">
    <:tab name="overview">Overview</:tab>
    <:tab name="activity">Activity</:tab>
  </.tabs_list>
  <.tabs_panel name="overview" active>...</.tabs_panel>
  <.tabs_panel name="activity">...</.tabs_panel>
</.tabs>

<!-- Segmented control -->
<.tabs id="segmented-tabs">
  <.tabs_list variant="segmented" active_tab="day">
    <:tab name="day">Day</:tab>
    <:tab name="week">Week</:tab>
    <:tab name="month">Month</:tab>
  </.tabs_list>
  <.tabs_panel name="day" active>...</.tabs_panel>
  <.tabs_panel name="week">...</.tabs_panel>
  <.tabs_panel name="month">...</.tabs_panel>
</.tabs>

<!-- Ghost tabs -->
<.tabs id="ghost-tabs">
  <.tabs_list variant="ghost" active_tab="all">
    <:tab name="all">All</:tab>
    <:tab name="active">Active</:tab>
    <:tab name="archived">Archived</:tab>
  </.tabs_list>
  <.tabs_panel name="all" active>...</.tabs_panel>
  <.tabs_panel name="active">...</.tabs_panel>
  <.tabs_panel name="archived">...</.tabs_panel>
</.tabs>

Sizes

The size attribute on tabs_list aligns the tablist height with the corresponding button size, so a tab strip sits flush next to buttons of the same size in a toolbar. The size also controls the inner padding, font size, and icon size.

<.tabs_list size="xs" variant="segmented" active_tab="day">
  <:tab name="day">Day</:tab>
  <:tab name="week">Week</:tab>
</.tabs_list>

<.tabs_list size="sm" variant="default" active_tab="overview">
  <:tab name="overview">Overview</:tab>
  <:tab name="activity">Activity</:tab>
</.tabs_list>

<.tabs_list size="md" variant="ghost" active_tab="all">
  <:tab name="all">All</:tab>
  <:tab name="archived">Archived</:tab>
</.tabs_list>

Individual tab buttons stretch to the full height of the tablist (h-full), so the row stays visually consistent regardless of which tab is active.

Rich Tab Content

The :tab slot accepts arbitrary HEEx content, so tabs can include icons, badges, counts, or any other inline element. Add class="icon" to icon elements so the size variants pick them up automatically and shrink them to match the tab text:

<.tabs_list active_tab="messages">
  <:tab name="messages">
    <.icon name="hero-envelope" class="icon" /> Messages
    <.badge color="primary">3</.badge>
  </:tab>
  <:tab name="threads">
    <.icon name="hero-chat-bubble-left-right" class="icon" /> Threads
  </:tab>
  <:tab name="archived">
    <.icon name="hero-archive-box" class="icon" /> Archived
  </:tab>
</.tabs_list>

When a tab contains an element with class="icon", the size variants reduce the horizontal padding slightly and add a small gap between the icon and the label to keep the visual rhythm consistent.

Disabled Tabs

Mark a :tab as disabled by passing the standard HTML disabled attribute or aria-disabled="true". A disabled tab cannot be activated by clicking it, is skipped during arrow-key navigation, and is walked past when jumping with Home or End:

<.tabs_list active_tab="profile">
  <:tab name="profile">Profile</:tab>
  <:tab name="billing" disabled>Billing</:tab>
  <:tab name="team" aria-disabled="true">Team</:tab>
</.tabs_list>

Disabled tabs still occupy a slot in the visual row; they're just not interactive and not part of the keyboard cycle.

Selection and Focus

The tablist follows the WAI-ARIA tabs pattern with automatic activation, so moving to a tab also selects it and reveals its panel. Only the active tab is in the page's tab sequence: Tab moves focus into the tablist and lands on the active tab, then arrow keys move through the row. Right and Down go to the next enabled tab, Left and Up go to the previous one, and both wrap around the ends. Home jumps to the first enabled tab and End jumps to the last. Disabled tabs are skipped in every direction.

When the active tab changes, focus follows to the new tab and its panel is shown immediately. If the panel being hidden holds the focused element, focus is moved out of it first so it is not stranded inside a hidden subtree.

Keyboard activation runs the tab's phx-click exactly as a mouse click does, so a tablist that patches the URL or pushes an event stays in sync with the server when navigated with the keyboard.

Server-Driven Active Tab

The most common LiveView pattern is to keep the active tab in an assign and update it from a phx-click handler on each tab. The component reads active_tab on tabs_list and the matching active boolean on each tabs_panel, so deriving both from the same assign keeps them aligned across patches.

<.tabs id="account-tabs">
  <.tabs_list active_tab={@active_tab}>
    <:tab name="profile" phx-click={JS.push("set_tab", value: %{tab: "profile"})}>
      Profile
    </:tab>
    <:tab name="settings" phx-click={JS.push("set_tab", value: %{tab: "settings"})}>
      Settings
    </:tab>
  </.tabs_list>

  <.tabs_panel name="profile" active={@active_tab == "profile"}>
    Profile content...
  </.tabs_panel>
  <.tabs_panel name="settings" active={@active_tab == "settings"}>
    Settings content...
  </.tabs_panel>
</.tabs>

def mount(_params, _session, socket) do
  {:ok, assign(socket, :active_tab, "profile")}
end

def handle_event("set_tab", %{"tab" => tab}, socket) do
  {:noreply, assign(socket, :active_tab, tab)}
end

To persist the active tab across full reloads or share a link to a specific panel, drive the assign from URL parameters instead:

<.tabs id="account-tabs">
  <.tabs_list active_tab={@active_tab}>
    <:tab name="profile" phx-click={JS.push("set_tab", value: %{tab: "profile"})}>
      Profile
    </:tab>
    <:tab name="settings" phx-click={JS.push("set_tab", value: %{tab: "settings"})}>
      Settings
    </:tab>
  </.tabs_list>

  <.tabs_panel name="profile" active={@active_tab == "profile"}>...</.tabs_panel>
  <.tabs_panel name="settings" active={@active_tab == "settings"}>...</.tabs_panel>
</.tabs>

def handle_params(params, _uri, socket) do
  {:noreply, assign(socket, :active_tab, params["tab"] || "profile")}
end

def handle_event("set_tab", %{"tab" => tab}, socket) do
  {:noreply, push_patch(socket, to: ~p"/account?tab=#{tab}")}
end

Dynamic Tabs

Tabs and panels can be generated from a collection. Pair :for on the tab slot with :for on the panels using the same source list, and key off a stable identifier:

<.tabs id="dynamic-tabs">
  <.tabs_list active_tab={@active_tab}>
    <:tab
      :for={tab <- @tabs}
      name={tab.id}
      phx-click={JS.push("set_tab", value: %{tab: tab.id})}
    >
      {tab.title}
    </:tab>
  </.tabs_list>

  <.tabs_panel
    :for={tab <- @tabs}
    name={tab.id}
    active={@active_tab == tab.id}
  >
    {tab.body}
  </.tabs_panel>
</.tabs>

When the server adds, removes, or reorders tabs, the new buttons and panels are linked on the next patch, so dynamically added tabs become interactive without a remount.

Nested Tabs

Tabs can be nested by placing a second tabs/1 instance inside a tabs_panel. Each instance scopes its tablist and panel queries to its own container, so an inner tablist click never leaks up to the outer instance.

<.tabs id="parent">
  <.tabs_list variant="segmented" active_tab="profile">
    <:tab name="profile">Profile</:tab>
    <:tab name="settings">Settings</:tab>
  </.tabs_list>

  <.tabs_panel name="profile" active>
    <.tabs id="profile-inner">
      <.tabs_list variant="ghost" active_tab="personal">
        <:tab name="personal">Personal</:tab>
        <:tab name="preferences">Preferences</:tab>
      </.tabs_list>
      <.tabs_panel name="personal" active>...</.tabs_panel>
      <.tabs_panel name="preferences">...</.tabs_panel>
    </.tabs>
  </.tabs_panel>

  <.tabs_panel name="settings">...</.tabs_panel>
</.tabs>

Each tabs/1 needs its own unique id, since its client behavior is bound to that container.

Examples

A "view as" segmented switcher in a card header that flips a list view between groupings:

<section class="rounded-lg border border-base">
  <header class="flex items-center justify-between border-b border-base px-4 py-3">
    <h2 class="text-base font-semibold">Customers</h2>
    <.tabs id="customers-view">
      <.tabs_list size="xs" variant="segmented" active_tab={@view}>
        <:tab name="all" phx-click={JS.push("set_view", value: %{view: "all"})}>
          All
        </:tab>
        <:tab name="active" phx-click={JS.push("set_view", value: %{view: "active"})}>
          Active
        </:tab>
        <:tab name="churned" phx-click={JS.push("set_view", value: %{view: "churned"})}>
          Churned
        </:tab>
      </.tabs_list>

      <.tabs_panel name="all" active={@view == "all"}>
        <.live_component module={CustomersList} id="all" filter={:all} />
      </.tabs_panel>
      <.tabs_panel name="active" active={@view == "active"}>
        <.live_component module={CustomersList} id="active" filter={:active} />
      </.tabs_panel>
      <.tabs_panel name="churned" active={@view == "churned"}>
        <.live_component module={CustomersList} id="churned" filter={:churned} />
      </.tabs_panel>
    </.tabs>
  </header>
</section>

A settings page with URL-synced tabs and a disabled section gated behind a feature flag:

<.tabs id="settings">
  <.tabs_list active_tab={@active_tab}>
    <:tab name="profile" phx-click={JS.push("set_tab", value: %{tab: "profile"})}>
      <.icon name="hero-user" class="icon" /> Profile
    </:tab>
    <:tab name="security" phx-click={JS.push("set_tab", value: %{tab: "security"})}>
      <.icon name="hero-lock-closed" class="icon" /> Security
    </:tab>
    <:tab
      name="billing"
      disabled={!@billing_enabled}
      phx-click={JS.push("set_tab", value: %{tab: "billing"})}
    >
      <.icon name="hero-credit-card" class="icon" /> Billing
    </:tab>
  </.tabs_list>

  <.tabs_panel name="profile" active={@active_tab == "profile"} class="space-y-4 p-4">
    <.live_component module={ProfileForm} id="profile-form" user={@user} />
  </.tabs_panel>
  <.tabs_panel name="security" active={@active_tab == "security"} class="space-y-4 p-4">
    <.live_component module={SecurityForm} id="security-form" user={@user} />
  </.tabs_panel>
  <.tabs_panel name="billing" active={@active_tab == "billing"} class="space-y-4 p-4">
    <.live_component module={BillingForm} id="billing-form" user={@user} />
  </.tabs_panel>
</.tabs>

A documentation viewer with dynamic tabs generated from a list of source files:

<.tabs id="docs-tabs">
  <.tabs_list size="sm" variant="default" active_tab={@active_doc}>
    <:tab
      :for={doc <- @docs}
      name={doc.slug}
      phx-click={JS.push("open_doc", value: %{slug: doc.slug})}
    >
      {doc.title}
    </:tab>
  </.tabs_list>

  <.tabs_panel
    :for={doc <- @docs}
    name={doc.slug}
    active={@active_doc == doc.slug}
    class="prose max-w-none p-6"
  >
    {raw(doc.html)}
  </.tabs_panel>
</.tabs>

A workspace dashboard with nested tabs, where the outer tabs swap top-level sections and the inner tabs filter content inside one of the sections:

<.tabs id="workspace">
  <.tabs_list variant="default" active_tab={@section}>
    <:tab name="overview" phx-click={JS.push("set_section", value: %{section: "overview"})}>
      Overview
    </:tab>
    <:tab name="projects" phx-click={JS.push("set_section", value: %{section: "projects"})}>
      Projects
    </:tab>
  </.tabs_list>

  <.tabs_panel name="overview" active={@section == "overview"}>
    Overview content...
  </.tabs_panel>

  <.tabs_panel name="projects" active={@section == "projects"} class="space-y-4 p-4">
    <.tabs id="projects-filter">
      <.tabs_list size="xs" variant="ghost" active_tab={@project_filter}>
        <:tab name="all" phx-click={JS.push("filter_projects", value: %{filter: "all"})}>
          All
        </:tab>
        <:tab name="mine" phx-click={JS.push("filter_projects", value: %{filter: "mine"})}>
          Mine
        </:tab>
        <:tab name="starred" phx-click={JS.push("filter_projects", value: %{filter: "starred"})}>
          Starred
        </:tab>
      </.tabs_list>

      <.tabs_panel name="all" active={@project_filter == "all"}>...</.tabs_panel>
      <.tabs_panel name="mine" active={@project_filter == "mine"}>...</.tabs_panel>
      <.tabs_panel name="starred" active={@project_filter == "starred"}>...</.tabs_panel>
    </.tabs>
  </.tabs_panel>
</.tabs>