Previews Overview

Preview classes are used to provide a set of illustrative examples (scenarios) for how each component should be used.

Preview classes typically have a 1-to-1 mapping with components, with each component having its own dedicated preview class.

Preview classes live in the test/components/previews directory by default.

File names must end in _preview.rb and should reflect the name of the component they are rendering - for example button_component_preview.rb.

Preview classes extend Lookbook::Preview (or optionally ViewComponent::Preview if using with ViewComponent).

# test/components/previews/button_component_preview.rb
class ButtonComponentPreview < Lookbook::Preview
  # scenarios defined here
end

Each public method defined within a preview class represents a unique scenario in which the target component is rendered using a particular set of arguments.

Lookbook will generate an isolated component preview for each scenario and make it accessible via the preview navigation.

# test/components/previews/button_component_preview.rb
class ButtonComponentPreview < Lookbook::Preview
  def standard
    render ButtonComponent.new(text: "Click me")
  end

  def with_icon
    render ButtonComponent.new(text: "Launch spaceship", icon: "rocket")
  end

  private

  # Private methods are ignored and will not show up in the navigation
  def not_a_scenario
    # ...
  end
end

You can set dynamic values from URL parameters by setting them as arguments:

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

And then supply values via URL parameters:

/lookbook/inspect/example/with_dynamic_title?title=Custom+title

For better ease of use and discoverability you can optionally add preview param tags to generate form fields so that parameter values can be set on-the-fly from within the Lookbook UI.

Read more about dynamic preview params →

Previews render with the application layout by default, but can be configured to use a specific layout either globally or on a per-preview-class basis.

See the preview layout docs for details on configuring and using layouts →

Given a preview test/components/previews/cell_component_preview.rb, template files for each scenario can be defined within the test/components/previews/cell_component_preview/ directory:

# test/components/previews/cell_component_preview.rb
class CellComponentPreview < Lookbook::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 the preview directory):

# test/components/previews/cell_component_preview.rb
class CellComponentPreview < Lookbook::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 < Lookbook::Preview
  def default(title: "Default title", subtitle: "A subtitle")
    render_with_template(locals: {
      title: title,
      subtitle: subtitle
    })
  end
end

Extend previews to add authentication, authorization, before actions, etc. using the lookbook.preview_controller config option:

config.lookbook.preview_controller = "MyPreviewController"

The contents of the preview directory can be organised into folders and Lookbook will reflect this structure in its navigation tree.

Watch out for preview class namespacing in subdirectories - the class namespace must reflect the relative path to the preview class (just like classes in the main Rails app directory). Note the file path and the (correct) namespacing in the example below:

# test/components/previews/elements/buttons/primary_button_component_preview.rb
class Elements::Buttons::PrimaryButtonComponentPreview < Lookbook::Preview
  def default
    render PrimaryButtonComponent.new(text: "Click me")
  end
end