Provides LiveView routing for Phoenix routers.



fetch_live_flash(conn, _)

Fetches the LiveView and merges with the controller flash.


fetch_live_flash(conn, _)

Fetches the LiveView and merges with the controller flash.

Replaces the default :fetch_flash plug used by Phoenix.Router.


defmodule AppWeb.Router do
  use LiveGenWeb, :router
  import Phoenix.LiveView.Router

  pipeline :browser do
    plug :fetch_live_flash

live(path, live_view, action \\ nil, opts \\ [])

Defines a LiveView route.

A LiveView can be routed to by using the live macro with a path and the name of the LiveView:

live "/thermostat", ThermostatLive

By default, you can generate a route to this LiveView by using the live_path helper:

live_path(@socket, ThermostatLive)

Actions and live navigation

It is common for a LiveView to have multiple states and multiple URLs. For example, you can have a single LiveView that lists all articles on your web app. For each article there is an "Edit" button which, when pressed, opens up a modal on the same page to edit the article. It is a best practice to use live navigation in those cases, so when you click edit, the URL changes to "/articles/1/edit", even though you are still within the same LiveView. Similarly, you may also want to show a "New" button, which opens up the modal to create new entries, and you want this to be reflected in the URL as "/articles/new".

In order to make it easier to recognize the current "action" your LiveView is on, you can pass the action option when defining LiveViews too:

live "/articles", ArticleLive.Index, :index
live "/articles/new", ArticleLive.Index, :new
live "/articles/:id/edit", ArticleLive.Index, :edit

When an action is given, the generated route helpers are named after the LiveView itself (in the same way as for a controller). For the example above, we will have:

article_index_path(@socket, :index)
article_index_path(@socket, :new)
article_index_path(@socket, :edit, 123)

The current action will always be available inside the LiveView as the @live_action assign, that can be used to render a LiveComponent:

<%= if @live_action == :new do %>
  <%= live_component @socket, MyAppWeb.ArticleLive.FormComponent %>
<% end %>

Or can be used to show or hide parts of the template:

<%= if @live_action == :edit do %>
  <%= render("form.html", user: @user) %>
<% end %>

Note that @live_action will be nil if no action is given on the route definition.


  • :session - a map to be merged into the session, for example: %{"my_key" => 123}. The map keys must be strings.

    Can also be a "MFA" (module, function, arguments) tuple. That function will receive the connection and should return a map (with string keys) to be merged into the session. For example, {MyModule, :my_function, []} means MyModule.my_function(conn) is called.

  • :layout - an optional tuple to specify the rendering layout for the LiveView. If set, this option will replace the current root layout.

  • :container - an optional tuple for the HTML tag and DOM attributes to be used for the LiveView container. For example: {:li, style: "color: blue;"}. See Phoenix.LiveView.Helpers.live_render/3 for more information and examples.

  • :as - optionally configures the named helper. Defaults to :live when using a LiveView without actions or defaults to the LiveView name when using actions.

  • :metadata - a map to optional feed metadata used on telemetry events and route info, for example: %{route_name: :foo, access: :user}.


defmodule MyApp.Router
  use Phoenix.Router
  import Phoenix.LiveView.Router

  scope "/", MyApp do
    pipe_through [:browser]

    live "/thermostat", ThermostatLive
    live "/clock", ClockLive
    live "/dashboard", DashboardLive, layout: {MyApp.AlternativeView, "app.html"}

iex> MyApp.Router.Helpers.live_path(MyApp.Endpoint, MyApp.ThermostatLive)

© 2018 Chris McCord
Licensed under the MIT License.