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

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

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.

This function is useful for lazily assigning values and sharing assigns. We will cover both use cases next.

lazy-assigns

Lazy assigns

Imagine you have a function component that accepts a color:

<.my_component color="red" />

The color is also optional, so you can skip it:

<.my_component />

In such cases, the implementation can use assign_new to lazily assign a color if none is given. Let's make it so it picks a random one when none is given:

def my_component(assigns) do
  assigns = assign_new(assigns, :bg_color, fn -> Enum.random(~w(bg-red-200 bg-green-200 bg-blue-200)) end)

  ~H"""
  <div class={@bg_color}>
    Example
  </div>
  """
end

sharing-assigns

Sharing assigns

It is possible to share assigns between the Plug pipeline and LiveView on disconnected render and between LiveViews when connected.

when-disconnected

When disconnected

When a user first accesses an application using LiveView, the LiveView is first rendered in its disconnected state, as part of a regular HTML response. By using assign_new in the mount callback of your LiveView, you can instruct LiveView to re-use any assigns already set in conn during disconnected state.

Imagine you have a Plug that does:

# A plug
def authenticate(conn, _opts) do
  if user_id = get_session(conn, :user_id) do
    assign(conn, :current_user, Accounts.get_user!(user_id))
  else
    send_resp(conn, :forbidden)
  end
end

You can re-use the :current_user assign in your LiveView during the initial render:

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

In such case conn.assigns.current_user will be used if present. If there is no such :current_user assign or the LiveView was mounted as part of the live navigation, where no Plug pipelines are invoked, then the anonymous function is invoked to execute the query instead.

when-connected

When connected

LiveView is also able to share assigns via assign_new within nested LiveView. If the parent LiveView defines a :current_user assign and the child LiveView also uses assign_new/3 to fetch the :current_user in its mount/3 callback, as above, the assign will be fetched from the parent LiveView, once again avoiding additional database queries.

Note that fun also provides access to the previously assigned values:

assigns =
    assigns
    |> assign_new(:foo, fn -> "foo" end)
    |> assign_new(:bar, fn %{foo: foo} -> foo <> "bar" end)

Filters the assigns as a list of keywords for use in dynamic tag attributes.

Useful for transforming caller assigns into dynamic attributes while stripping reserved keys from the result.

examples

Examples

Imagine the following my_link component which allows a caller to pass a new_window assign, along with any other attributes they would like to add to the element, such as class, data attributes, etc:

<.my_link to="/" id={@id} new_window={true} class="my-class">Home</.my_link>

We could support the dynamic attributes with the following component:

def my_link(assigns) do
  target = if assigns[:new_window], do: "_blank", else: false
  extra = assigns_to_attributes(assigns, [:new_window, :to])

  assigns =
    assigns
    |> assign(:target, target)
    |> assign(:extra, extra)

  ~H"""
  <a href={@to} target={@target} {@extra}>
    <%= render_slot(@inner_block) %>
  </a>
  """
end

The above would result in the following rendered HTML:

<a href="/" target="_blank" id="1" class="my-class">Home</a>

The second argument (optional) to assigns_to_attributes is a list of keys to exclude. It typically includes reserved keys by the component itself, which either do not belong in the markup, or are already handled explicitly by the component.

Declares attributes for a HEEx function components.

arguments

Arguments

• name - an atom defining the name of the attribute. Note that attributes cannot define the same name as any other attributes or slots declared for the same component.

• type - an atom defining the type of the attribute.

• opts - a keyword list of options. Defaults to [].

types

Types

An attribute is declared by its name, type, and options. The following types are supported:

options

Options

• :required - marks an attribute as required. If a caller does not pass the given attribute, a compile warning is issued.

• :default - the default value for the attribute if not provided. If this option is not set and the attribute is not given, accessing the attribute will fail unless a value is explicitly set with assign_new/3.

• :examples - a non-exhaustive list of values accepted by the attribute, used for documentation purposes.

