Starter Guide for HEEx Templates

The HTML EEx templates is the built-in templating engine for Phoenix framework. This reference is helpful for people familiar with templating languages like Nunjucks or Jinja.

We’ll be covering the following:

Using Phoenix LiveView, we can render a view either by defining render/1 function, or placing template code in a file.

For simplicity, let’s assume the module defines render/1 function, which returns a HEEx template, defined using a ~H sigil.

def render(assigns) do
  ~H"""
  template content here
  """
end

The assigns parameter can be either an Elixir Keyword or a Map, accessible within template code.

Variables

<p><%= @name %></p>

Accessing the value using @ when the value is undefined ends up in an exception. So, in case you need to provide a fallback in the template, you have to access the value through assigns, and supply a fallback.

<p><%= assigns[:name] || "Untitled" %></p>

HEEx templates comes with HTML validation and shorter interpolation syntax of attributes. You can provide a value to HTML attributes using key={value} syntax. HEEx will remove the attribute from rendered HTML when the value is false.

<div data-user-state={@state}> ... </div>
<div class={@classes}>
  <p>Hello <%= @username %></p>
</div>

…will magically render to:

<div class="highlight bold">
  <p>Hello joe</p>
</div>

Logic

If… else…

<%= if @state == "new" do %>
  <p>Newly joined.</p>
<% end %>
<%= if @state == "new" do %>
  <p>Newly joined.</p>
<% else %>
  <p>Veteran.</p>
<% end %>

Loop

Consider a user data passed down through assigns as:

assign(conn, :users,
    users: [
      %{name: 'Jamie Houston', age: 20},
      %{name: 'Barbara John', age: 23}
    ]
  )

…you can loop over the array using:

<%= for user <- @users do %>
  <div class="name"><%= user.name %></div>
  <div class="age"><%= user.age %></div>
<% end %>

Include

To replicate the function of include tag from Nunjucks and Jinja, to render another template file, you can use render/2 within templates

<%= render "another-template.html", assigns %>

Raw HTML

HEEx, by default, escape all HTML content. You can use raw to allow unescaped HTML.

<%= raw "<hello/>" %>

Comments

<%# This is a comment. %>

<%# And,
    ...this is a multiline comment.
%>

References