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 id={@id} new_window={true} class="my-class">Home</a>

We could support the dynamic attributes with the following component:

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

  assigns =
    assigns
    |> Phoenix.LiveView.assign(:target, target)
    |> Phoenix.LiveView.assign(:extra, assigns_to_attributes(assigns, [:new_window]))

  ~H"\""
  <a href={@href} target={@target}>
    <%= render_block(@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.

It takes two optional arguments, the assigns to pass to the given function and a do-block - which will be converted into a @inner_block assign (see render_block/2 for more information).

The given function must expect one argument, which are the assigns as a map.

All of the assigns given are forwarded directly to the function as a single argument.

Examples

The function can be either local:

<%= component(&weather_component/1, city: "Kraków") %>

Or remote:

<%= component(&MyApp.Weather.component/1, city: "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>

Renders a 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.

LiveComponent comes in two shapes, stateful and stateless. See Phoenix.LiveComponent for more information.

Examples

All of the assigns given are forwarded directly to the live_component:

<%= live_component(MyApp.WeatherComponent, id: "thermostat", city: "Kraków") %>

Note the :id won't necessarily be used as the DOM ID. That's up to the component. However, note that the :id has a special meaning: whenever an :id is given, the component becomes stateful. Otherwise, :id is always set to nil.

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)

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.render city="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 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 validating 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>

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 whose function components directly in the template using an HTML-like notation. For example, a remote function:

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

A local function can be invoked with a leading dot:

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

where the component could be defined as follows:

defmodule MyApp.Weather do
  import Phoenix.LiveView.Helpers

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

Function components can also receive their inner content as the @inner_block assign to be rendered with render_block/2:

<MyApp.Weather.render city="Kraków">
  Some content to be assigned to @inner_block
</MyApp.Weather.render>

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