Link Search Menu Expand Document

Previews

ViewComponent::Preview, like ActionMailer::Preview, provides a quick way to preview components in isolation.

For a more interactive experience, consider using ViewComponent::Storybook or Lookbook.

Define a ViewComponent::Preview:

# test/components/previews/example_component_preview.rb
class ExampleComponentPreview < ViewComponent::Preview
  def with_default_title
    render(ExampleComponent.new(title: "Example component default"))
  end

  def with_long_title
    render(ExampleComponent.new(title: "This is a really long title to see how the component renders this"))
  end

  def with_content_block
    render(ExampleComponent.new(title: "This component accepts a block of content")) do
      tag.div do
        content_tag(:span, "Hello")
      end
    end
  end
end

Then access the resulting previews at:

It’s also possible to set dynamic values from the params by setting them as arguments:

# test/components/previews/example_component_preview.rb
class ExampleComponentPreview < ViewComponent::Preview
  def with_dynamic_title(title: "Example component default")
    render(ExampleComponent.new(title: title))
  end
end

Which enables passing in a value with http://localhost:3000/rails/view_components/example_component/with_dynamic_title?title=Custom+title.

The ViewComponent::Preview base class includes ActionView::Helpers::TagHelper, which provides the tag and content_tag view helper methods.

Previews use the application layout by default, but can use a specific layout with the layout option:

# test/components/previews/example_component_preview.rb
class ExampleComponentPreview < ViewComponent::Preview
  layout "admin"

  ...
end

To set a custom layout for previews and the previews index page, set: default_preview_layout:

# config/application.rb
# Set the default layout to app/views/layouts/component_preview.html.erb
config.view_component.default_preview_layout = "component_preview"

Preview classes live in test/components/previews, which can be configured using the preview_paths option:

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

Previews are served from http://localhost:3000/rails/view_components by default. To use a different endpoint, set the preview_route option:

# config/application.rb
config.view_component.preview_route = "/previews"

This example will make the previews available from http://localhost:3000/previews.

Preview templates

Given a preview test/components/previews/cell_component_preview.rb, template files can be defined at test/components/previews/cell_component_preview/:

# test/components/previews/cell_component_preview.rb
class CellComponentPreview < ViewComponent::Preview
  def default
  end
end
<%# test/components/previews/cell_component_preview/default.html.erb %>
<table class="table">
  <tbody>
    <tr>
      <%= render CellComponent.new %>
    </tr>
  </tbody>
</div>

To use a different location for preview templates, pass the template argument: (the path should be relative to config.view_component.preview_path):

# test/components/previews/cell_component_preview.rb
class CellComponentPreview < ViewComponent::Preview
  def default
    render_with_template(template: 'custom_cell_component_preview/my_preview_template')
  end
end

Values from params can be accessed through locals:

# test/components/previews/cell_component_preview.rb
class CellComponentPreview < ViewComponent::Preview
  def default(title: "Default title", subtitle: "A subtitle")
    render_with_template(locals: {
      title: title,
      subtitle: subtitle
    })
  end
end

Which enables passing in a value with http://localhost:3000/rails/view_components/cell_component/default?title=Custom+title&subtitle=Another+subtitle.

Configuring preview controller

Previews can be extended to allow users to add authentication, authorization, before actions, or anything that the end user would need to meet their needs using the preview_controller option:

# config/application.rb
config.view_component.preview_controller = "MyPreviewController"

Enabling previews

Previews are enabled by default in test and development environments. To enable or disable previews, use the show_previews option:

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

Source previews

A source preview is a syntax highlighted source code example of the usage of a view component, shown below the preview. Source previews are disabled by default. To enable or disable source previews, use the show_previews_source option:

# config/environments/test.rb
config.view_component.show_previews_source = true

To render a source preview in a different place, use the view helper preview_source from within your preview template or preview layout.