Renders an async assign with slots for the different loading states. The result state takes precedence over subsequent loading and failed states.

Note: The inner block receives the result of the async assign as a :let. The let is only accessible to the inner block and is not in scope to the other slots.

Examples

<.async_result :let={org} assign={@org}>
  <:loading>Loading organization...</:loading>
  <:failed :let={_failure}>there was an error loading the organization</:failed>
  <%= if org do %>
    <%= org.name %>
  <% else %>
    You don't have an organization yet.
  <% end %>
</.async_result>

To display loading and failed states again on subsequent assign_async calls, reset the assign to a result-free %AsyncResult{}:

{:noreply,
  socket
  |> assign_async(:page, :data, &reload_data/0)
  |> assign(:page, AsyncResult.loading())}

Attributes

• assign (Phoenix.LiveView.AsyncResult) (required)

Slots

• loading - rendered while the assign is loading for the first time.
• failed - rendered when an error or exit is caught or assign_async returns {:error, reason} for the first time. Receives the error as a :let.
• inner_block - rendered when the assign is loaded successfully via AsyncResult.ok/2. Receives the result as a :let.

Generates a dynamically named HTML tag.

Raises an ArgumentError if the tag name is found to be unsafe HTML.

Attributes

• name (:string) (required) - The name of the tag, such as div.
• Global attributes are accepted. Additional HTML attributes to add to the tag, ensuring proper escaping.

Slots

• inner_block

Examples

<.dynamic_tag name="input" type="text"/>

<input type="text"/>

<.dynamic_tag name="p">content</.dynamic_tag>

<p>content</p>

Wraps tab focus around a container for accessibility.

This is an essential accessibility feature for interfaces such as modals, dialogs, and menus.

Attributes

• id (:string) (required) - The DOM identifier of the container tag.
• Global attributes are accepted. Additional HTML attributes to add to the container tag.

Slots

• inner_block (required) - The content rendered inside of the container tag.

Examples

Simply render your inner content within this component and focus will be wrapped around the container as the user tabs through the containers content:

<.focus_wrap id="my-modal" class="bg-white">
  <div id="modal-content">
    Are you sure?
    <button phx-click="cancel">Cancel</button>
    <button phx-click="confirm">OK</button>
  </div>
</.focus_wrap>

Renders a form.

This function receives a Phoenix.HTML.Form struct, generally created with to_form/2, and generates the relevant form tags. It can be used either inside LiveView or outside.

To see how forms work in practice, you can run mix phx.gen.live Blog Post posts title body:text inside your Phoenix application, which will setup the necessary database tables and LiveViews to manage your data.

Examples: inside LiveView

Inside LiveViews, this function component is typically called with as for={@form}, where @form is the result of the to_form/1 function. to_form/1 expects either a map or an Ecto.Changeset as the source of data and normalizes it into Phoenix.HTML.Form structure.

For example, you may use the parameters received in a Phoenix.LiveView.handle_event/3 callback to create an Ecto changeset and then use to_form/1 to convert it to a form. Then, in your templates, you pass the @form as argument to :for:

<.form
  for={@form}
  phx-change="change_name"
>
  <.input field={@form[:email]} />
</.form>

The .input component is generally defined as part of your own application and adds all styling necessary:

def input(assigns) do
  ~H"""
  <input type="text" name={@field.name} id={@field.id} value={@field.value} class="..." />
  """
end

A form accepts multiple options. For example, if you are doing file uploads and you want to capture submissions, you might write instead:

<.form
  for={@form}
  multipart
  phx-change="change_user"
  phx-submit="save_user"
>
  ...
  <input type="submit" value="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.

Using the for attribute

The for attribute can also be a map or an Ecto.Changeset. In such cases, a form will be created on the fly, and you can capture it using :let:

<.form
  :let={form}
  for={@changeset}
  phx-change="change_user"
>

However, such approach is discouraged in LiveView for two reasons:

• LiveView can better optimize your code if you access the form fields using @form[:field] rather than through the let-variable form

• Ecto changesets are meant to be single use. By never storing the changeset in the assign, you will be less tempted to use it across operations

A note on :errors

Even if changeset.errors is non-empty, errors will not be displayed in a form if the changeset :action is nil or :ignore.

This is useful for things like validation hints on form fields, e.g. an empty changeset for a new form. That changeset isn't valid, but we don't want to show errors until an actual user action has been performed.

For example, if the user submits and a Repo.insert/1 is called and fails on changeset validation, the action will be set to :insert to show that an insert was attempted, and the presence of that action will cause errors to be displayed. The same is true for Repo.update/delete.

