Phoenix Views and Templates

Phoenix uses HEEx (HTML+EEx) templates for rendering dynamic HTML content. HEEx provides compile-time validation, security through automatic escaping, and a component-based architecture. Views in Phoenix are modules that organize template rendering logic and house reusable function components.

View Module Structure

Phoenix view modules use the

embed_templates

macro to load HEEx templates from a directory:

elixir

defmodule HelloWeb.HelloHTML do
  use HelloWeb, :html

  embed_templates "hello_html/*"
end

This automatically creates functions for each

.html.heex

file in the

hello_html/

directory.

HEEx Templates

Basic Template Structure

HEEx templates combine HTML with embedded Elixir expressions:

heex

<section>
  <h2>Hello World, from Phoenix!</h2>
</section>

Interpolating Dynamic Content

Use

<%= ... %>

to interpolate Elixir expressions into HTML:

heex

<section>
  <h2>Hello World, from <%= @messenger %>!</h2>
</section>

The

symbol accesses assigns passed from the controller.

Multi-line Expressions

For expressions without output, omit the

heex

<% # This is a comment %>
<% user_name = String.upcase(@user.name) %>
<p>Welcome, <%= user_name %>!</p>

Working with Assigns

Assigns are key-value pairs passed from controllers to templates:

elixir

# Controller
def show(conn, %{"messenger" => messenger}) do
  render(conn, :show, messenger: messenger, receiver: "Dweezil")
end

heex

<!-- Template -->
<section>
  <h2>Hello <%= @receiver %>, from <%= @messenger %>!</h2>
</section>

All assigns are accessed with the

prefix in templates.

Conditional Rendering

Using if/else

HEEx supports conditional rendering with

if/else

blocks:

heex

<%= if some_condition? do %>
  <p>Some condition is true for user: <%= @username %></p>
<% else %>
  <p>Some condition is false for user: <%= @username %></p>
<% end %>

Using unless

For negative conditions:

heex

<%= unless @user.premium do %>
  <div class="upgrade-banner">
    Upgrade to premium for more features!
  </div>
<% end %>

Pattern Matching with case

For multiple conditions:

heex

<%= case @status do %>
  <% :pending -> %>
    <span class="badge badge-warning">Pending</span>
  <% :approved -> %>
    <span class="badge badge-success">Approved</span>
  <% :rejected -> %>
    <span class="badge badge-danger">Rejected</span>
<% end %>

Looping and Iteration

For Comprehensions

Generate dynamic lists using

for

heex

<table>
  <tr>
    <th>Number</th>
    <th>Power</th>
  </tr>
  <%= for number <- 1..10 do %>
    <tr>
      <td><%= number %></td>
      <td><%= number * number %></td>
    </tr>
  <% end %>
</table>

Iterating Over Collections

Loop through lists or maps:

heex

<ul>
  <%= for post <- @posts do %>
    <li>
      <h3><%= post.title %></h3>
      <p><%= post.excerpt %></p>
    </li>
  <% end %>
</ul>

Shorthand :for Attribute

HEEx provides cleaner syntax for simple iterations:

heex

<ul>
  <li :for={item <- @items}><%= item.name %></li>
</ul>

Accessing Index

Get the iteration index with

Enum.with_index/2

heex

<%= for {item, index} <- Enum.with_index(@items) do %>
  <div class="item-<%= index %>">
    <%= item.name %>
  </div>
<% end %>

Function Components

Function components are reusable UI elements defined as Elixir functions that return HEEx templates.

Defining Function Components

Use the

attr

macro to declare attributes and the

~H

sigil for the template:

elixir

defmodule HelloWeb.HelloHTML do
  use HelloWeb, :html

  embed_templates "hello_html/*"

  attr :messenger, :string, required: true

  def greet(assigns) do
    ~H"""
    <h2>Hello World, from <%= @messenger %>!</h2>
    """
  end
end

Using Function Components

Invoke components with the

<.component_name />

syntax:

heex

<section>
  <.greet messenger={@messenger} />
</section>

Optional Attributes with Defaults

Define optional attributes with default values:

elixir

attr :messenger, :string, default: nil
attr :class, :string, default: "greeting"

def greet(assigns) do
  ~H"""
  <h2 class={@class}>
    Hello World<%= if @messenger, do: ", from #{@messenger}" %>!
  </h2>
  """
end

