View components, presenters and Phlex

Kaksha shows a fee badge on 14 screens: paid, pending, overdue, each with a colour and sometimes a student’s name. As a partial, one misspelt local makes the name vanish without an error, and the only way to see every state is to click through the app. The runs on this page take that one badge through four shapes Rails apps use: a partial, a presenter, a ViewComponent with three tests and four previews, and a Phlex class, and then put a name with a script element through each of them.

By the end you can tell when a partial has outgrown its file, move formatting into a presenter, build and test a component, compare it with Phlex, and spot the one line in each tool that would print markup unescaped.

A partial’s locals are a contract nobody checks

Here is the badge as a partial. Its locals are documented in a comment, and the optional name is read with defined?, the usual way to make a local optional:

<%# app/views/shared/_fee_status_badge.html.erb
   A partial that shows a coloured badge for a student's fee status.
   Locals: status ("paid", "pending", "overdue"), student_name (optional) %>
<% colors = { "paid" => "green", "pending" => "orange", "overdue" => "red" } %>
<% labels = { "paid" => "Paid", "pending" => "Pending", "overdue" => "Overdue" } %>
<span class="badge badge-<%= colors.fetch(status, "gray") %>">
  <%= labels.fetch(status, status.capitalize) %>
  <% if defined?(student_name) && student_name %>
    for <%= student_name %>
  <% end %>
</span>

Nothing checks that comment. A caller that writes studentname: instead of student_name: gets a badge without the name and no error: the run in the ViewComponent section below shows exactly that. The colours and labels are rebuilt on every render inside the template, and testing the badge means rendering a page around it. None of this is wrong for a small partial; it becomes a cost when the partial is shared and its states multiply.

The first sign has a fix inside ERB itself: the strict-locals comment from the ERB lesson, <%# locals: (status:, student_name: nil) -%>, turns a misspelt local into an error. The other three are what presenters and components address.

A presenter moves formatting into plain Ruby

A presenterpresenter: A plain Ruby object that wraps one record and answers the questions a view asks about it, such as a date in local time or a fee in rupees, returning strings so the template only prints them. is a plain Ruby object that wraps a record and answers the questions a view asks: the start date in the reader’s time zone, the fee formatted for its market. The template then only prints what the presenter returns. This one uses Active Support’s own number helper with the locale grouping pattern the Rails API documents:

# A presenter: a plain Ruby object that formats a record for display, so the template only prints.
# It needs no Rails app, no request and no database, which is why it can be checked this quickly.
require "active_support"
require "active_support/number_helper"
require "active_support/core_ext/time"

Batch = Data.define(:name, :starts_at, :fee_paise)

class BatchPresenter
  # Indian grouping (12,50,000): the pattern the Rails API gives for number_to_delimited.
  LAKH_GROUPS = /(\d+?)(?=(\d\d)+(\d)(?!\d))/

  def initialize(batch)
    @batch = batch
  end

  def name = @batch.name

  def starts_on
    @batch.starts_at.in_time_zone("Asia/Kolkata").strftime("%-d %B %Y, %-I:%M %p IST")
  end

  def fee
    rupees = ActiveSupport::NumberHelper.number_to_delimited(@batch.fee_paise / 100, delimiter_pattern: LAKH_GROUPS)
    "₹#{rupees}"
  end
end

batches = [
  Batch.new("Data Science A1", Time.utc(2031, 5, 15, 3, 30), 125_000_00),
  Batch.new("Full-stack web, weekends", Time.utc(2031, 6, 1, 4, 0), 1_250_000_00),
  Batch.new("Spoken English trial", Time.utc(2031, 6, 7, 12, 30), 950_00),
]

batches.map { BatchPresenter.new(_1) }.each do |p|
  puts "#{p.name.ljust(25)} #{p.starts_on.ljust(27)} #{p.fee}"
end

Data Science A1           15 May 2031, 9:00 AM IST    ₹1,25,000
Full-stack web, weekends  1 June 2031, 9:30 AM IST    ₹12,50,000
Spoken English trial      7 June 2031, 6:00 PM IST    ₹950

