An Introduction to the ViewComponent Gem

Modern web UIs are complex. Traditional layout/template/partial techniques are not always the best fit. ViewComponent seeks to provide a better way. It's a framework for creating reusable, testable & encapsulated view components that integrate seamlessly with Rails. In this article, Abiodun Olowode shows us how to use ViewComponent to make our Rails views more manageable.

Inspired by React, ViewComponents are Ruby objects used to build markup for rendering views. ViewComponent is a framework for building re-usable, testable, and encapsulated view components in Rails. Typically, reusable views are created in Rails using partials and then rendered in different views as required, but with the introduction of the ViewComponent gem, partials can be swapped for view components, as they offer more advantages. Let's dive into what these advantages are.

When and Why should I use ViewComponents?

As stated earlier, view components are reusable and testable. Hence, they can be applied whenever a view is to be reused or benefits from being tested directly. Some of the benefits of view components, as stated in its documentation, include the following:

  • They are ~10x faster than partials.
  • They are Ruby objects; hence, their initialize method clearly defines what is required to render a view. This means that they are easier to understand and reuse in several other views. Furthermore, Ruby code’s quality standards can be enforced, thereby offering a reduced risk of bugs.
  • They can be unit tested as opposed to Rails’ traditional views, which require integration tests that also exercise routing and controller layers in addition to the view.

ViewComponent Implementation

ViewComponents are subclasses of ViewComponent::Base and live in app/components . Their names end in - Component, and they should be named for what they render and not what they accept. We can generate a view component either manually or via the component generator, but not without adding the gem to our gemfile and running a bundle install first.

gem "view_component", require: "view_component/engine"

To use the generator, run the following command:

rails generate component <Component name> <arguments needed for initialization>

For example, if we wanted to generate a component responsible for showcasing a list of in-class courses available on a learning platform, we could use this command:

rails g component Course course

We're passing the course argument to the command because we would initialize this Ruby object with the course we expect it to display, and we named it Course because it renders a course. What a coincidence!

CourseComponent Generated

As we can see above, the component and its corresponding view are created in the app/components folder, along with a test file.

ViewComponent includes template generators for the erb, haml, and slim template engines but will default to whatever template engine is specified in config.generators.template_engine. Nevertheless, you can indicate your preferred template engine using the following:

rails generate component Course course --template-engine <your template engine>

Let's proceed to create our Course model and some courses to display.

rails g model Course title:string price:decimal location:string
rails db:migrate

In our console, we can quickly create two new courses:

Course.create(title: 'The Art of Learning', price: 125.00, location: 'Denmark')
Course.create(title: 'Organizing your Time', price: 55.00, location: 'London')

The course_component.rb file is generated with the initialize method in place, as shown below.

CourseComponent Initialized

We need to create a course controller that routes us to the list of courses.

rails g controller Courses index

In our routes.rb file, we indicate our root route by adding the following:

root 'courses#index'

Now that we're all set, the next step is view creation. This is done in the already generated course_component.html.erb.

  <h2><%= @course.title %></h2>
  <h4><%=  number_to_currency(@course.price, :unit => "€") %></h4>
  <h4><%= @course.location %></h4>

In our view, we display the course title, price, and location using the @course variable, which was already defined in the initialize method of our CourseComponent. This is similar to when you create a variable in a controller method, and then it is available in a view.

Knowing how controllers work, we would be routed to the corresponding index.html.erb of our index method. Hence, this is where we render our component.

<%= render( Course.find(1))) %>

As seen above, we render a new instance of our CourseComponent by initializing it with the course we intend it to render in its view. This course becomes the @course variable made available to the course_component.html.erb file.

It is also possible to render this component directly from our controller, thereby bypassing the index file view:

class CoursesController < ApplicationController
  def index
    render( Course.find(1)))

Regardless of which method you choose, this will show up on the server:

First course displayed

Additional content can also be passed to the component in one of the following ways:

<%= render( Course.find(1))) do %>
<% end %>
<%= render( Course.find(1)).with_content("container")) %>

In our view component file, we can include the content wherever we want. In this case, we'll include it as a class by editing our div to look like this:

