phoenix-html

forest's avatarfrom forest

Critical Phoenix HTML and HEEx template guidelines that prevent common bugs and syntax errors. Use when writing Phoenix templates, HEEx files, LiveView templates, or any code using `~H` sigils. Prevents common mistakes with form handling, conditional syntax, class attributes, interpolation, and template comments that cause compilation errors or runtime bugs.

⭐4stars🔀0forks📁View on GitHub🕐Updated Dec 24, 2025

When & Why to Use This Skill

This Claude skill provides a comprehensive set of critical guidelines for writing Phoenix HTML and HEEx templates in Elixir. It ensures developers follow the latest best practices for web development, specifically focusing on HEEx syntax, modern form handling with Phoenix.Component, and proper conditional logic. By enforcing these rules, the skill prevents common compilation errors and runtime bugs, streamlining the creation of robust LiveView and Phoenix applications while ensuring code maintainability.

Use Cases

  • Developing Phoenix LiveView applications: Use these guidelines to ensure HEEx templates are syntactically correct and follow modern component patterns from the start.
  • Refactoring legacy Phoenix templates: Convert deprecated form_for and ~E sigils to modern to_form and ~H syntax to align with current framework standards.
  • Debugging template compilation errors: Apply these rules to quickly identify and fix invalid conditional structures or incorrect attribute interpolation in .heex files.
  • Standardizing Elixir codebases: Provide a consistent style guide for teams to ensure all Phoenix templates are written with uniform syntax and bug-prevention strategies.
namephoenix-html
descriptionCritical Phoenix HTML and HEEx template guidelines that prevent common bugs and syntax errors. Use when writing Phoenix templates, HEEx files, LiveView templates, or any code using `~H` sigils. Prevents common mistakes with form handling, conditional syntax, class attributes, interpolation, and template comments that cause compilation errors or runtime bugs.

Phoenix HTML/HEEx Guidelines

Template Syntax

  • Always use ~H sigils or .html.heex files. Never use ~E
  • HEEx comments use <%!-- comment --%> syntax

Forms

  • Always use Phoenix.Component.form/1 and Phoenix.Component.inputs_for/1
  • Never use deprecated Phoenix.HTML.form_for or Phoenix.HTML.inputs_for
  • Always use to_form/2 for form handling:
# In mount/handle_event:
assign(socket, form: to_form(changeset))

# In template:
<.form for={@form} id="product-form">
  <.input field={@form[:name]} />
</.form>
  • Always add unique DOM IDs to forms for testability

Conditionals

Elixir has if/else but does NOT support if/else if or if/elsif.

Never do this (invalid):

<%= if condition do %>
  ...
<% else if other_condition %>
  ...
<% end %>

Always use cond for multiple conditions:

<%= cond do %>
  <% condition1 -> %>
    ...
  <% condition2 -> %>
    ...
  <% true -> %>
    ...
<% end %>

Class Attributes

Always use list [...] syntax for class attributes:

<a class={[
  "px-2 text-white",
  @some_flag && "py-5",
  if(@other_condition, do: "border-red-500", else: "border-blue-100")
]}>Text</a>

Always wrap if expressions in parentheses inside {...}.

Never do this (invalid syntax):

<a class={
  "px-2 text-white",
  @some_flag && "py-5"
}>

Interpolation

  • Use {...} for interpolation within tag attributes and simple values in tag bodies
  • Use <%= ... %> for block constructs (if, cond, case, for) in tag bodies

Correct:

<div id={@id}>
  {@my_assign}
  <%= if @condition do %>
    {@value}
  <% end %>
</div>

Invalid (never do this):

<div id="<%= @invalid %>">
  {if @condition do}
  {end}
</div>

Iterating Collections

Always use for comprehensions:

<%= for item <- @collection do %>
  <div>{item.name}</div>
<% end %>

Never use <% Enum.each %> for template content.

Literal Curly Braces

Use phx-no-curly-interpolation for literal { or } in code snippets:

<code phx-no-curly-interpolation>
  let obj = {key: "val"}
</code>

Within annotated tags, use <%= ... %> for dynamic expressions.

App-Wide Imports

Add shared imports to my_app_web.ex's html_helpers block for availability in all LiveViews and components.