View Source Installation
new-projects
New projects
Phoenix v1.5+ comes with built-in support for LiveView apps. Just create
your application with mix phx.new my_app --live
. The --live
flag has
become the default on Phoenix v1.6.
Once you've created a LiveView project, refer to LiveView documentation for further information on how to use it.
existing-projects
Existing projects
If you are using a Phoenix version earlier than v1.5 or your app already exists, continue with the following steps.
The instructions below will serve if you are installing the latest stable version
from Hex. To start using LiveView, add one of the following dependencies to your mix.exs
and run mix deps.get
.
If installing from Hex, use the latest version from there:
def deps do
[
{:phoenix_live_view, "~> 0.18"},
{:floki, ">= 0.30.0", only: :test}
]
end
If you want the latest features, install from GitHub:
def deps do
[
{:phoenix_live_view, github: "phoenixframework/phoenix_live_view"},
{:floki, ">= 0.30.0", only: :test}
]
Once installed, update your endpoint's configuration to include a signing salt.
You can generate a signing salt by running mix phx.gen.secret 32
:
# config/config.exs
config :my_app, MyAppWeb.Endpoint,
live_view: [signing_salt: "SECRET_SALT"]
Next, add the following imports to your web file in lib/my_app_web.ex
:
# lib/my_app_web.ex
def view do
quote do
# ...
import Phoenix.Component
end
end
def router do
quote do
# ...
import Phoenix.LiveView.Router
end
end
In that same file, update your live_view layout configuration:
# lib/my_app_web.ex
def live_view do
use Phoenix.LiveView,
- layout: {MyAppWeb.LayoutView, "live.html"}
+ layout: {MyAppWeb.LayoutView, :live}
unquote(view_helpers())
end
Then add the Phoenix.LiveView.Router.fetch_live_flash/2
plug to your browser pipeline, in place of :fetch_flash
:
# lib/my_app_web/router.ex
pipeline :browser do
# ...
plug :fetch_session
- plug :fetch_flash
+ plug :fetch_live_flash
end
Next, expose a new socket for LiveView updates in your app's endpoint module.
# lib/my_app_web/endpoint.ex
defmodule MyAppWeb.Endpoint do
use Phoenix.Endpoint
# ...
socket "/live", Phoenix.LiveView.Socket,
websocket: [connect_info: [session: @session_options]]
# ...
end
Where @session_options
are the options given to plug Plug.Session
by using a module attribute. If you don't have a @session_options
in your endpoint yet, here is how to create one:
- Find plug Plug.Session in your endpoint.ex
plug Plug.Session
store: :cookie,
key: "_my_app_key",
signing_salt: "somesigningsalt"
- Move the options to a module attribute at the top of your file:
@session_options [
store: :cookie,
key: "_my_app_key",
signing_salt: "somesigningsalt"
]
- Change the plug Plug.Session to use that attribute:
plug Plug.Session, @session_options
Finally, ensure you have placed a CSRF meta tag inside the <head>
tag in your layout (lib/my_app_web/templates/layout/app.html.*
) before app.js
is included, like so:
<meta name="csrf-token" content={Plug.CSRFProtection.get_csrf_token()} />
<script defer type="text/javascript" src="<%= Routes.static_path(@conn, "/js/app.js") %>"></script>
and enable connecting to a LiveView socket in your app.js
file.
// assets/js/app.js
import {Socket} from "phoenix"
import {LiveSocket} from "phoenix_live_view"
let csrfToken = document.querySelector("meta[name='csrf-token']").getAttribute("content")
let liveSocket = new LiveSocket("/live", Socket, {params: {_csrf_token: csrfToken}})
// Connect if there are any LiveViews on the page
liveSocket.connect()
// Expose liveSocket on window for web console debug logs and latency simulation:
// >> liveSocket.enableDebug()
// >> liveSocket.enableLatencySim(1000)
// The latency simulator is enabled for the duration of the browser session.
// Call disableLatencySim() to disable:
// >> liveSocket.disableLatencySim()
window.liveSocket = liveSocket
The JavaScript above expects phoenix_live_view
to be available as a JavaScript dependency. Let's do that.
npm-dependencies
npm dependencies
If using npm
, you need to add LiveView to your assets/package.json
. For a regular project, do:
{
"dependencies": {
"phoenix": "file:../deps/phoenix",
"phoenix_html": "file:../deps/phoenix_html",
"phoenix_live_view": "file:../deps/phoenix_live_view"
}
}
However, if you're adding phoenix_live_view
to an umbrella project, the dependency paths should be modified appropriately:
{
"dependencies": {
"phoenix": "file:../../../deps/phoenix",
"phoenix_html": "file:../../../deps/phoenix_html",
"phoenix_live_view": "file:../../../deps/phoenix_live_view"
}
}
Now run the next commands from the root of your web app project:
npm install --prefix assets
If you had previously installed phoenix_live_view
and want to get the
latest javascript, then force an install with:
npm install --force phoenix_live_view --prefix assets
layouts
Layouts
LiveView does not use the default app layout. Instead, you typically call put_root_layout
in your router to specify a layout that is used by both "regular" views and live views. In your router, do:
# lib/my_app_web/router.ex
pipeline :browser do
# ...
plug :put_root_layout, {MyAppWeb.LayoutView, :root}
# ...
end
The layout given to put_root_layout
is typically very barebones, with mostly <head>
and <body>
tags. For example:
<!DOCTYPE html>
<html lang="en">
<head>
<meta name="csrf-token" content={Plug.CSRFProtection.get_csrf_token()} />
<Phoenix.Component.live_title><%= assigns[:page_title] || "MyApp" %></Phoenix.Component.live_title>
<link rel="stylesheet" href="<%= Routes.static_path(@conn, "/css/app.css") %>"/>
<script defer type="text/javascript" src="<%= Routes.static_path(@conn, "/js/app.js") %>"></script>
</head>
<body>
<%= @inner_content %>
</body>
</html>
Once you have specified a root layout, app.html.heex
will be rendered within your root layout for all non-LiveViews. You may also optionally define a live.html.heex
layout to be used across all LiveViews, as we will describe in the next section.
Optionally, you can add a phx-track-static
to all script
and link
elements in your layout that use src
and href
. This way you can detect when new assets have been deployed by calling static_changed?
.
<link phx-track-static rel="stylesheet" href={Routes.static_path(@conn, "/css/app.css")} />
<script phx-track-static defer type="text/javascript" src={Routes.static_path(@conn, "/js/app.js")}></script>
progress-animation
Progress animation
If you want to show a progress bar as users perform live actions, we recommend using topbar
.
You can either add a copy of topbar
to assets/vendor/topbar.js
or add it as a npm dependency by calling:
$ npm install --prefix assets --save topbar
Then customize LiveView to use it in your assets/js/app.js
, right before the liveSocket.connect()
call:
// Show progress bar on live navigation and form submits
import topbar from "topbar"
topbar.config({barColors: {0: "#29d"}, shadowColor: "rgba(0, 0, 0, .3)"})
window.addEventListener("phx:page-loading-start", info => topbar.show())
window.addEventListener("phx:page-loading-stop", info => topbar.hide())
Alternatively, you can also delay showing the topbar
and wait if the results do not appear within 200ms:
// Show progress bar on live navigation and form submits
import topbar from "topbar"
topbar.config({barColors: {0: "#29d"}, shadowColor: "rgba(0, 0, 0, .3)"})
window.addEventListener("phx:page-loading-start", () => {
topbar.show(200)
})
window.addEventListener("phx:page-loading-stop", () => {
topbar.hide()
})
location-for-liveview-modules
Location for LiveView modules
By convention your LiveView modules and heex
templates should be placed in lib/my_app_web/live/
directory.