<div class=<%= content %>>

All of the above methods of rendering the additional content yield the image below:

Additional content being rendered

Rendering a Collection

What if we wanted to render our entire list of courses? ViewComponent provides a very straight forward way of doing this using the with_collection tag. Instead of initializing the component using .new , it is initialized using .with_collection, and the collection is passed to it as a variable, as shown below.


This yields the following:

The Course collection rendered

There is also a with_collection_parameter tag available in case we wish to address the collection by a different name.

class CourseComponent < ViewComponent::Base
  with_collection_parameter :item

  def initialize(item:)
    @item = item

In the above case, the course parameter has been addressed as item. Hence, in the corresponding view, @course will be replaced with @item to yield the same result.

Additional parameters can also be added to the collection. These parameters will be displayed per item in the collection. Let's add a Buy Me text to each item via this method.

<%= render(CourseComponent.with_collection(Course.all, notice: "Buy Me")) %>
# app/components/course_component.rb
class CourseComponent < ViewComponent::Base
  with_collection_parameter :item
  def initialize(item:, notice:)
    @item = item
    @notice = notice

We add a new paragraph to the app/components/course_component.html.erb file to indicate the text for the newly added notice variable.

<p><a href='#'> <%= @notice %> </a></p>

This yields the following:

Courses rendered with an additional notice parameter

Lastly, under collections, we have a counter variable that can be enabled to number the items in a view. It is enabled by adding _counter to the collection parameter and making it available to the views via the initialize method.

def initialize(item:, notice:, item_counter:)
  @item = item
  @notice = notice
  @counter = item_counter

In our views, beside the item title, we add our counter:

<h2><%= @counter %>. <%= @item.title %></h2>

Let's generate a third course from the console to better understand the counter phenomenon.

Course.create(title: 'Understanding Databases', price: '100', location: 'Amsterdam')

This yields the following

Counter added to each course

Conditional Rendering

ViewComponent has a render? hook, which, when used, determines whether a view should be rendered. To implement this, we're going to give a 10% discount for courses with prices equal to or greater than 100 Euros. Let's create a component for this purpose.

rails generate component Discount item

DiscountComponent generated

This component is already automatically initialized with the item it should display a discount for, as seen below.

DiscountComponent initialized

Hence, in the discount_component.html.erb file, we add the text we intend to display.

<p class="green"> A 10% discount is available on this course </p>

Don't hesitate to add the class green to your css file and assign it any shade of green you prefer. Furthermore, in our discount_component.rb file, we add the render? method to determine when this component should be rendered.

def render?
  @item.price >= 100

Now, we can go ahead and render the discount component within the view that renders each course.

# app/components/course_component.html.erb
<%= render( @item)) %>

This yields the following:

DiscountComponent rendered

Isn't that awesome?


In the traditional Rails views, we can easily plug in our helpers by calling the method name in our views, but it works differently with view components. In view components, helper methods cannot be called directly in the views but can be included in a component. We already have a courses_helper.rb file that was automatically generated when the CoursesController was created, so let's take advantage of it. First, let's create a helper method that tells us how many people have enrolled in a course so far. Let's make the value a quarter of the price :).

module CoursesHelper
  def count_enrollees(course)
    count = (course.price / 4).round()
    tag.p "#{count} enrollees so far"

Next, we'll create a component in which we'll call the helper. This is the component that will be rendered in our view. In it, we'll add an include statement, including the helper, and then we can call any method in the helper within this component.

# app/components/enrollee_component.rb
class EnrolleeComponent < ViewComponent::Base
include CoursesHelper

  def total_enrollees(course)

The last step is adding the EnrolleeComponent to the view that displays our courses.

# app/components/course_component.html.erb
<%= %>

Note that we are not using the render word for the EnrolleeComponent, as it doesn't have a view, and its output will be that of the helper method called. This yields the following:

Number of enrollees shown using Helpers

Helpers can be used for icons, gravitars, or whatever you might choose. ViewComponent doesn’t change the use of helpers; it just changes how we call them in our components.

The before_render method

