Uses LiveView in the current module to mark it a LiveView.

use Phoenix.LiveView,
  namespace: MyAppWeb,
  container: {:tr, class: "colorized"},
  layout: {MyAppWeb.LayoutView, "live.html"}

Options

• :namespace - configures the namespace the LiveView is in
• :container - configures the container the LiveView will be wrapped in
• :layout - configures the layout the LiveView will be rendered in

Allows an upload for the provided name.

Options

• :accept - Required. A list of unique file type specifiers or the atom :any to allow any kind of file. For example, [".jpeg"], :any, etc.

• :max_entries - The maximum number of selected files to allow per file input. Defaults to 1.

• :max_file_size - The maximum file size in bytes to allow to be uploaded. Defaults 8MB. For example, 12_000_000.

• :chunk_size - The chunk size in bytes to send when uploading. Defaults 64_000.

• :chunk_timeout - The time in milliseconds to wait before closing the upload channel when a new chunk has not been received. Defaults 10_000.

• :external - The 2-arity function for generating metadata for external client uploaders. See the Uploads section for example usage.

• :progress - The optional 3-arity function for receiving progress events

• :auto_upload - Instructs the client to upload the file automatically on file selection instead of waiting for form submits. Default false.

Raises when a previously allowed upload under the same name is still active.

Examples

allow_upload(socket, :avatar, accept: ~w(.jpg .jpeg), max_entries: 2)
allow_upload(socket, :avatar, accept: :any)

For consuming files automatically as they are uploaded, you can pair auto_upload: true with a custom progress function to consume the entries as they are completed. For example:

allow_upload(socket, :avatar, accept: :any, progress: &handle_progress/3, auto_upload: true)

defp handle_progress(:avatar, entry, socket) do
  if entry.done? do
    uploaded_file =
      consume_uploaded_entry(socket, entry, fn %{} = meta ->
        ...
      end)

    {:noreply, put_flash(socket, :info, "file #{uploaded_file.name} uploaded")}
  else
    {:noreply, socket}
  end
end

Adds key-value pairs to assigns.

The first argument is either a LiveView socket or an assigns map from function components.

A keyword list or a map of assigns must be given as argument to be merged into existing assigns.

Examples

iex> assign(socket, name: "Elixir", logo: "💧")
iex> assign(socket, %{name: "Elixir"})

Adds a key-value pair to socket_or_assigns.

The first argument is either a LiveView socket or an assigns map from function components.

Examples

iex> assign(socket, :name, "Elixir")

Assigns the given key with value from fun into socket_or_assigns if one does not yet exist.

The first argument is either a LiveView socket or an assigns map from function components.

Useful for lazily assigning values and referencing parent assigns.

Referencing parent assigns

When a LiveView is mounted in a disconnected state, the Plug.Conn assigns will be available for reference via assign_new/3, allowing assigns to be shared for the initial HTTP request. The Plug.Conn assigns will not be available during the connected mount. Likewise, nested LiveView children have access to their parent's assigns on mount using assign_new/3, which allows assigns to be shared down the nested LiveView tree.

Examples

# controller
conn
|> assign(:current_user, user)
|> LiveView.Controller.live_render(MyLive, session: %{"user_id" => user.id})

# LiveView mount
def mount(_params, %{"user_id" => user_id}, socket) do
  {:ok, assign_new(socket, :current_user, fn -> Accounts.get_user!(user_id) end)}
end

Attaches the given fun by name for the lifecycle stage into socket.

Note: This function is for server-side lifecycle callbacks. For client-side hooks, see the JS Interop guide.

Hooks provide a mechanism to tap into key stages of the LiveView lifecycle in order to bind/update assigns, intercept events, patches, and regular messages when necessary, and to inject common functionality. Hooks may be attached to any of the following lifecycle stages: :mount (via on_mount/1), :handle_params, :handle_event, and :handle_info.

Return Values

Lifecycle hooks take place immediately before a given lifecycle callback is invoked on the LiveView. A hook may return {:halt, socket} to halt the reduction, otherwise it must return {:cont, socket} so the operation may continue until all hooks have been invoked for the current stage.

Halting the lifecycle

Note that halting from a hook will halt the entire lifecycle stage. This means that when a hook returns {:halt, socket} then the LiveView callback will not be invoked. This has some implications.

Implications for plugin authors

When defining a plugin that matches on specific callbacks, you must define a catch-all clause, as your hook will be invoked even for events you may not be interested on.

Implications for end-users

Allowing a hook to halt the invocation of the callback means that you can attach hooks to intercept specific events before detaching themselves, while allowing other events to continue normally.

Examples

