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 href="/" 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])

  assigns =
    assigns
    |> Phoenix.LiveView.assign(:target, target)
    |> Phoenix.LiveView.assign(:extra, extra)

  ~H"""
  <a href={@href} 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.

Renders a component defined by the given function.

This function is rarely invoked directly by users. Instead, it is used by ~H to render Phoenix.Components. For example, the following:

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

Is the same as:

<%= component(&MyApp.Weather.city/1, name: "Kraków") %>

Renders a form function component.

This function is built on top of Phoenix.HTML.Form.form_for/4. For more information about options and how to build inputs, see Phoenix.HTML.Form.

options

Options

The following attribute is required:

• :for - the form source data

The following attributes are optional:

• :action - the action to submit the form on. This attribute must be given if you intend to submit the form to a URL without LiveView.

• :as - the server side parameter in which all params for this form will be collected (i.e. as: :user_params would mean all fields for this form will be accessed as conn.params.user_params server side). Automatically inflected when a changeset is given.

• :multipart - when true, sets enctype to "multipart/form-data". Required when uploading files

• :method - the HTTP method. It is only used if an :action is given. If the method is not "get" nor "post", an input tag with name _method is generated along-side the form tag. Defaults to "post".

• :csrf_token - a token to authenticate the validity of requests. One is automatically generated when an action is given and the method is not "get". When set to false, no token is generated.

• :errors - use this to manually pass a keyword list of errors to the form (for example from conn.assigns[:errors]). This option is only used when a connection is used as the form source and it will make the errors available under f.errors

• :id - the ID of the form attribute. If an ID is given, all form inputs will also be prefixed by the given ID

All further assigns will be passed to the form tag.

examples

Examples

inside-liveview

Inside LiveView

The :for attribute is typically an Ecto.Changeset:

<.form let={f} for={@changeset} phx-change="change_name">
  <%= text_input f, :name %>
</.form>

<.form let={user_form} for={@changeset} multipart phx-change="change_user" phx-submit="save_user">
  <%= text_input user_form, :name %>
  <%= submit "Save" %>
</.form>

Notice how both examples use phx-change. The LiveView must implement the phx-change event and store the input values as they arrive on change. This is important because, if an unrelated change happens on the page, LiveView should re-render the inputs with their updated values. Without phx-change, the inputs would otherwise be cleared. Alternatively, you can use phx-update="ignore" on the form to discard any updates.

The :for attribute can also be an atom, in case you don't have an existing data layer but you want to use the existing form helpers. In this case, you need to pass the input values explicitly as they change (or use phx-update="ignore" as per the previous paragraph):

<.form let={user_form} for={:user} multipart phx-change="change_user" phx-submit="save_user">
  <%= text_input user_form, :name, value: @user_name %>
  <%= submit "Save" %>
</.form>

However, if you don't have a data layer, it may be more straight-forward to drop the form component altogether and simply rely on HTML:

<form multipart phx-change="change_user" phx-submit="save_user">
  <input type="text" name="user[name]" value={@user_name}>
  <input type="submit" name="Save">
</form>

outside-liveview

Outside LiveView

The form component can still be used to submit forms outside of LiveView. In such cases, the action attribute MUST be given. Without said attribute, the form method and csrf token are discarded.

<.form let={f} for={@changeset} action={Routes.comment_path(:create, @comment)}>
  <%= text_input f, :body %>
</.form>

Define a inner block, generally used by slots.

This macro is mostly used by HTML engines that provides a slot implementation and rarely called directly. The name must be the assign name the slot/block will be stored under.

If you're using HEEx templates, you should use its higher level <:slot> notation instead. See Phoenix.Component for more information.

A function component for rendering Phoenix.LiveComponent within a parent LiveView.

While LiveViews can be nested, each LiveView starts its own process. A LiveComponent provides similar functionality to LiveView, except they run in the same process as the LiveView, with its own encapsulated state. That's why they are called stateful components.

See Phoenix.LiveComponent for more information.

examples

Examples

.live_component requires the component :module and its :id to be given:

<.live_component module={MyApp.WeatherComponent} id="thermostat" city="Kraków" />

The :id is used to identify this LiveComponent throughout the LiveView lifecycle. Note the :id won't necessarily be used as the DOM ID. That's up to the component.

Deprecated API for rendering LiveComponent.

upgrading

Upgrading

In order to migrate from <%= live_component ... %> to <.live_component>, you must first:

1. Migrate from ~L sigil and .leex templates to ~H sigil and .heex templates

2. Then instead of:

   <%= live_component MyModule, id: "hello" do %>
   ...
   <% end %>

   You should do:

   <.live_component module={MyModule} id="hello">
   ...
   </.live_component>

3. If your component is using render_block/2, replace it by render_slot/2

Builds a file input tag for a LiveView upload.

Options may be passed through to the tag builder for custom attributes.

drag-and-drop

Drag and Drop

Drag and drop is supported by annotating the droppable container with a phx-drop-target attribute pointing to the DOM ID of the file input. By default, the file input ID is the upload ref, so the following markup is all that is required for drag and drop support:

<div class="container" phx-drop-target={@uploads.avatar.ref}>
    ...
    <%= live_file_input @uploads.avatar %>
</div>

examples

Examples

<%= live_file_input @uploads.avatar %>

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>

Generates an image preview on the client for a selected file.

examples

Examples

<%= for entry <- @uploads.avatar.entries do %>
  <%= live_img_preview entry, width: 75 %>
<% end %>

Generates a link that will patch the current LiveView.

When navigating to the current LiveView, Phoenix.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 live_redirect/2.

options

Options

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

All other options are forwarded to the anchor tag.

examples

Examples

<%= live_patch "home", to: Routes.page_path(@socket, :index) %>
<%= live_patch "next", to: Routes.live_path(@socket, MyLive, @page + 1) %>
<%= live_patch to: Routes.live_path(@socket, MyLive, dir: :asc), replace: false do %>
  Sort By Price
<% end %>

Generates a link that will redirect to a new LiveView of the same live session.

The current LiveView will be shut down 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 live_patch/2 instead.

Note: The live redirects are only supported between two LiveViews defined under the same live session. See Phoenix.LiveView.Router.live_session/3 for more details.

options

Options

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

All other options are forwarded to the anchor tag.

examples

Examples

<%= live_redirect "home", to: Routes.page_path(@socket, :index) %>
<%= live_redirect "next", to: Routes.live_path(@socket, MyLive, @page + 1) %>
<%= live_redirect to: Routes.live_path(@socket, MyLive, dir: :asc), replace: false do %>
  Sort By Price
<% end %>

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 title tag with automatic prefix/suffix on @page_title updates.

examples

Examples

<%= live_title_tag assigns[:page_title] || "Welcome", prefix: "MyApp – " %>

<%= live_title_tag assigns[:page_title] || "Welcome", suffix: " – MyApp" %>

Renders the @inner_block assign of a component with the given argument.

<%= render_block(@inner_block, value: @value)

This function is deprecated for function components. Use render_slot/2 instead.

Renders a slot entry with the given optional argument.

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

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.

Note: HEEx requires Elixir >= 1.12.0 in order to provide accurate file:line:column information in error messages. Earlier Elixir versions will work but will show inaccurate error messages.

Note: The HEEx HTML formatter requires Elixir >= 1.13.0. See the Phoenix.LiveView.HTMLFormatter for more information on template formatting.

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

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.

Provides ~L sigil with HTML safe Live EEx syntax inside source files.

iex> ~L"""
...> Hello <%= "world" %>
...> """
{:safe, ["Hello ", "world", "\n"]}

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 %>