Format HEEx templates from .heex files or ~H sigils.

This is a mix format plugin.

Note: The HEEx HTML Formatter requires Elixir v1.13.4 or later.

Setup

Add it as plugin to your .formatter.exs file and make sure to put theheex extension in the inputs option.

[
  plugins: [Phoenix.LiveView.HTMLFormatter],
  inputs: ["*.{heex,ex,exs}", "priv/*/seeds.exs", "{config,lib,test}/**/*.{heex,ex,exs}"],
  # ...
]

For umbrella projects

In umbrella projects you must also change two files at the umbrella root, add :phoenix_live_view to your deps in the mix.exs file and add plugins: [Phoenix.LiveView.HTMLFormatter] in the .formatter.exs file. This is because the formatter does not attempt to load the dependencies of all children applications.

Editor support

Most editors that support mix format integration should automatically format .heex and ~H templates. Other editors may require custom integration or even provide additional functionality. Here are some reference posts:

• Formatting HEEx templates in VS Code

Options

• :line_length - The Elixir formatter defaults to a maximum line length of 98 characters, which can be overwritten with the :line_length option in your .formatter.exs file.

• :heex_line_length - change the line length only for the HEEx formatter.

  [
    # ...omitted
    heex_line_length: 300
  ]

Formatting

This formatter tries to be as consistent as possible with the Elixir formatter.

Given HTML like this:

  <section><h1>   <b><%= @user.name %></b></h1></section>

It will be formatted as:

<section>
  <h1><b><%= @user.name %></b></h1>
</section>

A block element will go to the next line, while inline elements will be kept in the current line as long as they fit within the configured line length.

The following links list all block and inline elements.

• https://developer.mozilla.org/en-US/docs/Web/HTML/Block-level_elements#elements
• https://developer.mozilla.org/en-US/docs/Web/HTML/Inline_elements#list_of_inline_elements

It will also keep inline elements in their own lines if you intentionally write them this way:

<section>
  <h1>
    <b><%= @user.name %></b>
  </h1>
</section>

This formatter will place all attributes on their own lines when they do not all fit in the current line. Therefore this:

<section id="user-section-id" class="sm:focus:block flex w-full p-3" phx-click="send-event">
  <p>Hi</p>
</section>

Will be formatted to:

<section
  id="user-section-id"
  class="sm:focus:block flex w-full p-3"
  phx-click="send-event"
>
  <p>Hi</p>
</section>

This formatter does not format Elixir expressions with do...end. The content within it will be formatted accordingly though. Therefore, the given input:

<%= live_redirect(
       to: "/my/path",
  class: "my class"
) do %>
        My Link
<% end %>

Will be formatted to

<%= live_redirect(
       to: "/my/path",
  class: "my class"
) do %>
  My Link
<% end %>

Note that only the text My Link has been formatted.

Intentional new lines

The formatter will keep intentional new lines. However, the formatter will always keep a maximum of one line break in case you have multiple ones:

<p>
  text


  text
</p>

Will be formatted to:

<p>
  text

  text
</p>

Inline elements

We don't format inline elements when there is a text without whitespace before or after the element. Otherwise it would compromise what is rendered adding an extra whitespace.

This is the list of inline elements:

https://developer.mozilla.org/en-US/docs/Web/HTML/Inline_elements#list_of_inline_elements

Skip formatting

In case you don't want part of your HTML to be automatically formatted. You can use the special phx-no-format attribute so that the formatter will skip the element block. Note that this attribute will not be rendered.

Therefore:

<.textarea phx-no-format>My content</.textarea>

Will be kept as is your code editor, but rendered as:

<textarea>My content</textarea>

Comments

Inline comments <%# comment %> are deprecated and the formatter will discard them silently from templates. You must change them to the multi-line comment <%!-- comment --%> on Elixir v1.14+ or introduce a space between <% and #, such as <% # comment %>.