def mount(_params, _session, socket) do
  socket =
    attach_hook(socket, :my_hook, :handle_event, fn
      "very-special-event", _params, socket ->
        # Handle the very special event and then detach the hook
        {:halt, detach_hook(socket, :my_hook, :handle_event)}

      _event, _params, socket ->
        {:cont, socket}
    end)

  {:ok, socket}
end

Cancels an upload for the given entry.

Examples

<%= for entry <- @uploads.avatar.entries do %>
  ...
  <button phx-click="cancel-upload" phx-value-ref="<%= entry.ref %>">cancel</button>
<% end %>

def handle_event("cancel-upload", %{"ref" => ref}, socket) do
  {:noreply, cancel_upload(socket, :avatar, ref)}
end

Checks if the given key changed in socket_or_assigns.

The first argument is either a LiveView socket or an assigns map from function components.

Examples

iex> changed?(socket, :count)

Clears the flash.

Examples

iex> clear_flash(socket)

Clears a key from the flash.

Examples

iex> clear_flash(socket, :info)

Returns true if the socket is connected.

Useful for checking the connectivity status when mounting the view. For example, on initial page render, the view is mounted statically, rendered, and the HTML is sent to the client. Once the client connects to the server, a LiveView is then spawned and mounted statefully within a process. Use connected?/1 to conditionally perform stateful work, such as subscribing to pubsub topics, sending messages, etc.

Examples

defmodule DemoWeb.ClockLive do
  use Phoenix.LiveView
  ...
  def mount(_params, _session, socket) do
    if connected?(socket), do: :timer.send_interval(1000, self(), :tick)

    {:ok, assign(socket, date: :calendar.local_time())}
  end

  def handle_info(:tick, socket) do
    {:noreply, assign(socket, date: :calendar.local_time())}
  end
end

Consumes the uploaded entries.

Raises when there are still entries in progress. Typically called when submitting a form to handle the uploaded entries alongside the form data. For form submissions, it is guaranteed that all entries have completed before the submit event is invoked. Once entries are consumed, they are removed from the upload.

Examples

def handle_event("save", _params, socket) do
  uploaded_files =
    consume_uploaded_entries(socket, :avatar, fn %{path: path}, _entry ->
      dest = Path.join("priv/static/uploads", Path.basename(path))
      File.cp!(path, dest)
      Routes.static_path(socket, "/uploads/#{Path.basename(dest)}")
    end)
  {:noreply, update(socket, :uploaded_files, &(&1 ++ uploaded_files))}
end

Consumes an individual uploaded entry.

Raises when the entry is still in progress. Typically called when submitting a form to handle the uploaded entries alongside the form data. Once entries are consumed, they are removed from the upload.

This is a lower-level feature than consume_uploaded_entries/3 and useful for scenarios where you want to consume entries as they are individually completed.

Examples

def handle_event("save", _params, socket) do
  case uploaded_entries(socket, :avatar) do
    {[_|_] = entries, []} ->
      uploaded_files = for entry <- entries do
        consume_uploaded_entry(socket, entry, fn %{path: path} ->
          dest = Path.join("priv/static/uploads", Path.basename(path))
          File.cp!(path, dest)
          Routes.static_path(socket, "/uploads/#{Path.basename(dest)}")
        end)
      end
      {:noreply, update(socket, :uploaded_files, &(&1 ++ uploaded_files))}

    _ ->
      {:noreply, socket}
  end
end

Detaches a hook with the given name from the lifecycle stage.

Note: This function is for server-side lifecycle callbacks. For client-side hooks, see the JS Interop guide.

If no hook is found, this function is a no-op.

Examples

def handle_event(_, socket) do
  {:noreply, detach_hook(socket, :hook_that_was_attached, :handle_event)}
end

Revokes a previously allowed upload from allow_upload/3.

Examples

disallow_upload(socket, :avatar)

Accesses the connect info from the socket to use on connected mount.

Connect info are only sent when the client connects to the server and only remain available during mount. nil is returned when called in a disconnected state and a RuntimeError is raised if called after mount.

Examples

First, when invoking the LiveView socket, you need to declare the connect_info you want to receive. Typically, it includes at least the session but it may include other keys, such as :peer_data. See Phoenix.Endpoint.socket/3:

socket "/live", Phoenix.LiveView.Socket,
  websocket: [connect_info: [:peer_data, session: @session_options]]

Those values can now be accessed on the connected mount as get_connect_info/1:

def mount(_params, _session, socket) do
  if info = get_connect_info(socket) do
    {:ok, assign(socket, ip: info.peer_data.address)}
  else
    {:ok, assign(socket, ip: nil)}
  end
end