Three batches, three formats checked at once, with no Rails app, no request and no database: a UTC time became a local start time and each fee got its digits grouped for its market. A presenter returns strings, never markup, so it says nothing about which tag or colour the badge gets; it fits when formatting is the pain and the template is still small.

The split between what the value says and what the markup is runs through every tool in this lesson, so it is worth stating once as a rule.

A ViewComponent is a class, a template and its arguments

ViewComponentViewComponent: A gem that turns a piece of view into a Ruby class with its template beside it: initialize declares the arguments, and the component can be rendered, tested with render_inline and previewed on its own. turns the partial into a Ruby class that inherits from ViewComponent::Base, with its template in a file beside it. The class’s initialize takes the arguments, and the methods it defines are what the template calls:

# app/components/fee_status_badge_component.rb
# A ViewComponent that shows a coloured badge for a student's fee status.
class FeeStatusBadgeComponent < ViewComponent::Base
  COLORS = { "paid" => "green", "pending" => "orange", "overdue" => "red" }.freeze
  LABELS = { "paid" => "Paid", "pending" => "Pending", "overdue" => "Overdue" }.freeze

  def initialize(status:, student_name: nil)
    @status = status
    @student_name = student_name
  end

  def color
    COLORS.fetch(@status, "gray")
  end

  def label
    LABELS.fetch(@status, @status.capitalize)
  end
end

<span class="badge badge-<%= color %>">
  <%= label %>
  <% if @student_name %>
    for <%= @student_name %>
  <% end %>
</span>

Step through what one render of it does, from the call to the HTML it hands back:

This run renders the badge as the partial, the component and the Phlex class of a later section, then passes the same typo to the partial and to the component, and finally asks for the component’s previews:

require_relative "session"

# The Kaksha app beside this folder: a default `rails new` (Rails 8.1.4) plus view_component 4.16.0 and phlex-rails 2.4.0.
Dir.chdir File.expand_path("../kaksha_vc", __dir__)

Session.run(<<~'SH')
  # The same badge as a partial, a ViewComponent and a Phlex class, then one typo:
  bin/rails runner ../render_badges.rb
SH

# The same badge as a partial, a ViewComponent and a Phlex class, then one typo:
$ bin/rails runner ../render_badges.rb
== The partial: render "shared/fee_status_badge", status: "overdue", student_name: "Asha"
<!-- BEGIN app/views/shared/_fee_status_badge.html.erb
--><span class="badge badge-red">
  Overdue
    for Asha
</span>
<!-- END app/views/shared/_fee_status_badge.html.erb -->

== The ViewComponent: render FeeStatusBadgeComponent.new(status: "overdue", student_name: "Asha")
<!-- BEGIN app/components/fee_status_badge_component.html.erb
--><span class="badge badge-red">
  Overdue
    for Asha
</span>
<!-- END app/components/fee_status_badge_component.html.erb -->

== The Phlex class: render FeeStatusBadge.new(status: "overdue", student_name: "Asha")
<span class="badge badge-red">Overdue for Asha</span>

== A typo, studentname instead of student_name, passed to the partial
<!-- BEGIN app/views/shared/_fee_status_badge.html.erb
--><span class="badge badge-red">
  Overdue
</span>
<!-- END app/views/shared/_fee_status_badge.html.erb -->

== The same typo passed to the component
ArgumentError: unknown keyword: :studentname

== GET /rails/view_components (the list of previews)
200: /rails/view_components/fee_status_badge_component/overdue, /rails/view_components/fee_status_badge_component/paid, /rails/view_components/fee_status_badge_component/pending, /rails/view_components/fee_status_badge_component/unknown_status

== GET /rails/view_components/fee_status_badge_component/unknown_status
200: <span class="badge badge-gray"> Waived </span>

The partial and the component produce the same span, each wrapped in development in BEGIN and END comments that name its file. The typo is where they part: the partial renders “Overdue” with no name, while the component raises ArgumentError: unknown keyword: :studentname before anything is drawn.

Tests and previews need no page around the component