ViewComponent offers a before_render method that can be called before a component is rendered. Let's add a star beside our discount notice. We start by adding a helper method that fetches the star; a star.png image has also been downloaded and placed in the app/assets/images folder.

def star_icon
  image_tag("/assets/star.png", width: "1%")

Let's add a before_render method to our Discount component that calls this helper method.

# app/components/discount_component.rb
def before_render
  @star_icon = helpers.star_icon

As we can see above, another manner of calling helpers is introduced. Helpers can also be called using helpers.method in the component.rb file. Then, in our render method for the DiscountComponent, we input our star icon, which is now made available via the @star_icon variable.

# app/components/discount_component.html.erb
<p class="green"> <%= @star_icon %> A 10% discount is available on this course </p>

This yields the following:

Star icon shown using the before render method

We do not necessarily have to use helpers for the before_render method to work. I have used helpers to introduce another approach to calling helper methods.


Like Action Mailer, ViewComponent makes it possible to preview components. This has to first be enabled in the config/application.rb file.

config.view_component.preview_paths << "#{Rails.root}/lib/component_previews"

Preview components are located in test/components/previews and can be used to preview a component with several different inputs passed in. We'll be previewing our DiscountComponent.

# test/components/previews/discount_component_preview.rb
class DiscountComponentPreview < ViewComponent::Preview
  def with_first_course
    render( Course.find(1)))

  def with_second_course
    render( Course.find(2)))

Two methods have been added to preview the DiscountComponent in different scenarios. To view this, visit http://localhost:3000/rails/view_components, where we find all the preview components created and their methods. We can click on any of them to view what they look like, as shown below.

DiscountComponent previewed

As you can see in the video above, the first course renders the discount component, but nothing gets rendered for the second course. Do you know why this happened?  The render? method check happened. The first scenario is when the cost price is more than 100 euros(the 1st course), but the cost is less than 100 euros for the second course. The method names were not more descriptive to enable you figure out the cause before it is highlighted here :).

Previews can be enabled or disabled in any environment using the show_previews option, but in development and testing environments, they are enabled by default.

# config/environments/test.rb
config.view_component.show_previews = false

JS AND CSS Inclusion

It's possible to include JavaScript and CSS alongside components, sometimes called "sidecar" assets or files. This is still an experimental feature. Hence, we won't dive into its inner workings in this article, but you can find more about this ViewComponent feature here.


The template of a view component can be defined in several ways. The simpler option is inserting the view and component in the same folder, as shown below.

A simple template for view components

As we can see here, we have every component and view in the app/components folder.

Another option is to place the view and other assets in a subdirectory with the same name as the component. Thus, in the app/components folder, we have the component.rb file, which houses the component, and then a separate course_component folder, which houses the view course_component.html.erb and every other asset related to the course_component.

ViewComponent template for asset inclusion

To generate component files in this way from the command line, the --sidecar flag is required:

rails g component Example name  --sidecar

This enables you add your css and js files to the component folder. ViewComponents can also render without a template file by defining a call method. An example of this is provided in the next section, where we discuss slots.


Multiple blocks of content can be passed to a single ViewComponent using slots. Similar to the has_one and has_many attributes in Rails models, slots are defined with renders_one and renders_many:

  • renders_one defines a slot that will be rendered at most once per component: renders_one :header.
  • renders_many defines a slot that can be rendered multiple times per-component: renders_many :titles.

Imagine that we want to have a page that renders a header and the titles of all the courses we have available; this can be achieved using slots. Let's create a ListComponent, which will contain a header that is only rendered once, and a TitleComponent, which renders many titles.

class ListComponent < ViewComponent::Base
  renders_one :header, "HeaderComponent"
  # `HeaderComponent` is defined within this component, so we refer to it using a string.
  renders_many :titles, TitleComponent
  # `titleComponent` will be defined in another file, so we can refer to it by class name.
  class HeaderComponent < ViewComponent::Base
    def call
      content_tag :h1, content