Accesses the connect params sent by the client for use on connected mount.

Connect params are only sent when the client connects to the server and only remain available during mount. nil is returned when called in a disconnected state and a RuntimeError is raised if called after mount.

Reserved params

The following params have special meaning in LiveView:

• "_csrf_token" - the CSRF Token which must be explicitly set by the user when connecting
• "_mounts" - the number of times the current LiveView is mounted. It is 0 on first mount, then increases on each reconnect. It resets when navigating away from the current LiveView or on errors
• "_track_static" - set automatically with a list of all href/src from tags with the phx-track-static annotation in them. If there are no such tags, nothing is sent

Examples

def mount(_params, _session, socket) do
  {:ok, assign(socket, width: get_connect_params(socket)["width"] || @width)}
end

Declares a module callback to be invoked on the LiveView's mount.

The function within the given module, which must be named on_mount, will be invoked before both disconnected and connected mounts. The hook has the option to either halt or continue the mounting process as usual. If you wish to redirect the LiveView, you must halt, otherwise an error will be raised.

Tip: if you need to define multiple on_mount callbacks, avoid defining multiple modules. Instead, pass a tuple and use pattern matching to handle different cases:

def on_mount(:admin, _params, _session, _socket) do
  {:cont, socket}
end

def on_mount(:user, _params, _session, _socket) do
  {:cont, socket}
end

And then invoke it as:

on_mount {MyAppWeb.SomeHook, :admin}
on_mount {MyAppWeb.SomeHook, :user}

Registering on_mount hooks can be useful to perform authentication as well as add custom behaviour to other callbacks via attach_hook/4.

Examples

The following is an example of attaching a hook via Phoenix.LiveView.Router.live_session/3:

# lib/my_app_web/live/init_assigns.ex
defmodule MyAppWeb.InitAssigns do
  @moduledoc """
  Ensures common `assigns` are applied to all LiveViews attaching this hook.
  """
  import Phoenix.LiveView

  def on_mount(:default, _params, _session, socket) do
    {:cont, assign(socket, :page_title, "DemoWeb")}
  end

  def on_mount(:user, _params, _session, socket) do
  end

  def on_mount(:admin, _params, _session, socket) do
  end
end

# lib/my_app_web/router.ex
defmodule MyAppWeb.Router do
  use MyAppWeb, :router

  # pipelines, plugs, etc.

  live_session :default, on_mount: MyAppWeb.InitAssigns do
    scope "/", MyAppWeb do
      pipe_through :browser
      live "/", PageLive, :index
    end
  end

  live_session :authenticated, on_mount: {MyAppWeb.InitAssigns, :user} do
    scope "/", MyAppWeb do
      pipe_through [:browser, :require_user]
      live "/profile", UserLive.Profile, :index
    end
  end

  live_session :admins, on_mount: {MyAppWeb.InitAssigns, :admin} do
    scope "/admin", MyAppWeb.Admin do
      pipe_through [:browser, :require_user, :require_admin]
      live "/", AdminLive.Index, :index
    end
  end
end

Pushes an event to the client to be consumed by hooks.

Note: events will be dispatched to all active hooks on the client who are handling the given event. Scoped events can be achieved by namespacing your event names.

Examples

{:noreply, push_event(socket, "scores", %{points: 100, user: "josé"})}

Annotates the socket for navigation within the current LiveView.

When navigating to the current LiveView, handle_params/3 is immediately invoked to handle the change of params and URL state. Then the new state is pushed to the client, without reloading the whole page while also maintaining the current scroll position. For live redirects to another LiveView, use push_redirect/2.

Options

• :to - the required path to link to. It must always be a local path
• :replace - the flag to replace the current history or push a new state. Defaults false.

Examples

{:noreply, push_patch(socket, to: "/")}
{:noreply, push_patch(socket, to: "/", replace: true)}

Annotates the socket for navigation to another LiveView.

The current LiveView will be shutdown and a new one will be mounted in its place, without reloading the whole page. This can also be used to remount the same LiveView, in case you want to start fresh. If you want to navigate to the same LiveView without remounting it, use push_patch/2 instead.

Options

• :to - the required path to link to. It must always be a local path
• :replace - the flag to replace the current history or push a new state. Defaults false.

Examples

{:noreply, push_redirect(socket, to: "/")}
{:noreply, push_redirect(socket, to: "/", replace: true)}

Adds a flash message to the socket to be displayed.

Note: While you can use put_flash/3 inside a Phoenix.LiveComponent, components have their own @flash assigns. The @flash assign in a component is only copied to its parent LiveView if the component calls push_redirect/2 or push_patch/2.

