Generates a dynamically named HTML tag.

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

attributes

Attributes

• name (:string) (required) - The name of the tag, such as div.
• Global attributes are accepted.

slots

Slots

• inner_block

examples

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

Attributes

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

slots

Slots

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

examples

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 form struct, generally created with to_form/2, and generates the relevant form tags. It can be used either inside LiveView or outside.

examples-inside-liveview

Examples: inside LiveView

Inside LiveViews, the for={...} attribute is generally a form struct created with the to_form/1 function. to_form/1 expects either a map or an Ecto.Changeset as the source of data.

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

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

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.

If you want to show errors manually you can also set the action yourself, either directly 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.

example-outside-liveview-regular-http-requests

Example: outside LiveView (regular HTTP requests)

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)}>
  <.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

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

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.

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

  Defaults to false.

• Global attributes are accepted.

slots

Slots

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

Renders nested form inputs for associations or embeds.

attributes

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.

slots

Slots

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

examples

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

Dynamicaly adding and removing inputs is supported by rendering checkboxes for inserts and removals. Libraries such as Ecto, or custom param filtering can then inspect the paramters 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 "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 intructs 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="list[emails_sort][]" value={ef.index} />
  <.input type="text" field={ef[:email]} placeholder="email" />
  <.input type="text" field={ef[:name]} placeholder="name" />
  <label>
    <input type="checkbox" name="list[emails_drop][]" value={ef.index} class="hidden" />
    <.icon name="hero-x-mark" class="w-6 h-6 relative top-2" />
  </label>
</.inputs_for>

<label class="block cursor-pointer">
  <input type="checkbox" name="list[emails_sort][]" class="hidden" />
  add more
</label>

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

We used inputs_for to render inputs for the :emails association, which containes an email address and name input for each child. Within the nested inputs, we render a hidden 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 label containing the "delete" text and a hidden checkbox input with the name 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 checkbox is checked. Wrapping the checkbox and textual content in a label makes any clicked content within the label check and uncheck the checbox.

Finally, outside the inputs_for, we render another label with a value-less list[emails_sort][] checkbox witih accompanied "add more" text. Ecto will treat unknown sort params as new children and build a new child. We also render an empty list[emails_drop][] to ensure that all children are deleted when saving our form in the event that the user dropped all the inputs.

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

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

Attributes

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

slots

Slots

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

Generates a link for live and href navigation.

attributes

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.

slots

Slots

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

examples

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

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

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

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

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

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

Examples

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

Builds a file input tag for a LiveView upload.

attributes

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.

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

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

Attributes

• entry (Phoenix.LiveView.UploadEntry) (required) - The Phoenix.LiveView.UploadEntry struct.
• Global attributes are accepted.

examples

Examples

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

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

attributes

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

Slots

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

examples

Examples

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

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