In the component above, we stated that the header is rendered once, but the titles are rendered many times, as this page would contain many titles. We have also defined the HeaderComponent within the ListComponent. Yes, this is possible with ViewComponent; a class can be defined within another class. Let's also take note of the call method discussed earlier under the Templates section and how it's being used in the HeaderComponent to render an h1 tag, thereby eliminating the need for a corresponding view(html.erb file). The corresponding HTML file for the ListComponent would contain the following;

  <%= header %> <!-- renders the header component -->
  <% titles.each do |title| %>
      <%= title %> <!-- renders an individual course title -->
  <% end %>

In the html file, we have included the header, iterated through all the titles passed into the component, and rendered them. As you can see, we do not have to specify the name of the component to be rendered in the list view file; our slots have taken care of that. Hence, we just identify them as header and title.

The next step is to create our TitleComponent and its corresponding HTML file, as this is what will be rendered for every title passed.

# app/components/title_component.rb
class TitleComponent < ViewComponent::Base
  def initialize(title:)
    @title = title
# app/components/title_component.html.erb
  <h3> <%= @title %> </h3>

Finally, in our index.html file, let's temporarily erase what we have and replace it with the ListComponent render.

<%= render do |c| %>
  <% c.header do %>
  <%= link_to "List of Available Courses", root_path %>
  <% end %>
  <%= c.title(title: "First title") %>
  <%= c.title(title: "Second title!") %>
<% end %>

Individual titles rendered using Slots

Now, let's pass our courses into this view as a collection. To pass a collection into a slot, we have to pass the collection as an array of objects containing the variable needed for initialization. As we can see, every course passed in should be initialized with the title argument. We can extract the titles of all the courses in our db into an array of hashes and render it.

A hash containing the titles of all the courses

We can now replace our list of several titles with a single c.titles for a collection and pass it to our hash of titles, which we define using the variable course_titles.

# app/views/courses/index.html.erb
<% course_titles = Course.all.pluck(:title).map { |title| {title: title}} %>

<% c.titles(course_titles) %>

This yields the following:

A collection of titles rendered using Slots

This is exactly how slots work: rendering several components within a single ViewComponent. Slots can be rendered in several other ways, and you can find more info here.


Testing view components is done by requiring "view_component/test_case" in the test file and using the render_inline test helper so that assertions are made against the rendered output. Let's begin by testing our DiscountComponent.

require "test_helper"
require "view_component/test_case"

class DiscountComponentTest < ViewComponent::TestCase
  def test_render_component
    render_inline( "my item"))

When we run this test using the command rails test test/components/discount_component_test.rb, we get the following error:

DiscountComponent Test Error Message

This proves to us that the test is getting to the right component but is lacking a suitable prop, as the item must be a course with a price property and not a string, as we passed. It also tells us that there is a render? method being checked before this component renders. Let's pass in the right variables now.

def test_render_component
  course = Course.create(title: 'Organizing your Time', price: 55.00, location: 'London')
  render_inline( course))

This runs successfully. Let's proceed to add assertions to this test.

def test_render_component
  course = Course.create(title: 'Organizing your Time', price: 155.00, location: 'London')
  render_inline( course))
  assert_selector 'p[class="green"]'
  assert_text "10% discount"

This test also passes. Recall that there is a render condition for this component. Don’t worry, though, because ViewComponent also provides a way to test that a component is not rendered, by using refute_component_rendered. We can test this using a course with a price below 100 euros.

def test_component_not_rendered
  course = Course.create(title: 'Organizing your Time', price: 55.00, location: 'London')
  render_inline( course))

This test also passes.

Let's write another test for our CourseComponent to test that it renders all the components nested within it.

require "test_helper"
require "view_component/test_case"

class CourseComponentTest < ViewComponent::TestCase
  def test_component_renders_all_children
    course = Course.create(title: 'Organizing your Time', price: 155.00, location: 'London')
    render_inline( course, notice: 'A new test', item_counter: 1))
    assert_selector("h2", text: "Organizing your Time")
    assert_selector("h4", text: "€155.00")
    assert_selector("h4", text: "London")

This test also passes. It tests that the Enrollee and Discount components are also rendering properly.

Recall that we have a slot component, and as shown in the image below, it renders one header and many titles.

ListComponent using slots to render other Components