• :values - an exhaustive list of values accepted by the attributes. If a caller passes a literal not contained in this list, a compile warning is issued.

• :doc - documentation for the attribute.

compile-time-validations

Compile-Time Validations

LiveView performs some validation of attributes via the :phoenix_live_view compiler. When attributes are defined, LiveView will warn at compilation time on the caller if:

• A required attribute of a component is missing.

• An unknown attribute is given.

• You specify a literal attribute (such as value="string" or value, but not value={expr}) and the type does not match. The following types currently support literal validation: :string, :atom, :boolean, :integer, :float, :map and :list.

• You specify a literal attribute and it is not a member of the :values list.

LiveView does not perform any validation at runtime. This means the type information is mostly used for documentation and reflection purposes.

On the side of the LiveView component itself, defining attributes provides the following quality of life improvements:

• The default value of all attributes will be added to the assigns map upfront.

• Attribute documentation is generated for the component.

• Required struct types are annotated and emit compilation warnings. For example, if you specify attr :user, User, required: true and then you write @user.non_valid_field in your template, a warning will be emitted.

• Calls made to the component are tracked for reflection and validation purposes.

documentation-generation

Documentation Generation

Public function components that define attributes will have their attribute types and docs injected into the function's documentation, depending on the value of the @doc module attribute:

• if @doc is a string, the attribute docs are injected into that string. The optional placeholder [INSERT LVATTRDOCS] can be used to specify where in the string the docs are injected. Otherwise, the docs are appended to the end of the @doc string.

• if @doc is unspecified, the attribute docs are used as the default @doc string.

• if @doc is false, the attribute docs are omitted entirely.

The injected attribute docs are formatted as a markdown list:

• name (:type) (required) - attr docs. Defaults to :default.

By default, all attributes will have their types and docs injected into the function @doc string. To hide a specific attribute, you can set the value of :doc to false.

example

Example

attr :name, :string, required: true
attr :age, :integer, required: true

def celebrate(assigns) do
  ~H"""
  <p>
    Happy birthday <%= @name %>!
    You are <%= @age %> years old.
  </p>
  """
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

Examples

iex> changed?(socket, :count)

Embeds external template files into the module as function components.

options

Options

• :root - The root directory to embed files. Defaults to the current module's directory (__DIR__)

A wildcard pattern may be used to select all files within a directory tree. For example, imagine a directory listing:

├── components.ex
├── pages
│   ├── about_page.html.heex
│   └── welcome_page.html.heex

Then to embed the page templates in your components.ex module:

defmodule MyAppWeb.Components do
  use Phoenix.Component

  embed_templates "pages/*"
end

Now, your module will have an about_page/1 and welcome_page/1 function component defined. Embedded templates also support declarative assigns via bodyless function definitions, for example:

defmodule MyAppWeb.Components do
  use Phoenix.Component

  embed_templates "pages/*"

  attr :name, :string, required: true
  def welcome_page(assigns)

  slot :header
  def about_page(assigns)
end

Multiple invocations of embed_templates is also supported.

Returns the flash message from the LiveView flash assign.

examples

Examples

<p class="alert alert-info"><%= live_flash(@flash, :info) %></p>
<p class="alert alert-danger"><%= live_flash(@flash, :error) %></p>

Renders a LiveView within a template.

This is useful in two situations:

• When rendering a child LiveView inside a LiveView.

• When rendering a LiveView inside a regular (non-live) controller/view.

options

Options

• :session - a map of binary keys with extra session data to be serialized and sent to the client. All session data currently in the connection is automatically available in LiveViews. You can use this option to provide extra data. Remember all session data is serialized and sent to the client, so you should always keep the data in the session to a minimum. For example, instead of storing a User struct, you should store the "user_id" and load the User when the LiveView mounts.

• :container - an optional tuple for the HTML tag and DOM attributes to be used for the LiveView container. For example: {:li, style: "color: blue;"}. By default it uses the module definition container. See the "Containers" section below for more information.

