Declares attributes for a HEEx function components.

arguments

Arguments

• name - an atom defining the name of the attribute. Note that attributes cannot define the same name as any other attributes or slots declared for the same component.

• type - an atom defining the type of the attribute.

• opts - a keyword list of options. Defaults to [].

types

Types

An attribute is declared by its name, type, and options. The following types are supported:

options

Options

• :required - marks an attribute as required. If a caller does not pass the given attribute, a compile warning is issued.

• :default - the default value for the attribute if not provided. If this option is not set and the attribute is not given, accessing the attribute will fail unless a value is explicitly set with assign_new/3.

• :examples - a non-exhaustive list of values accepted by the attribute, used for documentation purposes.

• :values - an exhaustive list of values accepted by the attributes. If a caller passes a literal not contained in this list, a compile warning is issued.

• :doc - documentation for the attribute.

compile-time-validations

Compile-Time Validations

LiveView performs some validation of attributes via the :phoenix_live_view compiler. When attributes are defined, LiveView will warn at compilation time on the caller if:

• A required attribute of a component is missing.

• An unknown attribute is given.

• You specify a literal attribute (such as value="string" or value, but not value={expr}) and the type does not match. The following types currently support literal validation: :string, :atom, :boolean, :integer, :float, :map and :list.

• You specify a literal attribute and it is not a member of the :values list.

LiveView does not perform any validation at runtime. This means the type information is mostly used for documentation and reflection purposes.

On the side of the LiveView component itself, defining attributes provides the following quality of life improvements:

• The default value of all attributes will be added to the assigns map upfront.

• Attribute documentation is generated for the component.

• Required struct types are annotated and emit compilation warnings. For example, if you specify attr :user, User, required: true and then you write @user.non_valid_field in your template, a warning will be emitted.

• Calls made to the component are tracked for reflection and validation purposes.

documentation-generation

Documentation Generation

Public function components that define attributes will have their attribute types and docs injected into the function's documentation, depending on the value of the @doc module attribute:

• if @doc is a string, the attribute docs are injected into that string. The optional placeholder [INSERT LVATTRDOCS] can be used to specify where in the string the docs are injected. Otherwise, the docs are appended to the end of the @doc string.

• if @doc is unspecified, the attribute docs are used as the default @doc string.

• if @doc is false, the attribute docs are omitted entirely.

The injected attribute docs are formatted as a markdown list:

• name (:type) (required) - attr docs. Defaults to :default.

By default, all attributes will have their types and docs injected into the function @doc string. To hide a specific attribute, you can set the value of :doc to false.

example

Example

attr :name, :string, required: true
attr :age, :integer, required: true

def celebrate(assigns) do
  ~H"""
  <p>
    Happy birthday <%= @name %>!
    You are <%= @age %> years old.
  </p>
  """
end

Embeds external template files into the module as function components.

options

Options

• :root - The root directory to embed files. Defaults to the current module's directory (__DIR__)
• :suffix - The string value to append to embedded function names. By default, function names will be the name of the template file excluding the format and engine.

A wildcard pattern may be used to select all files within a directory tree. For example, imagine a directory listing:

├── components.ex
├── pages
│   ├── about_page.html.heex
│   └── welcome_page.html.heex

Then to embed the page templates in your components.ex module:

defmodule MyAppWeb.Components do
  use Phoenix.Component

  embed_templates "pages/*"
end

Now, your module will have an about_page/1 and welcome_page/1 function component defined. Embedded templates also support declarative assigns via bodyless function definitions, for example:

defmodule MyAppWeb.Components do
  use Phoenix.Component

  embed_templates "pages/*"

  attr :name, :string, required: true
  def welcome_page(assigns)

  slot :header
  def about_page(assigns)
end

Multiple invocations of embed_templates is also supported, which can be useful if you have more than one template format. For example:

defmodule MyAppWeb.Emails do
  use Phoenix.Component

  embed_templates "emails/*.html", suffix: "_html"
  embed_templates "emails/*.text", suffix: "_text"
end

Note: this function is the same as Phoenix.Template.embed_templates/2. It is also provided here for convenience and documentation purposes. Therefore, if you want to embed templates for other formats, which are not related to Phoenix.Component, prefer to import Phoenix.Template, only: [embed_templates: 1] than this module.

The ~H sigil for writing HEEx templates inside source files.

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

