Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 38 ยท Templates and Components

Layouts, Core Components and Navigation

Understand root and app layouts, the generated CoreComponents module (flash, button, input, table, modal), link helpers and how to add your own shared layout.

Every Phoenix page you see is made of three layers: a root layout that holds the <html> skeleton, an app layout that adds the site chrome (header, navigation, flash messages) and the page template itself. On top of that, generated projects include a CoreComponents module with ready-made pieces such as <.button>, <.input>, <.table>, <.modal> and <.flash>.

This lesson explains how the layers fit, how to customize them and how links and flash messages work. It builds on function components.

Phoenix code is read-only on this site. The TryIts rebuild the layering idea in JavaScript.

The three layers

A page is three nested layers

Root layout html, head, meta tags and scripts.
App layout Header, flash messages and main area.
1 / 2

The files live in lib/blog_web/components/layouts/:

HEEX
<%!-- root.html.heex --%>
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <.live_title suffix=" ยท Blog">{assigns[:page_title] || "Home"}</.live_title>
    <link phx-track-static rel="stylesheet" href={~p"/assets/css/app.css"} />
    <script defer phx-track-static type="text/javascript" src={~p"/assets/js/app.js"}></script>
  </head>
  <body>
    {@inner_content}
  </body>
</html>

The root layout is set in the router pipeline with plug :put_root_layout, html: {BlogWeb.Layouts, :root} and is rendered only on a full page load. The app layout is a function component that wraps each page:

ELIXIR
defmodule BlogWeb.Layouts do
  use BlogWeb, :html

  embed_templates "layouts/*"
end
HEEX
<%!-- app.html.heex --%>
<header class="px-4 py-3">
  <.link navigate={~p"/"}>Blog</.link>
  <.link navigate={~p"/posts"}>Posts</.link>
</header>

<main class="mx-auto max-w-2xl p-4">
  <.flash_group flash={@flash} />
  {render_slot(@inner_block)}
</main>

In controllers the layout is rendered for you. In LiveViews it is the layout option. To use a different layout for a section of the site, call put_layout(conn, html: {BlogWeb.Layouts, :admin}) in a plug.

Setting the page title

Assign page_title in the controller (assign(conn, :page_title, "Posts")) and the root layout's <.live_title> shows it with the suffix. Set it in every action so browser tabs and search results make sense.

HEEX
<.link href={~p"/about"}>About</.link>              <%!-- normal browser navigation --%>
<.link navigate={~p"/posts"}>Posts</.link>           <%!-- LiveView-to-LiveView, no full reload --%>
<.link patch={~p"/posts?page=2"}>Next</.link>        <%!-- same LiveView, new params --%>
<.link href={~p"/posts/#{@post}"} method="delete" data-confirm="Sure?">Delete</.link>

href with method="delete" generates a small piece of JavaScript that submits a hidden form with the right method and CSRF token. For plain controller pages href is what you use; navigate and patch matter once you reach LiveView.

Flash messages

put_flash(conn, :info, "Saved") stores a message for the next request, and <.flash_group flash={@flash} /> in the layout shows it. The generated flash component supports :info and :error kinds and a dismiss button. Add success or warning kinds by extending the component.

Tour of CoreComponents

lib/blog_web/components/core_components.ex is your code: edit it freely. Typical contents:

Component Use
<.button> Styled button, accepts phx-click and other attributes
<.input field={@form[:title]} label="Title" /> Label, input, error messages
<.simple_form> Form wrapper with actions slot
<.table rows={@posts}> The slot-driven table from the last lesson
<.list> Description list
<.header> Page heading with subtitle and actions
<.modal> Dialog with show/hide JavaScript
<.icon name="hero-x-mark" /> Heroicons
<.back navigate={~p"/posts"}> Back link

Because these are plain function components in your project, restyling the whole site means editing this one file.

ELIXIR
attr :type, :string, default: nil
attr :class, :string, default: nil
attr :rest, :global, include: ~w(disabled form name value)
slot :inner_block, required: true

def button(assigns) do
  ~H"""
  <button type={@type} class={["rounded px-3 py-2 font-semibold", @class]} {@rest}>
    {render_slot(@inner_block)}
  </button>
  """
end

Your own shared components

Create modules such as BlogWeb.Components.Card and import them where needed, or add them to html_helpers in lib/blog_web.ex so every template can use them:

ELIXIR
defp html_helpers do
  quote do
    import Phoenix.HTML
    import BlogWeb.CoreComponents
    import BlogWeb.Components.Card
    alias Phoenix.LiveView.JS
    unquote(verified_routes())
  end
end

Layers, modeled

JS Root layout, app layout and page

Press Run (or Ctrl + Enter) to see the console output here.

No output.

A flash that lasts one request

JS Flash survives exactly one redirect

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The first request sees the message and clears it, so the second shows nothing, just like Phoenix's flash.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which layout renders the <html> and <head> tags?

    root.html.heex holds the document skeleton; the app layout wraps page content inside <body>.
  2. 2. What does .link with method="delete" generate?

    Phoenix's JavaScript builds a hidden form with the correct method and token.
  3. 3. Who owns the CoreComponents module?

    It is generated into your project so you can restyle and extend it.
  4. 4. How is the page title set?

    The root layout reads the page_title assign and shows it in the title tag.

Summary

  • Pages nest three layers: root layout, app layout, page template.
  • <.link href|navigate|patch> covers normal links, LiveView navigation and param patches.
  • Flash messages last one request and show through <.flash_group>.
  • CoreComponents is generated, editable code; import your own components in html_helpers.

Next: Forms, changesets and to_form