Multiple Attribute Types

Components can accept various attribute types:

elixir

attr :title, :string, required: true
attr :count, :integer, default: 0
attr :active, :boolean, default: false
attr :user, :map, required: true
attr :items, :list, default: []

def card(assigns) do
  ~H"""
  <div class={"card" <> if @active, do: " active", else: ""}>
    <h3><%= @title %></h3>
    <p>Count: <%= @count %></p>
    <p>User: <%= @user.name %></p>
    <ul>
      <li :for={item <- @items}><%= item %></li>
    </ul>
  </div>
  """
end

Components with Computed Values

Use

assign/2

to compute values within components:

elixir

attr :x, :integer, required: true
attr :y, :integer, required: true
attr :title, :string, required: true

def sum_component(assigns) do
  assigns = assign(assigns, sum: assigns.x + assigns.y)

  ~H"""
  <h1><%= @title %></h1>
  <p>Sum: <%= @sum %></p>
  """
end

Slots

Slots allow components to accept blocks of content, enabling powerful composition patterns.

Defining and Using Slots

Define a slot and render it:

elixir

slot :inner_block, required: true

def card(assigns) do
  ~H"""
  <div class="card">
    <%= render_slot(@inner_block) %>
  </div>
  """
end

Use the component with content:

heex

<.card>
  <h2>Card Title</h2>
  <p>Card content goes here</p>
</.card>

Named Slots

Components can have multiple named slots:

elixir

slot :header, required: true
slot :body, required: true
slot :footer

def panel(assigns) do
  ~H"""
  <div class="panel">
    <div class="panel-header">
      <%= render_slot(@header) %>
    </div>
    <div class="panel-body">
      <%= render_slot(@body) %>
    </div>
    <%= if @footer != [] do %>
      <div class="panel-footer">
        <%= render_slot(@footer) %>
      </div>
    <% end %>
  </div>
  """
end

Usage:

heex

<.panel>
  <:header>
    <h2>Panel Title</h2>
  </:header>
  <:body>
    <p>Panel content</p>
  </:body>
  <:footer>
    <button>Close</button>
  </:footer>
</.panel>

Slots with Attributes

Slots can accept attributes for more dynamic rendering:

elixir

slot :item, required: true do
  attr :title, :string, required: true
  attr :highlighted, :boolean, default: false
end

def list(assigns) do
  ~H"""
  <ul>
    <%= for item <- @item do %>
      <li class={if item.highlighted, do: "highlight"}>
        <%= item.title %>: <%= render_slot(item) %>
      </li>
    <% end %>
  </ul>
  """
end

Rendering Child Templates

Rendering Other Templates

Include child templates within a parent:

heex

<%= render("child_template.html", assigns) %>

Rendering Components from Other Modules

Call components from different modules:

heex

<MyApp.Components.button text="Click me" />

Or with aliasing:

elixir

alias MyApp.Components

# In template:
<Components.button text="Click me" />

Layout Templates

Using Layouts

Layouts wrap rendered templates. Configure the layout in the controller:

elixir

def controller do
  quote do
    use Phoenix.Controller,
      formats: [:html, :json],
      layouts: [html: HelloWeb.Layouts]
    ...
  end
end

Root Layout

The root layout includes the

@inner_content

placeholder:

heex

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8"/>
    <title>My App</title>
  </head>
  <body>
    <%= @inner_content %>
  </body>
</html>

App Layout Component

Nest layouts using components:

heex

<Layouts.app flash={@flash}>
  <section>
    <h2>Hello World, from <%= @messenger %>!</h2>
  </section>
</Layouts.app>

Disabling Layouts

Render without a layout:

elixir

def home(conn, _params) do
  render(conn, :home, layout: false)
end

LiveView Integration

Delegating to Phoenix Views

LiveView can delegate rendering to existing view modules:

elixir

defmodule AppWeb.ThermostatLive do
  use Phoenix.LiveView

  def render(assigns) do
    Phoenix.View.render(AppWeb.PageView, "page.html", assigns)
  end
end

Embedding LiveView in Templates

Render LiveView components within static templates:

heex

<h1>Temperature Control</h1>
<%= live_render(@conn, AppWeb.ThermostatLive) %>

Function Components in LiveView

Define and use function components in LiveView:

elixir