• Out-of-the-box code formatting via mix format

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.

heex-extension-special-attributes

HEEx extension: special attributes

Apart from normal HTML attributes, HEEx also supports some special attributes such as :let and :for.

:let

This is used by components and slots that want to yield a value back to the caller. For an example, see how form/1 works:

<.form :let={f} for={@form} phx-change="validate" phx-submit="save">
  <.input field={f[:username]} type="text" />
  ...
</.form>

Notice how the variable f, defined by .form is used by your input component. The Phoenix.Component module has detailed documentation on how to use and implement such functionality.

:if and :for

It is a syntax sugar for <%= if .. do %> and <%= for .. do %> that can be used in regular HTML, function components, and slots.

For example in an HTML tag:

<table id="admin-table" :if={@admin?}>
  <tr :for={user <- @users}>
    <td><%= user.name %></td>
  </tr>
<table>

The snippet above will only render the table if @admin? is true, and generate a tr per user as you would expect from the collection.

:for can be used similarly in function components:

<.error :for={msg <- @errors} message={msg}/>

Which is equivalent to writing:

<%= for msg <- @errors do %>
  <.error message={msg} />
<% end %>

And :for in slots behaves the same way:

<.table id="my-table" rows={@users}>
  <:col :for={header <- @headers} :let={user}>
    <td><%= user[:header] %></td>
  </:col>
<table>

You can also combine :for and :if for tags, components, and slot to act as a filter:

<.error :for={msg <- @errors} :if={msg != nil} message={msg} />

code-formatting

Code formatting

You can automatically format HEEx templates (.heex) and ~H sigils using Phoenix.LiveView.HTMLFormatter. Please check that module for more information.

Declares a slot. See slot/3 for more information.

Declares a function component slot.

arguments

Arguments

• name - an atom defining the name of the slot. Note that slots cannot define the same name as any other slots or attributes declared for the same component.

• opts - a keyword list of options. Defaults to [].

• block - a code block containing calls to attr/3. Defaults to nil.

options

Options

• :required - marks a slot as required. If a caller does not pass a value for a required slot, a compilation warning is emitted. Otherwise, an omitted slot will default to [].

• :doc - documentation for the slot. Any slot attributes declared will have their documentation listed alongside the slot.

slot-attributes

Slot Attributes

A named slot may declare attributes by passing a block with calls to attr/3.

Unlike attributes, slot attributes cannot accept the :default option. Passing one will result in a compile warning being issued.

the-default-slot

The Default Slot

The default slot can be declared by passing :inner_block as the name of the slot.

Note that the :inner_block slot declaration cannot accept a block. Passing one will result in a compilation error.

compile-time-validations

Compile-Time Validations

LiveView performs some validation of slots via the :phoenix_live_view compiler. When slots are defined, LiveView will warn at compilation time on the caller if:

• A required slot of a component is missing.

• An unknown slot is given.

• An unknown slot attribute is given.

On the side of the function component itself, defining attributes provides the following quality of life improvements:

• Slot documentation is generated for the component.

• Calls made to the component are tracked for reflection and validation purposes.

documentation-generation

Documentation Generation

Public function components that define slots will have their docs injected into the function's documentation, depending on the value of the @doc module attribute:

• if @doc is a string, the slot docs are injected into that string. The optional placeholder [INSERT LVATTRDOCS] can be used to specify where in the string the docs are injected. Otherwise, the docs are appended to the end of the @doc string.

• if @doc is unspecified, the slot docs are used as the default @doc string.

• if @doc is false, the slot docs are omitted entirely.

The injected slot docs are formatted as a markdown list:

• name (required) - slot docs. Accepts attributes:
  • name (:type) (required) - attr docs. Defaults to :default.

By default, all slots will have their docs injected into the function @doc string. To hide a specific slot, you can set the value of :doc to false.

example

Example

slot :header
slot :inner_block, required: true
slot :footer

def modal(assigns) do
  ~H"""
  <div class="modal">
    <div class="modal-header">
      <%= render_slot(@header) || "Modal" %>
    </div>
    <div class="modal-body">
      <%= render_slot(@inner_block) %>
    </div>
    <div class="modal-footer">
      <%= render_slot(@footer) || submit_button() %>
    </div>
  </div>
  """
end

As shown in the example above, render_slot/1 returns nil when an optional slot is declared and none is given. This can be used to attach default behaviour.