• :id - both the DOM ID and the ID to uniquely identify a LiveView. An :id is automatically generated when rendering root LiveViews but it is a required option when rendering a child LiveView.

• :sticky - an optional flag to maintain the LiveView across live redirects, even if it is nested within another LiveView. If you are rendering the sticky view within your live layout, make sure that the sticky view itself does not use the same layout. You can do so by returning {:ok, socket, layout: false} from mount.

examples

Examples

When rendering from a controller/view, you can call:

<%= live_render(@conn, MyApp.ThermostatLive) %>

Or:

<%= live_render(@conn, MyApp.ThermostatLive, session: %{"home_id" => @home.id}) %>

Within another LiveView, you must pass the :id option:

<%= live_render(@socket, MyApp.ThermostatLive, id: "thermostat") %>

containers

Containers

When a LiveView is rendered, its contents are wrapped in a container. By default, the container is a div tag with a handful of LiveView specific attributes.

The container can be customized in different ways:

• You can change the default container on use Phoenix.LiveView:

  use Phoenix.LiveView, container: {:tr, id: "foo-bar"}

• You can override the container tag and pass extra attributes when calling live_render (as well as on your live call in your router):

  live_render socket, MyLiveView, container: {:tr, class: "highlight"}

Renders a slot entry with the given optional argument.

<%= render_slot(@inner_block, @form) %>

If the slot has no entries, nil is returned.

If multiple slot entries are defined for the same slot,render_slot/2 will automatically render all entries, merging their contents. In case you want to use the entries' attributes, you need to iterate over the list to access each slot individually.

For example, imagine a table component:

<.table rows={@users}>
  <:col :let={user} label="Name">
    <%= user.name %>
  </:col>

  <:col :let={user} label="Address">
    <%= user.address %>
  </:col>
</.table>

At the top level, we pass the rows as an assign and we define a :col slot for each column we want in the table. Each column also has a label, which we are going to use in the table header.

Inside the component, you can render the table with headers, rows, and columns:

def table(assigns) do
  ~H"""
  <table>
    <tr>
      <%= for col <- @col do %>
        <th><%= col.label %></th>
      <% end %>
    </tr>
    <%= for row <- @rows do %>
      <tr>
        <%= for col <- @col do %>
          <td><%= render_slot(col, row) %></td>
        <% end %>
      </tr>
    <% end %>
  </table>
  """
end

The ~H sigil for writing HEEx templates inside source files.

HEEx is a HTML-aware and component-friendly extension of Elixir Embedded language (EEx) that provides:

• Built-in handling of HTML attributes

• An HTML-like notation for injecting function components

• Compile-time validation of the structure of the template

• The ability to minimize the amount of data sent over the wire

• Out-of-the-box code formatting via mix format

example

Example

~H"""
<div title="My div" class={@class}>
  <p>Hello <%= @name %></p>
  <MyApp.Weather.city name="Kraków"/>
</div>
"""

syntax

Syntax

HEEx is built on top of Embedded Elixir (EEx). In this section, we are going to cover the basic constructs in HEEx templates as well as its syntax extensions.

interpolation

Interpolation

Both HEEx and EEx templates use <%= ... %> for interpolating code inside the body of HTML tags:

<p>Hello, <%= @name %></p>

Similarly, conditionals and other block Elixir constructs are supported:

<%= if @show_greeting? do %>
  <p>Hello, <%= @name %></p>
<% end %>

Note we don't include the equal sign = in the closing <% end %> tag (because the closing tag does not output anything).

There is one important difference between HEEx and Elixir's builtin EEx. HEEx uses a specific annotation for interpolating HTML tags and attributes. Let's check it out.

heex-extension-defining-attributes

HEEx extension: Defining attributes

Since HEEx must parse and validate the HTML structure, code interpolation using <%= ... %> and <% ... %> are restricted to the body (inner content) of the HTML/component nodes and it cannot be applied within tags.

For instance, the following syntax is invalid:

<div class="<%= @class %>">
  ...
</div>

Instead do:

<div class={@class}>
  ...
</div>

You can put any Elixir expression between { ... }. For example, if you want to set classes, where some are static and others are dynamic, you can using string interpolation:

<div class={"btn btn-#{@type}"}>
  ...
</div>

The following attribute values have special meaning:

• true - if a value is true, the attribute is rendered with no value at all. For example, <input required={true}> is the same as <input required>;

• false or nil - if a value is false or nil, the attribute is not rendered;

• list (only for the class attribute) - each element of the list is processed as a different class. nil and false elements are discarded.

For multiple dynamic attributes, you can use the same notation but without assigning the expression to any specific attribute.

<div {@dynamic_attrs}>
  ...
</div>

The expression inside {...} must be either a keyword list or a map containing the key-value pairs representing the dynamic attributes.

You can pair this notation assigns_to_attributes/2 to strip out any internal LiveView attributes and user-defined assigns from being expanded into the HTML tag:

<div {assigns_to_attributes(assigns, [:visible])}>
  ...
</div>

The above would add all caller attributes into the HTML, but strip out LiveView assigns like slots, as well as user-defined assigns like :visible that are not meant to be added to the HTML itself. This approach is useful to allow a component to accept arbitrary HTML attributes like class, ARIA attributes, etc.

heex-extension-defining-function-components

HEEx extension: Defining function components

Function components are stateless components implemented as pure functions with the help of the Phoenix.Component module. They can be either local (same module) or remote (external module).

HEEx allows invoking these function components directly in the template using an HTML-like notation. For example, a remote function:

<MyApp.Weather.city name="Kraków"/>

A local function can be invoked with a leading dot:

<.city name="Kraków"/>

where the component could be defined as follows:

defmodule MyApp.Weather do
  use Phoenix.Component

  def city(assigns) do
    ~H"""
    The chosen city is: <%= @name %>.
    """
  end

  def country(assigns) do
    ~H"""
    The chosen country is: <%= @name %>.
    """
  end
end

It is typically best to group related functions into a single module, as opposed to having many modules with a single render/1 function. Function components support other important features, such as slots. You can learn more about components in Phoenix.Component.

heex-extension-special-attributes

HEEx extension: special attributes

Apart from normal HTML attributes, HEEx also supports some special attributes such as :let and :for.

:let

This is used by components and slots that want to yield a value back to the caller. For an example, see how form/1 works:

<.form :let={f} for={@changeset} phx-change="validate" phx-submit="save">
  <%= label(f, :username) %>
  <%= text_input(f, :username) %>
  ...
</.form>

Notice how the variable f, defined by .form, is used by label and text_input. The Phoenix.Component module has detailed documentation on how to use and implement such functionality.

:if and :for

It is a syntax sugar for <%= if .. do %> and <%= for .. do %> that can be used in regular HTML, function components, and slots.

For example in an HTML tag:

<table id="admin-table" :if={@admin?}>
  <tr :for={user <- @users}>
    <td><%= user.name %></td>
  </tr>
<table>

The snippet above will only render the table if @admin? is true, and generate a tr per user as you would expect from the collection.

:for can be used similarly in function components:

<.error :for={msg <- @errors} message={msg}/>

Which is equivalent to writing:

<%= for msg <- @errors do %>
  <.error message={msg} />
<% end %>

And :for in slots behaves the same way:

<.table id="my-table" rows={@users}>
  <:col :for={header <- @headers} :let={user}>
    <td><%= user[:header] %></td>
  </:col>
<table>

You can also combine :for and :if for tags, components, and slot to act as a filter:

<.error :for={msg <- @errors} :if={msg != nil} message={msg} />

code-formatting

Code formatting

You can automatically format HEEx templates (.heex) and ~H sigils using Phoenix.LiveView.HTMLFormatter. Please check that module for more information.

Declares a slot. See slot/3 for more information.

Declares a function component slot.

arguments

Arguments