Because a component is an object with its own arguments, a test can render it alone. ViewComponent::TestCase provides render_inline, which returns the HTML as a Nokogiri fragment, and, when Capybara is in the bundle, lets the test use assert_selector and assert_text on it. One test per state:

require "test_helper"

# test/components/fee_status_badge_component_test.rb: one test per state of the badge. render_inline renders the
# component with no request and no browser; assert_selector and assert_text read the HTML it produced.
class FeeStatusBadgeComponentTest < ViewComponent::TestCase
  def test_overdue_is_red_and_names_the_student
    render_inline(FeeStatusBadgeComponent.new(status: "overdue", student_name: "Ravi"))

    assert_selector "span.badge.badge-red", text: "Overdue"
    assert_text "for Ravi"
  end

  def test_an_unknown_status_is_gray
    render_inline(FeeStatusBadgeComponent.new(status: "waived"))

    assert_selector "span.badge.badge-gray", text: "Waived"
  end

  def test_a_name_with_markup_stays_text
    render_inline(FeeStatusBadgeComponent.new(status: "paid", student_name: "<b>Asha</b>"))

    assert_no_selector "b"
    assert_text "for <b>Asha</b>"
  end
end

require_relative "session"

# The Kaksha app beside this folder: a default `rails new` (Rails 8.1.4) plus view_component 4.16.0 and phlex-rails 2.4.0.
Dir.chdir File.expand_path("../kaksha_vc", __dir__)

Session.run(<<~'SH')
  # The component test, run like every other test of the app:
  bin/rails test test/components/fee_status_badge_component_test.rb
SH

# The component test, run like every other test of the app:
$ bin/rails test test/components/fee_status_badge_component_test.rb
Running 3 tests in a single process (parallelization threshold is 50)
Run options: --seed …

# Running:

...

Finished in …s, … runs/s, … assertions/s.
3 runs, 5 assertions, 0 failures, 0 errors, 0 skips

Three runs and five assertions passed with no controller, route or browser involved, including the check that a name with a <b> element stays text. Previews show the same states to people. A class in test/components/previews with one method per state gives each its own page in development:

# test/components/previews/fee_status_badge_component_preview.rb: every state of the badge, one page each, at
# /rails/view_components/fee_status_badge_component/<method> while the app runs in development.
class FeeStatusBadgeComponentPreview < ViewComponent::Preview
  def paid = render(FeeStatusBadgeComponent.new(status: "paid", student_name: "Asha"))
  def pending = render(FeeStatusBadgeComponent.new(status: "pending", student_name: "Asha"))
  def overdue = render(FeeStatusBadgeComponent.new(status: "overdue", student_name: "Asha"))
  def unknown_status = render(FeeStatusBadgeComponent.new(status: "waived"))
end

The end of the badge run above asked for them: /rails/view_components listed four pages, one per method, and the unknown_status page answered 200 with a gray “Waived” badge. Lookbook, a separate gem, builds a browsable gallery from the same preview classes and also supports Phlex.

Phlex writes the same badge in Ruby

PhlexPhlex: A Ruby gem for views written as Ruby classes: a view_template method calls one method per HTML element and escapes text written with plain; phlex-rails lets Rails render such a class. drops the template file: the whole view is a Ruby class whose view_template method calls one method per HTML element, span(class: …) { … }, and plain for text:

# app/components/fee_status_badge.rb
# A Phlex component that shows a coloured badge for a student's fee status.
class FeeStatusBadge < Phlex::HTML
  COLORS = { "paid" => "green", "pending" => "orange", "overdue" => "red" }.freeze
  LABELS = { "paid" => "Paid", "pending" => "Pending", "overdue" => "Overdue" }.freeze

  def initialize(status:, student_name: nil)
    @status = status
    @student_name = student_name
  end

  def view_template
    span(class: "badge badge-#{color}") do
      plain label
      if @student_name
        plain " for "
        plain @student_name
      end
    end
  end

  private

  def color = COLORS.fetch(@status, "gray")
  def label = LABELS.fetch(@status, @status.capitalize)
end