To test this, we pass the component a block of code containing the header and titles it should render, and then we can assert against the rendered component.

require "test_helper"
require "view_component/test_case"

class ListComponentTest < ViewComponent::TestCase
  def test_renders_slots_with_content
  render_inline( do |component|
  component.header { "A Test List" }
  component.titles [{title: 'Test title 1'}, {title: 'Test title 2'}]

  assert_selector("h1", text: "A Test List")

  assert_text("Test title 1")
  assert_text("Test title 2")

This test also passes :).

Rspec Testing

In addition to all that has been said above about testing, if the preferred testing framework is RSpec, some additional configurations must be carried out to enable RSpec for ViewComponents.

# spec/rails_helper.rb
require "view_component/test_helpers"
require "capybara/rspec"

RSpec.configure do |config|
  config.include ViewComponent::TestHelpers, type: :component
  config.include Capybara::RSpecMatchers, type: :component

Our DiscountComponent test can be re-written and retested using Rspec, as shown below:

require "rails_helper"

RSpec.describe DiscountComponent, type: :component do

  it "renders the component correctly" do
    course = Course.create(title: 'Organizing your Time', price: 155.00, location: 'London')
    render_inline( course))
    expect(rendered_component).to have_css "p[class='green']", text: "10% discount"
    expect(rendered_component).to have_css "img[src*='/assets/star.png']"

This test passes elegantly. Hell yeah, we can see our star icon.


Writing several view components for your Rails app not only makes your code more readable and less prone to errors from unwanted complications but also makes it possible to test your views in isolation and not only during HTTP requests. View components are easy to inculcate into an existing Rails app, and its best to start with views that are mostly reused. With everything learned so far, this should be an easy-peasy task. Nevertheless, if you would like more information on ViewComponent, do not hesitate to go through its documentation or the RubyDoc info.

What to do next:
  1. Try Honeybadger for FREE
    Honeybadger helps you find and fix errors before your users can even report them. Get set up in minutes and check monitoring off your to-do list.
    Start free trial
    Easy 5-minute setup — No credit card required
  2. Get the Honeybadger newsletter
    Each month we share news, best practices, and stories from the DevOps & monitoring community—exclusively for developers like you.
    author photo

    Abiodun Olowode

    Abiodun is a software engineer who works with Ruby/Rails and React. She is passionate about sharing knowledge via writing/speaking and spends her free time singing, binge-watching movies or watching football games.

    More articles by Abiodun Olowode
    Stop wasting time manually checking logs for errors!

    Try the only application health monitoring tool that allows you to track application errors, uptime, and cron jobs in one simple platform.

    • Know when critical errors occur, and which customers are affected.
    • Respond instantly when your systems go down.
    • Improve the health of your systems over time.
    • Fix problems before your customers can report them!

    As developers ourselves, we hated wasting time tracking down errors—so we built the system we always wanted.

    Honeybadger tracks everything you need and nothing you don't, creating one simple solution to keep your application running and error free so you can do what you do best—release new code. Try it free and see for yourself.

    Start free trial
    Simple 5-minute setup — No credit card required

    Learn more

    "We've looked at a lot of error management systems. Honeybadger is head and shoulders above the rest and somehow gets better with every new release."
    — Michael Smith, Cofounder & CTO of YvesBlue

    Honeybadger is trusted by top companies like:

    “Everyone is in love with Honeybadger ... the UI is spot on.”
    Molly Struve, Sr. Site Reliability Engineer, Netflix
    Start free trial
    Are you using Sentry, Rollbar, Bugsnag, or Airbrake for your monitoring? Honeybadger includes error tracking with a whole suite of amazing monitoring tools — all for probably less than you're paying now. Discover why so many companies are switching to Honeybadger here.
    Start free trial
    Stop digging through chat logs to find the bug-fix someone mentioned last month. Honeybadger's built-in issue tracker keeps discussion central to each error, so that if it pops up again you'll be able to pick up right where you left off.
    Start free trial
    “Wow — Customers are blown away that I email them so quickly after an error.”
    Chris Patton, Founder of
    Start free trial