phoenix_live_view

Phoenix LiveView

Phoenix LiveView enables rich, real-time user experiences with server-rendered HTML. For more information, see the initial announcement.

Note: Currently LiveView is under active development and we are focused on getting a stable and solid initial version out. For this reason, we will be accepting only bug reports in the issues tracker for now. We will open the issues tracker for features after the current milestone is ironed out.

Learning

As official guides are being developed, see our existing comprehensive docs and examples to get up to speed:

• Phoenix.LiveView docs for Elixir and JavaScript usage
• Phoenix.LiveViewTest for testing docs
• LiveView example repo with a handful of examples from Weather widgets, autocomplete search, and games like Snake or Pacman

Installation

To use LiveView, add to your mix.exs and run mix deps.get:

def deps do
  [
    {:phoenix_live_view, "~> 0.1.0"}
  ]
end

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 LiveView flash plug to your browser pipeline, after :fetch_flash:

# lib/my_app_web/router.ex

pipeline :browser do
  ...
  plug :fetch_flash
  plug Phoenix.LiveView.Flash
end

Then add the following imports to your web file in lib/my_app_web.ex:

# lib/my_app_web.ex

def controller do
  quote do
    ...
    import Phoenix.LiveView.Controller, only: [live_render: 3]
  end
end

def view do
  quote do
    ...
    import Phoenix.LiveView, only: [live_render: 2, live_render: 3, live_link: 1, live_link: 2]
  end
end

def router do
  quote do
    ...
    import Phoenix.LiveView.Router
  end
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

  # ...
end

Add LiveView NPM dependencies in your assets/package.json.

{
  "dependencies": {
    "phoenix": "file:../deps/phoenix",
    "phoenix_html": "file:../deps/phoenix_html",
    "phoenix_live_view": "file:../deps/phoenix_live_view"
  }
}

Then install the new npm dependency.

npm install --prefix assets

If you had previously installed phoenix_live_view and want to get the latest javascript, then force an install.

(cd assets && npm install --force phoenix_live_view)

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 liveSocket = new LiveSocket("/live", Socket)
liveSocket.connect()

Finally, by convention live views are saved in a lib/my_app_web/live/ directory. For live page reload support, add the following pattern to your config/dev.exs:

# config/dev.exs
config :demo, MyAppWeb.Endpoint,
  live_reload: [
    patterns: [
      ...,
      ~r{lib/my_app_web/live/.*(ex)$}
    ]
  ]

You can also optionally import the style for the default CSS classes in your app.css file.

/* assets/css/app.css */
@import "../../deps/phoenix_live_view/assets/css/live_view.css";

Browser Support

All current Chrome, Safari, Firefox, and MS Edge are supported. IE11 support is available with the following polyfills:

$ npm install --save --prefix assets mdn-polyfills url-search-params-polyfill formdata-polyfill child-replace-with-polyfill classlist-polyfill

// assets/js/app.js
import "mdn-polyfills/Array.prototype.from"
import "mdn-polyfills/NodeList.prototype.forEach"
import "mdn-polyfills/Element.prototype.closest"
import "mdn-polyfills/Element.prototype.matches"
import "child-replace-with-polyfill"
import "url-search-params-polyfill"
import "formdata-polyfill"
import "classlist-polyfill"

import {Socket} from "phoenix"
import LiveSocket from "phoenix_live_view"
...

Changelog

0.2.0 (2019-09-12)

Enhancements

• [LiveView] Add new :container option to use Phoenix.LiveView
• [LiveViewTest] Add live_isolated test helper for testing LiveViews which are not routable

Backwards incompatible changes

• Replace configure_temporary_assigns/2 with 3-tuple mount return, supporting a :temporary_assigns key
• Do not allow redirect/live_redirect on mount nor in child live views
• All phx-update containers now require a unique ID
• LiveSocket JavaScript constructor now requires explicit dependency injection of Phoenix Socket constructor. For example:

import {Socket} from "phoenix"
import LiveSocket from "phoenix_live_view"

let liveSocket = new LiveSocket("/live", Socket, {...})

Bug Fixes

• Fix phx-update=append/prepend failing to join new nested live views or wire up new phx-hooks
• Fix number input handling causing some browsers to reset form fields on invalid inputs
• Fix multi-select decoding causing server error
• Fix multi-select change tracking failing to submit an event when a value is deselected
• Fix live redirect loop triggered under certain scenarios
• Fix params failing to update on re-mounts after live_redirect
• Fix blur event metadata being sent with type of "focus"