Phoenix LiveView v0.15.0 Phoenix.LiveView.Router View Source

Provides LiveView routing for Phoenix routers.

Link to this section Summary

Functions

Fetches the LiveView and merges with the controller flash.

Link to this section Functions

Link to this function

fetch_live_flash(conn, _)

View Source

Fetches the LiveView and merges with the controller flash.

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

Examples

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

  pipeline :browser do
    ...
    plug :fetch_live_flash
  end
  ...
end
Link to this macro

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

View Source (macro)

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.

Options

  • :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}.

Examples

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"}
  end
end

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