def weather_greeting(assigns) do
  ~H"""
  <div title="My div" class={@class}>
    <p>Hello <%= @name %></p>
    <MyApp.Weather.city name="Kraków"/>
  </div>
  """
end

Testing Views

Testing View Rendering

Test views directly using

render_to_string/4

elixir

defmodule HelloWeb.ErrorHTMLTest do
  use HelloWeb.ConnCase, async: true

  import Phoenix.Template

  test "renders 404.html" do
    assert render_to_string(HelloWeb.ErrorHTML, "404", "html", []) == "Not Found"
  end

  test "renders 500.html" do
    assert render_to_string(HelloWeb.ErrorHTML, "500", "html", []) == "Internal Server Error"
  end
end

Testing Function Components

Test components in isolation:

elixir

import Phoenix.LiveViewTest

test "renders greet component" do
  assigns = %{messenger: "Phoenix"}
  html = rendered_to_string(~H"""
  <HelloWeb.HelloHTML.greet messenger={@messenger} />
  """)
  assert html =~ "Hello World, from Phoenix!"
end

When to Use This Skill

Use this skill when you need to:

Create dynamic HTML templates for Phoenix applications
Build reusable function components for consistent UI elements
Implement conditional rendering based on application state
Render lists and tables with dynamic data
Create complex layouts with nested components and slots
Integrate LiveView components with static templates
Test view rendering logic and component behavior
Build accessible and semantic HTML structures
Implement responsive designs with dynamic classes
Create forms with validation feedback
Display flash messages and user notifications
Render navigation menus and breadcrumbs
Build card-based layouts and dashboards
Implement pagination controls

Best Practices

Use function components - Encapsulate reusable UI patterns in components
Declare attributes explicitly - Use
```
attr
```
macro for all component attributes
Provide default values - Make components flexible with sensible defaults
Use semantic HTML - Choose appropriate HTML elements for accessibility
Leverage slots - Use slots for flexible component composition
Keep templates simple - Move complex logic to controller or context
Use :for shorthand - Prefer
```
:for
```
attribute for simple iterations
Avoid inline styles - Use CSS classes for styling
Test components - Write tests for complex component logic
Document components - Add docstrings to explain component usage
Use verified routes - Always use
```
~p
```
sigil in templates
Escape user content - Let HEEx handle escaping automatically
Optimize renders - Minimize computation in template code
Use descriptive names - Name components and attributes clearly
Follow conventions - Stick to Phoenix naming patterns

Common Pitfalls

Putting logic in templates - Complex business logic belongs in contexts, not views
Not escaping HTML - Using
```
raw/1
```
without sanitizing user input
Deeply nested templates - Creating hard-to-maintain template hierarchies
Missing attribute declarations - Not using
```
attr
```
macro for component attributes
Overusing inline conditionals - Making templates hard to read
Not using components - Repeating markup instead of extracting components
Forgetting slot checks - Not checking if optional slots are provided
Mixing concerns - Combining data fetching with presentation logic
Large template files - Creating monolithic templates instead of components
Inconsistent formatting - Not following HEEx formatting conventions
Using EEx instead of HEEx - Missing compile-time validation benefits
Ignoring accessibility - Not adding ARIA labels and semantic markup
Hardcoding values - Not using assigns for configurable content
Not testing edge cases - Missing nil checks and empty state handling
Excessive nesting - Creating deeply nested component trees

phoenix-views-templates

NPX Install

Tags

SKILL.md Content

Phoenix Views and Templates

View Module Structure

HEEx Templates

Basic Template Structure

Interpolating Dynamic Content

Multi-line Expressions

Working with Assigns

Conditional Rendering

Using if/else

Using unless

Pattern Matching with case

Looping and Iteration

For Comprehensions

Iterating Over Collections

Shorthand :for Attribute

Accessing Index

Function Components

Defining Function Components

Using Function Components

Optional Attributes with Defaults

Multiple Attribute Types

Components with Computed Values

Slots

Defining and Using Slots

Named Slots

Slots with Attributes

Rendering Child Templates

Rendering Other Templates

Rendering Components from Other Modules

Layout Templates

Using Layouts

Root Layout

App Layout Component

Disabling Layouts

LiveView Integration

Delegating to Phoenix Views

Embedding LiveView in Templates

Function Components in LiveView

Testing Views

Testing View Rendering

Testing Function Components

When to Use This Skill

Best Practices

Common Pitfalls

Resources