Getting started

Installation

Rails Installation

1. In Gemfile, add:

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

2. In.gitignore, add:

   **/*.stories.json
   

Storybook Installation

1. Add Storybook Server as a dev dependency.

   yarn add @storybook/server @storybook/addon-controls --dev
   

   Storybook Controls addon isn’t required but is strongly recommended.

2. Add an NPM script to start Storybook. In package.json, add:

   {
     "scripts": {
       "storybook": "start-storybook"
     }
   }
   

3. Configure Storybook to find the json stories that the gem creates. Create .storybook/main.js,

   module.exports = {
     stories: ["../test/components/**/*.stories.json"],
     addons: ["@storybook/addon-controls"],
   };
   

4. Configure Storybook with the Rails application url to call for the html content of the stories. Create .storybook/preview.js

   export const parameters = {
     server: {
       url: `http://localhost:3000/rails/stories`,
     },
   };
   

Quick start

Create a ViewComponent

Use the component generator to create a new ViewComponent.

bin/rails generate component Example title

      invoke  test_unit
      create  test/components/example_component_test.rb
      create  app/components/example_component.rb
      create  app/components/example_component.html.erb

This generates a new component:

# app/components/example_component.rb
class ExampleComponent < ViewComponent::Base
  def initialize(title:)
    @title = title
  end
end

Add a template for the new component:

<%# app/components/example_component.html.erb %>
<span title="<%= @title %>"><%= content %></span>

Write a story for ExampleComponent

# test/components/stories/example_component_stories.rb
class ExampleComponentStories < ViewComponent::Storybook::Stories
  story :hello_world do
    constructor(title: "my title") do
      "Hello World!"
    end
  end
end

Generating Storybook Stories JSON

Generate the Storybook JSON stories by running the rake task:

rake view_component_storybook:write_stories_json

Start the Rails app and Storybook

In separate shells start the Rails app and Storybook

rails s

yarn storybook

The second command will open the Storybook app in your browser rendering your ExampleComponent story!

Implementation

When Storybook calls the Rails app for the html story content the ViewComponent::Storybook passes the string “my title” to the component constructor and “Hello World!” as the component content. Effectively the component is rendered in a view as:

<%= render(ExampleComponent.new(title: "my title")) do %>
  Hello, World!
<% end %>

Returning the rendered html to Storybook:

<span title="my title">Hello, World!</span>

Dynamic Stories with Controls

Storybook isn’t just for rendering static stories. Storybook controls enable dynamic stories with variable inputs. ViewComponent Storybook exposes a similar api to describe dynamic inputs to component stories. For example add the text control to make title and content dynamic:

# test/components/stories/example_componeont_stories.rb
class ExampleComponentStories < ViewComponent::Storybook::Stories
  story :hello_world  do
    constructor(title: text("my title"))
    content(text("Hello World!"))
  end
end

This adds text controls to the Storybook Controls panel. Changing the values re-renders the compoent.

Available controls and their options are documented on the Controls page.