Error visibility is handled by providing the action to to_form/2, which will set the underlying changeset action. You can also set the action manually by directly updating on the Ecto.Changeset struct field, or by using Ecto.Changeset.apply_action/2. Since the action can be arbitrary, you can set it to :validate or anything else to avoid giving the impression that a database operation has actually been attempted.

Displaying errors on used and unused input fields

Used inputs are only those inputs that have been focused, interacted with, or submitted by the client. In most cases, a user shouldn't receive error feedback for forms they haven't yet interacted with, until they submit the form. Filtering the errors based on used input fields can be done with used_input?/1.

Example: outside LiveView (regular HTTP requests)

The form component can still be used to submit forms outside of LiveView. In such cases, the standard HTML 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)}>
  <.input field={f[:body]} />
</.form>

In the example above, we passed a changeset to for and captured the value using :let={f}. This approach is ok outside of LiveViews, as there are no change tracking optimizations to consider.

CSRF protection

CSRF protection is a mechanism to ensure that the user who rendered the form is the one actually submitting it. This module generates a CSRF token by default. Your application should check this token on the server to avoid attackers from making requests on your server on behalf of other users. Phoenix by default checks this token.

When posting a form with a host in its address, such as "//host.com/path" instead of only "/path", Phoenix will include the host signature in the token and validate the token only if the accessed host is the same as the host in the token. This is to avoid tokens from leaking to third party applications. If this behaviour is problematic, you can generate a non-host specific token with Plug.CSRFProtection.get_csrf_token/0 and pass it to the form generator via the :csrf_token option.

Attributes

• for (:any) (required) - An existing form or the form source data.

• action (:string) - 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 (:atom) - The prefix to be used in names and IDs generated by the form. For example, setting as: :user_params means the parameters will be nested "user_params" in your handle_event or conn.params["user_params"] for regular HTTP requests. If you set this option, you must capture the form with :let.

• csrf_token (:any) - 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 (:list) - Use this to manually pass a keyword list of errors to the form. This option is useful when a regular map is given as the form source and it will make the errors available under f.errors. If you set this option, you must capture the form with :let.

• method (:string) - 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 alongside the form tag. If an :action is given with no method, the method will default to post.

• multipart (:boolean) - Sets enctype to multipart/form-data. Required when uploading files.

  Defaults to false.

• Global attributes are accepted. Additional HTML attributes to add to the form tag. Supports all globals plus: ["autocomplete", "name", "rel", "enctype", "novalidate", "target"].

Slots

• inner_block (required) - The content rendered inside of the form tag.

Renders nested form inputs for associations or embeds.

Attributes

• field (Phoenix.HTML.FormField) (required) - A %Phoenix.HTML.Form{}/field name tuple, for example: {@form[:email]}.

• id (:string) - The id to be used in the form, defaults to the concatenation of the given field to the parent form id.

• as (:atom) - The name to be used in the form, defaults to the concatenation of the given field to the parent form name.

• default (:any) - The value to use if none is available.

• prepend (:list) - The values to prepend when rendering. This only applies if the field value is a list and no parameters were sent through the form.

• append (:list) - The values to append when rendering. This only applies if the field value is a list and no parameters were sent through the form.

• skip_hidden (:boolean) - Skip the automatic rendering of hidden fields to allow for more tight control over the generated markup.

  Defaults to false.

• options (:list) - Any additional options for the Phoenix.HTML.FormData protocol implementation.

  Defaults to [].

Slots

• inner_block (required) - The content rendered for each nested form.

Examples

<.form
  :let={f}
  phx-change="change_name"
>
  <.inputs_for :let={f_nested} field={f[:nested]}>
    <.input type="text" field={f_nested[:name]} />
  </.inputs_for>
</.form>

Dynamically adding and removing inputs

Dynamically adding and removing inputs is supported by rendering named buttons for inserts and removals. Like inputs, buttons with name/value pairs are serialized with form data on change and submit events. Libraries such as Ecto, or custom param filtering can then inspect the parameters and handle the added or removed fields. This can be combined with Ecto.Changeset.cast/3's :sort_param and :drop_param options. For example, imagine a parent with an :emails has_many or embeds_many association. To cast the user input from a nested form, one simply needs to configure the options:

schema "mailing_lists" do
  field :title, :string

  embeds_many :emails, EmailNotification, on_replace: :delete do
    field :email, :string
    field :name, :string
  end
end

def changeset(list, attrs) do
  list
  |> cast(attrs, [:title])
  |> cast_embed(:emails,
    with: &email_changeset/2,
    sort_param: :emails_sort,
    drop_param: :emails_drop
  )
