phoenix_storybook: a component workbench for Phoenix and LiveView

Mounted in your own router, not a separate service

PhoenixStorybook provides a Storybook-like user interface for your Phoenix components, and the first thing to understand is where it lives. It is mounted in your application router and serves its user interface at the mounting point of your choice, so the storybook is part of your application rather than a separate development server you have to run. That has a practical consequence for the two other ways it is used, because the storybook renders your real components through your real endpoint, so the environment it runs in is your environment. The library does automatic discovery of your storybook content under a specified folder, the content path, and then automatically generates a storybook navigation sidebar, and every module detected in the content folder is loaded and identified as a storybook entry. There is no manifest to maintain and no registry to update when you add a component, which is the property that makes it usable as a growing catalogue rather than a curated one.

Three kinds of story, and they cover different purposes

Three kinds of stories are supported, and the distinction between them is the design. A component story describes a stateless function component or a live_component. A page story is for writing and documenting user interface guidelines, or whatever content you want, so the storybook doubles as a written style guide rather than only a component gallery. An example story shows how your components can be used and mixed in real user interface pages, which is the one that catches integration problems that isolated component examples do not. The three capabilities the library advertises map onto these: exploring all your components and showcasing them with different variations, browsing a component's documentation with its supported attributes, and learning how components behave by using an interactive playground. That last one is the closest thing to the Storybook.js playground, and it is the reason the library depends on LiveView rather than being a static page generator.

Installing it with Igniter or by hand

There is a fast path and a manual path, and the fast path is the one most people should take. The fastest way to install the storybook is with Igniter, which adds the dependency, generates the storybook files and applies the whole setup, meaning the router, layout, assets, config, formatter and mix aliases, automatically:

mix igniter.install phoenix_storybook

The alternative is to add the dependency yourself and run the generator. The dependency goes in your mix.exs and you run mix deps.get:

def deps do
  [
    {:phoenix_storybook, "~> 1.4.0"}
  ]
end

Then the generator, run from the root of your application:

$> mix deps.get
$> mix phx.gen.storybook

One important note applies if you pick a GitHub version of the library rather than an official hex.pm release, because in that case you also need the storybook's assets compiled, which means running mix dev.storybook. The documentation also points at a setup guide for those who prefer manual setup.

Two mandatory settings and a long list of optional ones

Of all the configuration settings, only the otp_app and content_path keys are mandatory, and the storybook module itself is where they live, in a file such as lib/my_app_web/storybook.ex. The otp_app is the OTP name of your application, and the content_path is the path to your storybook stories, either absolute or relative to the Mix project root. Everything else is optional and there is a lot of it. There is a js_path for a JavaScript asset loaded just before the library's own JavaScript, intended mainly for defining LiveView hooks in window.storybook.Hooks, and the same pattern for css_path and theme_path, all of which are remote paths served by your own application endpoint rather than local file system paths. The stylesheet is loaded within the app CSS layer, and the layer ordering is reset, theme, app, utilities, which tells you where your rules land. A sandbox_class is put on the storybook container elements so your own styles prevail, with a guide on sandboxing for the details, and source_permalink_base_url and source_permalink_root control the permalinks in the source tab, with the recommendation that the base includes the blob path for GitHub or the equivalent for GitLab.

Themes and colour modes are first class settings

The theme system is more than a stylesheet swap. Each theme must have a name and an optional dropdown_class, and when a theme is set, a dropdown appears in the storybook header so the user can pick one, with the dropdown_class used both to render the theme in the dropdown and to identify which theme is currently active. The chosen theme key is passed as an assign to all components, so a component can react to the theme it is being previewed in, and the chosen theme class is also added to the psb-sandbox container, which is how a theme reaches the components that are being rendered. If no theme has been selected or no theme is present in the URL, the first one is enabled. Colour mode is a separate switch, off by default, and it takes a dark class and a light class for the sandbox. The icon settings are similarly detailed, with a plan for custom FontAwesome icons, a kit id, an optional path to your own FontAwesome CSS, and a rendering option that can be webfont or svg.

One maintainer, a demo and a sample app

The project is small and run by one person, and the README says so directly: the maintainer is the sole maintainer of this project and works on it in his free time. The resources around it are correspondingly complete for something of this size. There is hosted documentation on hexdocs, a live demo, a separate sample application repository, a getting started video, and a write-up on ElixirCasts. The repository itself has a guides directory, a lib directory, a priv directory, assets, a config directory, a test directory and screenshots, with a mix.exs and mix.lock, a .credo.exs for the Elixir linter, a .formatter.exs, a biome.json for the JavaScript side, and a coveralls.json for coverage reporting. The release history is steady, with v1.5.0 in September 2026 after v1.4.1 and v1.4.0 a week and a half earlier, and the last push was on 2026-10-05. The library is MIT licensed, and the topics on the repository are elixir, liveview, phoenix and storybook.

Editorial conclusion

phoenix_storybook suits a Phoenix team that builds a lot of function components or live_components and wants one place to see their variations, their supported attributes and their behaviour, without a separate JavaScript toolchain. It does not suit a project that wants the Storybook.js experience with its addons ecosystem, since this is an Elixir and LiveView implementation, and it does not suit a team that keeps its component library in a different repository. Before you install it, decide where the storybook content lives, because the content path and the otp app are the only two mandatory settings, and read the setup guide if you are not using Igniter.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. phenixdigital/phoenix_storybook on GitHub
4. README
5. Releases