A story designates any kind of content in your storybook. For now only following kinds of stories are supported :component, :live_component, and :page.

In order to populate your storybook, just create story scripts under your content path, and implement their required behaviour.

Stories must be created as story.exs files.

In dev environment, stories are lazily compiled when reached from the UI.

Usage

Component

Implement your component as such. Confer to:

• PhoenixStorybook.Variation documentation for variations.
• PhoenixStorybook.Attr documentation for attributes.

# storybook/my_component.exs
defmodule MyAppWeb.Storybook.MyComponent do
  use PhoenixStorybook.Story, :component

  # required
  def function, do: &MyAppWeb.MyComponent.my_component/1

  def attributes, do: []
  def slots, do: []
  def variations, do: []
end

Live Component

Very similar to components, except that you need to define a component/0 function instead of function/0.

# storybook/my_live_component.exs
defmodule MyAppWeb.Storybook.MyLiveComponent do
  use PhoenixStorybook.Story, :live_component

  # required
  def component, do: MyAppWeb.MyLiveComponent

  def attributes, do: []
  def slots, do: []
  def variations, do: []
end

ℹ️ Learn more on components in the components guide.

Page

A page is a fairly simple story that can be used to write whatever content you want. We use it to provide some UI guidelines.

You should implement the render function and an optional navigation function, if you want a tab based sub-navigation. Current tab is passed as :tab in render/1 assigns.

# storybook/my_page.exs
defmodule MyAppWeb.Storybook.MyPage do
  use PhoenixStorybook.Story, :page

  def doc, do: "My page description"

  def navigation do
    [
      {:tab_one, "Tab One", {:fa, "book"}},
      {:tab_two, "Tab Two", {:fa, "cake", :solid}}
    ]
  end

  def render(assigns) do
    ~H"<div>Your HEEX template</div>"
  end
end

Example

An example is a real-world UI showcasing how your components can be used and mixed in complex UI interfaces.

Examples are rendered as a child LiveView, so you can implement mount/3, render/1 or any handle_event/3 callback. Unfortunately handle_params/3 cannot be defined in a child LiveView.

By default, your example story's source code will be shown in a dedicated tab. But you can show additional files source code by implementing the extra_sources/0 function which should return a list of relative paths to your example related files.

# storybook/my_example.story.exs
defmodule MyAppWeb.Storybook.MyPage do
  use PhoenixStorybook.Story, :example

  def doc, do: "My page description"

  def extra_sources do
    [
      "./template.html.heex",
      "./my_page_html.ex"
    ]
  end

  def mount(_, _, socket), do: {:ok, socket}

  def render(assigns) do
    ~H"<div>Your HEEX template</div>"
  end
end