end

Here we see the :sort_param and :drop_param options in action.

Note: on_replace: :delete on the has_many and embeds_many is required when using these options.

When Ecto sees the specified sort or drop parameter from the form, it will sort the children based on the order they appear in the form, add new children it hasn't seen, or drop children if the parameter instructs it to do so.

The markup for such a schema and association would look like this:

<.inputs_for :let={ef} field={@form[:emails]}>
  <input type="hidden" name="mailing_list[emails_sort][]" value={ef.index} />
  <.input type="text" field={ef[:email]} placeholder="email" />
  <.input type="text" field={ef[:name]} placeholder="name" />
  <button
    type="button"
    name="mailing_list[emails_drop][]"
    value={ef.index}
    phx-click={JS.dispatch("change")}
  >
    <.icon name="hero-x-mark" class="w-6 h-6 relative top-2" />
  </button>
</.inputs_for>

<input type="hidden" name="mailing_list[emails_drop][]" />

<button type="button" name="mailing_list[emails_sort][]" value="new" phx-click={JS.dispatch("change")}>
  add more
</button>

We used inputs_for to render inputs for the :emails association, which contains an email address and name input for each child. Within the nested inputs, we render a hidden mailing_list[emails_sort][] input, which is set to the index of the given child. This tells Ecto's cast operation how to sort existing children, or where to insert new children. Next, we render the email and name inputs as usual. Then we render a button containing the "delete" text with the name mailing_list[emails_drop][], containing the index of the child as its value.

Like before, this tells Ecto to delete the child at this index when the button is clicked. We use phx-click={JS.dispatch("change")} on the button to tell LiveView to treat this button click as a change event, rather than a submit event on the form, which invokes our form's phx-change binding.

Outside the inputs_for, we render an empty mailing_list[emails_drop][] input, to ensure that all children are deleted when saving a form where the user dropped all entries. This hidden input is required whenever dropping associations.

Finally, we also render another button with the sort param name mailing_list[emails_sort][] and value="new" name with accompanied "add more" text. Please note that this button must have type="button" to prevent it from submitting the form. Ecto will treat unknown sort params as new children and build a new child. This button is optional and only necessary if you want to dyamically add entries. You can optionally add a similar button before the <.inputs_for>, in the case you want to prepend entries.

Intersperses separator slot between an enumerable.

Useful when you need to add a separator between items such as when rendering breadcrumbs for navigation. Provides each item to the inner block.

Examples

<.intersperse :let={item} enum={["home", "profile", "settings"]}>
  <:separator>
    <span class="sep">|</span>
  </:separator>
  <%= item %>
</.intersperse>

Renders the following markup:

home <span class="sep">|</span> profile <span class="sep">|</span> settings

Attributes

• enum (:any) (required) - the enumerable to intersperse with separators.

Slots

• inner_block (required) - the inner_block to render for each item.
• separator (required) - the slot for the separator.

Generates a link to a given route.

To navigate across pages, using traditional browser navigation, use the href attribute. To patch the current LiveView or navigate across LiveViews, use patch and navigate respectively.

Attributes

• navigate (:string) - Navigates from a LiveView to a new LiveView. The browser page is kept, but a new LiveView process is mounted and its content on the page is reloaded. It is only possible to navigate between LiveViews declared under the same router Phoenix.LiveView.Router.live_session/3. Otherwise, a full browser redirect is used.

• patch (:string) - Patches the current LiveView. The handle_params callback of the current LiveView will be invoked and the minimum content will be sent over the wire, as any other LiveView diff.

• href (:any) - Uses traditional browser navigation to the new location. This means the whole page is reloaded on the browser.

• replace (:boolean) - When using :patch or :navigate, should the browser's history be replaced with pushState?

  Defaults to false.

• method (:string) - The HTTP method to use with the link. This is intended for usage outside of LiveView and therefore only works with the href={...} attribute. It has no effect on patch and navigate instructions.

  In case the method is not get, the link is generated inside the form which sets the proper information. In order to submit the form, JavaScript must be enabled in the browser.

  Defaults to "get".

• csrf_token (:any) - A boolean or custom token to use for links with an HTTP method other than get. Defaults to true.

• Global attributes are accepted. Additional HTML attributes added to the a tag. Supports all globals plus: ["download", "hreflang", "referrerpolicy", "rel", "target", "type"].

Slots

• inner_block (required) - The content rendered inside of the a tag.

Examples

<.link href="/">Regular anchor link</.link>

<.link navigate={~p"/"} class="underline">home</.link>