In the badge run, Phlex printed <span class="badge badge-red">Overdue for Asha</span> on one line and without the annotation comments, because it builds the HTML itself instead of going through an ERB template. The phlex-rails gem lets render take a Phlex object anywhere a partial or a component would go. The three shapes compare like this:

Escaping still applies, and each tool has one way around it

A component is still a template, so the rules of the ERB lesson hold: output is escaped unless something marks it safe. This run gives the badge a student name that carries a script element and counts the script elements that reached the HTML, first through each tool’s normal output and then through each tool’s explicit opt-out, shown so you can recognise it in code you own:

require_relative "session"

# The Kaksha app beside this folder: a default `rails new` (Rails 8.1.4) plus view_component 4.16.0 and phlex-rails 2.4.0.
Dir.chdir File.expand_path("../kaksha_vc", __dir__)

Session.run(<<~'SH')
  # One name with a script element, through each tool and each tool's opt-out:
  bin/rails runner ../escaping_badges.rb
SH

# One name with a script element, through each tool and each tool's opt-out:
$ bin/rails runner ../escaping_badges.rb
The default output of each tool:
  PASS  partial, <%= student_name %>: 0 script elements
  PASS  ViewComponent, <%= @student_name %>: 0 script elements
  PASS  Phlex, plain @student_name: 0 script elements

The explicit opt-outs (never for user text):
  FAIL  partial, <%= raw student_name %>: 1 script element
  FAIL  ViewComponent, given NAME.html_safe: 1 script element
  FAIL  Phlex, raw(safe(@html)): 1 script element
  ----  Phlex, raw(@html) with a plain String: Phlex::ArgumentError: You passed an unsafe object to `raw`.

All three normal paths printed 0 script elements: <%= %> in the partial and in the component template, and plain in Phlex, all escape. Each opt-out printed 1: raw in a partial, a string marked html_safe before it reaches a component, and raw(safe(…)) in Phlex. Phlex is the strictest of the three: raw with a plain string raised Phlex::ArgumentError, so markup can only get through when someone wrote safe on purpose.

Practise

Every question below comes from the runs on this page: the presenter’s three batches, the typo that one tool ignored and the other refused, the three tests and four previews, Phlex’s one-line span, and the script elements counted in each tool. Answer one and its explanation opens at once.

Interview questions

Warm-up: when would you use a presenter instead of a helper?

When the formatting rule belongs to one kind of record and deserves its own tests. A helper is a module mixed into every view, so its methods take the record as an argument and grow into a long shared list. A presenter wraps one record and answers its display questions, such as a fee formatted for its market or the start time in the reader’s zone, as plain Ruby that runs without a request; the lesson’s presenter formatted three batches with no app running. A helper still suits a small, general piece of markup used everywhere, like a link with an icon. A presenter returns strings, never markup, so the tags stay in the template or component.

Warm-up: what does ViewComponent’s render_inline return, and what can a test do with it?

It renders the component on its own, with no request, controller or browser, and returns the HTML as a Nokogiri fragment. When Capybara is in the bundle, as it is in a new Rails app, ViewComponent::TestCase also lets the test call assert_selector and assert_text on that HTML, so a test can check the span’s class, its text and that a name with markup stayed text. In the lesson’s run, three such tests with five assertions passed, one for each state of the badge.

Two questions in the module bank go further than this page: escaping inside components, and deciding when a team should adopt them. Work out your own answer first, then open the model answer.

Key takeaways

• A partial’s locals are checked by nothing unless it declares strict locals, so a misspelt local silently disappears, and every state of it is tested only through a whole page.
• A presenter is plain Ruby that formats one record for display, testable without an app, and it returns strings, never markup.
• A ViewComponent is a class with its template beside it: initialize checks the arguments, the template runs with the component as self, and render_inline tests and preview classes show every state on its own.
• Phlex builds the same HTML from Ruby methods in one class, and phlex-rails lets render take it like a partial or a component.
• All three escape output by default, and each has one explicit opt-out (raw, html_safe, raw(safe(…))) that must never carry text a person typed.