Note: You must also place the Phoenix.LiveView.Router.fetch_live_flash/2 plug in your browser's pipeline in place of fetch_flash for LiveView flash messages be supported, for example:

import Phoenix.LiveView.Router

pipeline :browser do
  ...
  plug :fetch_live_flash
end

Examples

iex> put_flash(socket, :info, "It worked!")
iex> put_flash(socket, :error, "You can't access that page")

Annotates the socket for redirect to a destination path.

Note: LiveView redirects rely on instructing client to perform a window.location update on the provided redirect location. The whole page will be reloaded and all state will be discarded.

Options

• :to - the path to redirect to. It must always be a local path
• :external - an external path to redirect to

Asynchronously updates a Phoenix.LiveComponent with new assigns.

The :id that identifies the component must be passed as part of the assigns and it will be used to identify the live components to be updated.

The pid argument is optional and it defaults to the current process, which means the update instruction will be sent to a component running on the same LiveView. If the current process is not a LiveView or you want to send updates to a live component running on another LiveView, you should explicitly pass the LiveView's pid instead.

When the component receives the update, first the optional preload/1 then update/2 is invoked with the new assigns. If update/2 is not defined all assigns are simply merged into the socket.

While a component may always be updated from the parent by updating some parent assigns which will re-render the child, thus invoking update/2 on the child component, send_update/3 is useful for updating a component that entirely manages its own state, as well as messaging between components mounted in the same LiveView.

Examples

def handle_event("cancel-order", _, socket) do
  ...
  send_update(Cart, id: "cart", status: "cancelled")
  {:noreply, socket}
end

def handle_event("cancel-order-asynchronously", _, socket) do
  ...
  pid = self()

  Task.async(fn ->
    # Do something asynchronously
    send_update(pid, Cart, id: "cart", status: "cancelled")
  end)

  {:noreply, socket}
end

Similar to send_update/3 but the update will be delayed according to the given time_in_milliseconds.

Examples

def handle_event("cancel-order", _, socket) do
  ...
  send_update_after(Cart, [id: "cart", status: "cancelled"], 3000)
  {:noreply, socket}
end

def handle_event("cancel-order-asynchronously", _, socket) do
  ...
  pid = self()

  Task.async(fn ->
    # Do something asynchronously
    send_update_after(pid, Cart, [id: "cart", status: "cancelled"], 3000)
  end)

  {:noreply, socket}
end

Returns true if the socket is connected and the tracked static assets have changed.

This function is useful to detect if the client is running on an outdated version of the marked static files. It works by comparing the static paths sent by the client with the one on the server.

Note: this functionality requires Phoenix v1.5.2 or later.

To use this functionality, the first step is to annotate which static files you want to be tracked by LiveView, with the phx-track-static. For example:

<link phx-track-static rel="stylesheet" href="<%= Routes.static_path(@conn, "/css/app.css") %>"/>
<script defer phx-track-static type="text/javascript" src="<%= Routes.static_path(@conn, "/js/app.js") %>"></script>

Now, whenever LiveView connects to the server, it will send a copy src or href attributes of all tracked statics and compare those values with the latest entries computed by mix phx.digest in the server.

The tracked statics on the client will match the ones on the server the huge majority of times. However, if there is a new deployment, those values may differ. You can use this function to detect those cases and show a banner to the user, asking them to reload the page. To do so, first set the assign on mount:

def mount(params, session, socket) do
  {:ok, assign(socket, static_changed?: static_changed?(socket))}
end

And then in your views:

<%= if @static_changed? do %>
  <div id="reload-static">
    The app has been updated. Click here to <a href="#" onclick="window.location.reload()">reload</a>.
  </div>
<% end %>

If you prefer, you can also send a JavaScript script that immediately reloads the page.

Note: only set phx-track-static on your own assets. For example, do not set it in external JavaScript files:

<script defer phx-track-static type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js"></script>

Because you don't actually serve the file above, LiveView will interpret the static above as missing, and this function will return true.

Returns the transport pid of the socket.

Raises ArgumentError if the socket is not connected.

Examples

iex> transport_pid(socket)
#PID<0.107.0>

Updates an existing key with fun in the given socket_or_assigns.

The first argument is either a LiveView socket or an assigns map from function components.

The update function receives the current key's value and returns the updated value. Raises if the key does not exist.

Examples

iex> update(socket, :count, fn count -> count + 1 end)
iex> update(socket, :count, &(&1 + 1))

Returns the completed and in progress entries for the upload.

Examples

case uploaded_entries(socket, :photos) do
  {[_ | _] = completed, []} ->
    # all entries are completed

  {[], [_ | _] = in_progress} ->
    # all entries are still in progress
end