<.link navigate={~p"/?sort=asc"} replace={false}>
  Sort By Price
</.link>

<.link patch={~p"/details"}>view details</.link>

<.link href={URI.parse("https://elixir-lang.org")}>hello</.link>

<.link href="/the_world" method="delete" data-confirm="Really?">delete</.link>

JavaScript dependency

In order to support links where :method is not "get" or use the above data attributes, Phoenix.HTML relies on JavaScript. You can load priv/static/phoenix_html.js into your build tool.

Data attributes

Data attributes are added as a keyword list passed to the data key. The following data attributes are supported:

• data-confirm - shows a confirmation prompt before generating and submitting the form when :method is not "get".

Overriding the default confirm behaviour

phoenix_html.js does trigger a custom event phoenix.link.click on the clicked DOM element when a click happened. This allows you to intercept the event on its way bubbling up to window and do your own custom logic to enhance or replace how the data-confirm attribute is handled. You could for example replace the browsers confirm() behavior with a custom javascript implementation:

// listen on document.body, so it's executed before the default of
// phoenix_html, which is listening on the window object
document.body.addEventListener('phoenix.link.click', function (e) {
  // Prevent default implementation
  e.stopPropagation();
  // Introduce alternative implementation
  var message = e.target.getAttribute("data-confirm");
  if(!message){ return true; }
  vex.dialog.confirm({
    message: message,
    callback: function (value) {
      if (value == false) { e.preventDefault(); }
    }
  })
}, false);

Or you could attach your own custom behavior.

window.addEventListener('phoenix.link.click', function (e) {
  // Introduce custom behaviour
  var message = e.target.getAttribute("data-prompt");
  var answer = e.target.getAttribute("data-prompt-answer");
  if(message && answer && (answer != window.prompt(message))) {
    e.preventDefault();
  }
}, false);

The latter could also be bound to any click event, but this way you can be sure your custom code is only executed when the code of phoenix_html.js is run.

CSRF Protection

By default, CSRF tokens are generated through Plug.CSRFProtection.

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.

Attributes

• id (:string) (required) - A unique identifier for the LiveComponent. Note the id won't necessarily be used as the DOM id. That is up to the component to decide.

• module (:atom) (required) - The LiveComponent module to render.

Any additional attributes provided will be passed to the LiveComponent as a map of assigns. See Phoenix.LiveComponent for more information.

Examples

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

Builds a file input tag for a LiveView upload.

Attributes

• upload (Phoenix.LiveView.UploadConfig) (required) - The Phoenix.LiveView.UploadConfig struct.
• accept (:string) - the optional override for the accept attribute. Defaults to :accept specified by allow_upload.
• Global attributes are accepted. Supports all globals plus: ["webkitdirectory", "required", "disabled", "capture", "form"].

Drag and Drop

Drag and drop is supported by annotating the droppable container with a phx-drop-target attribute pointing to the UploadConfig 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 upload={@uploads.avatar} />
</div>

Examples

Rendering a file input:

<.live_file_input upload={@uploads.avatar} />

Rendering a file input with a label:

<label for={@uploads.avatar.ref}>Avatar</label>
<.live_file_input upload={@uploads.avatar} />

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

Attributes

• entry (Phoenix.LiveView.UploadEntry) (required) - The Phoenix.LiveView.UploadEntry struct.
• id (:string) - the id of the img tag. Derived by default from the entry ref, but can be overridden as needed if you need to render a preview of the same entry multiple times on the same page. Defaults to nil.
• Global attributes are accepted.

Examples

<%= for entry <- @uploads.avatar.entries do %>
  <.live_img_preview entry={entry} width="75" />
<% end %>

When you need to use it multiple times, make sure that they have distinct ids

<%= for entry <- @uploads.avatar.entries do %>
  <.live_img_preview entry={entry} width="75" />
<% end %>

<%= for entry <- @uploads.avatar.entries do %>
  <.live_img_preview id={"modal-#{entry.ref}"} entry={entry} width="500" />
<% end %>

Renders a title with automatic prefix/suffix on @page_title updates.

Attributes

• prefix (:string) - A prefix added before the content of inner_block. Defaults to nil.
• suffix (:string) - A suffix added after the content of inner_block. Defaults to nil.

Slots

• inner_block (required) - Content rendered inside the title tag.

Examples

<.live_title prefix="MyApp – ">
  <%= assigns[:page_title] || "Welcome" %>
</.live_title>

<.live_title suffix="- MyApp">
  <%= assigns[:page_title] || "Welcome" %>
</.live_title>