• name - an atom defining the name of the slot. Note that slots cannot define the same name as any other slots or attributes declared for the same component.

• opts - a keyword list of options. Defaults to [].

• block - a code block containing calls to attr/3. Defaults to nil.

options

Options

• :required - marks a slot as required. If a caller does not pass a value for a required slot, a compilation warning is emitted. Otherwise, an omitted slot will default to [].

• :doc - documentation for the slot. Any slot attributes declared will have their documentation listed alongside the slot.

slot-attributes

Slot Attributes

A named slot may declare attributes by passing a block with calls to attr/3.

Unlike attributes, slot attributes cannot accept the :default option. Passing one will result in a compile warning being issued.

the-default-slot

The Default Slot

The default slot can be declared by passing :inner_block as the name of the slot.

Note that the :inner_block slot declaration cannot accept a block. Passing one will result in a compilation error.

compile-time-validations

Compile-Time Validations

LiveView performs some validation of slots via the :phoenix_live_view compiler. When slots are defined, LiveView will warn at compilation time on the caller if:

• A required slot of a component is missing.

• An unknown slot is given.

• An unknown slot attribute is given.

On the side of the function component itself, defining attributes provides the following quality of life improvements:

• Slot documentation is generated for the component.

• Calls made to the component are tracked for reflection and validation purposes.

documentation-generation

Documentation Generation

Public function components that define slots will have their docs injected into the function's documentation, depending on the value of the @doc module attribute:

• if @doc is a string, the slot docs are injected into that string. The optional placeholder [INSERT LVATTRDOCS] can be used to specify where in the string the docs are injected. Otherwise, the docs are appended to the end of the @doc string.

• if @doc is unspecified, the slot docs are used as the default @doc string.

• if @doc is false, the slot docs are omitted entirely.

The injected slot docs are formatted as a markdown list:

• name (required) - slot docs. Accepts attributes:
  • name (:type) (required) - attr docs. Defaults to :default.

By default, all slots will have their docs injected into the function @doc string. To hide a specific slot, you can set the value of :doc to false.

example

Example

slot :header
slot :inner_block, required: true
slot :footer

def modal(assigns) do
  ~H"""
  <div class="modal">
    <div class="modal-header">
      <%= render_slot(@header) || "Modal" %>
    </div>
    <div class="modal-body">
      <%= render_slot(@inner_block) %>
    </div>
    <div class="modal-footer">
      <%= render_slot(@footer) || submit_button() %>
    </div>
  </div>
  """
end

As shown in the example above, render_slot/1 returns nil when an optional slot is declared and none is given. This can be used to attach default behaviour.

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.

The update function may also be of arity 2, in which case it receives the current key's value as the first argument and the current assigns as the second argument. Raises if the key does not exist.

examples

Examples

iex> update(socket, :count, fn count -> count + 1 end)
iex> update(socket, :count, &(&1 + 1))
iex> update(socket, :max_users_this_session, fn current_max, %{users: users} ->
       max(current_max, length(users))
     end)

Returns the entry errors for an upload.

The following error may be returned:

• :too_many_files - The number of selected files exceeds the :max_entries constraint

examples

Examples

def error_to_string(:too_many_files), do: "You have selected too many files"

<%= for err <- upload_errors(@uploads.avatar) do %>
  <div class="alert alert-danger">
    <%= error_to_string(err) %>
  </div>
<% end %>

Returns the entry errors for an upload.

The following errors may be returned:

• :too_large - The entry exceeds the :max_file_size constraint
• :not_accepted - The entry does not match the :accept MIME types

examples

Examples

def error_to_string(:too_large), do: "Too large"
def error_to_string(:not_accepted), do: "You have selected an unacceptable file type"

<%= for entry <- @uploads.avatar.entries do %>
  <%= for err <- upload_errors(@uploads.avatar, entry) do %>
    <div class="alert alert-danger">
      <%= error_to_string(err) %>
    </div>
  <% end %>
<% end %>