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

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 optional second argument to assigns_to_attributes takes a list of keys to exclude which will typically be the keys reserved 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" />

It 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

The :for assign is the form's source data and the optional :action assign can be provided for the form's action. Additionally accepts the same options as Phoenix.HTML.Form.form_for/4 as optional assigns:

• :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.

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

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

• :csrf_token - for "post" requests, the form tag will automatically include an input tag with name _csrf_token. When set to false, this is disabled

• :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

<.form let={f} for={@changeset}>
  <%= text_input f, :name %>
</.form>

<.form let={user_form} for={@changeset} as="user" multipart {@extra}>
  <%= text_input user_form, :name %>
</.form>

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

.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

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

<%= live_file_input @uploads.avatar %>

Returns the flash message from the LiveView flash assign.

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

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

• :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

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

• :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

<%= 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 an originating plug request or within a parent LiveView.

Options

• :session - the map of extra session data to be serialized and sent to the client. Note that all session data currently in the connection is automatically available in LiveViews. You can use this option to provide extra data. Also note that the keys in the session are strings keys, as a reminder that data has to be serialized first.
• :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.
• :router - an optional router that enables this LiveView to perform live navigation. Only a single LiveView in a page may have the :router set. LiveViews defined at the router with the live macro automatically have the :router option set.

Examples

# within eex template
<%= live_render(@conn, MyApp.ThermostatLive) %>

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

Containers

When a LiveView is rendered, its contents are wrapped in a container. By default, said 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

<%= 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>
    <th>
      <%= for col <- @col do %>
        <td><%= col.label %></td>
      <% end >
    </th>
    <%= for row <- @rows do %>
      <tr>
        <%= for col <- @col do %>
          <td><%= render_slot(col, row) %></td>
        <% end %>
      </tr>
    <% end %>
  </table>
  """
end

Provides ~H sigil with HTML-safe and HTML-aware syntax 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.

HEEx is a HTML-aware and component-friendly extension of 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

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

Syntax

HEEx is built on top of Embedded Elixir (EEx), a templating syntax that uses <%= ... %> for interpolating results. In this section, we are going to cover the basic constructs in HEEx templates as well as its syntax extensions.

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

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>

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.

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"]}

Defines a slot's inner block.

This macro is mostly used by HTML engines that provides a slot implementation and rarely called directly.

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

Returns the entry errors for an upload.

The following errors may be returned:

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

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

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