Storybook 5.0

Michael Shilman
Mar 5, 2019 · 7 min read

Welcome to the future of component development! We’re kicking off 2019 with Storybook 5.0 (SB5), our biggest release to date. Here’s what’s in it:

  • 🎨 Complete overhaul of Storybook’s developer experience
  • 💅 Theme-ready component library
  • 🛠 Evolved front-end architecture for addons
  • 🖼 Brand new Storybook website

Read on for a project update, tour of improvements, and upgrade instructions.

Storybook’s progress and what’s next

📈 Record adoption: Storybook is the tool of choice at UI powerhouses like Airbnb, Slack, Squarespace, Lyft, Dropbox. Adoption continues to grow across industry and open source projects, recently crossing 4.5 million monthly npm downloads.

👩‍💻 Thriving community: The Storybook community recently surpassed 600 contributors and 34k stars on Github, vaulting us into the top 40 Javascript projects by star count. The community is stronger than ever. To guide the project into the future we established a steering committee of top maintainers.

🛠 Professional-grade tool: In 2018 we focused on building the Storybook platform: expanded view layer support, addon cross-compatibility, and evolving alongside JavaScript tooling. Now in 2019 we’re improving the developer experience by:

  • Prioritizing user feedback
  • Making Storybook configurable in all the ways you want
  • Stabilizing the platform with smaller, more frequent releases

Say hello to the new Storybook

The new UI addresses accumulated user feedback dating all the way back to 2016. It boasts:

  • 🌓 New design with light and dark themes
  • 🛠 Canvas toolbar for easy access to addons
  • 🗺 Overhauled navigation sidebar with an intuitive menu
  • 🗜 Redesigned addons panel with handy buttons to toggle visibility and orientation
  • ⌨️ Improved keyboard shortcuts that are user configurable
  • 🌍 New URL structure that eliminates long strings of query parameters

These upgrades improve the entire Storybook ecosystem of view layers, addons, and integrations. Read more about this project in Meet Storybook’s new design.

The UI was designed by Dominic Nguyen. Implemented by Norbert de Langen, Dominic Nguyen, Tom Coleman, Jessica Koch, Alexandre Bodin, and many more contributors.

Reuse Storybook’s components

Storybook components are lovingly crafted in Storybook itself

Storybook Components is implemented in React and Emotion. The library contains all of the building blocks for the Storybook interface, crafted for both desktop and mobile, and customizable through Emotion’s flexible theming API.

Releasing the library achieves a few different goals:

  • ⚡️Accelerate development: We document common use cases, automate visual testing, and promote code reuse
  • ✨ Promote best practices: Our long-term goal is that the library will be a shining example of how to build a well-documented design system in Storybook. We’ve got a long way to go here, but SB5 is a first step.
  • 🏗 Improve the workflow: We eat our own dogfood. Many of SB5’s improvements came as a result of building our component library in Storybook.

Check out the library in Storybook’s Official Storybook, and stay tuned for more documentation as we continue to build out this resource for the Storybook community.

Customize Storybook to your needs

Theme API

Update to your brand (left) + Change the theme (right)

Storybook includes hand-crafted “light” and “dark” themes out of the box. These themes stand alone and serve as starting points for customization. Here’s a simple example to get you started:

SB5’s theme system is abstracted into a core set of variables. This simplifies theming for developers while making it easier to preserve backwards compatibility as Storybook’s UI evolves. For more information about theming in SB5, please see the updated Theming documentation.

For adventurous theme authors there is also an escape hatch that allows you to hack the underlying Emotion theming API.

Addons API

  • Toolbar: Addons can now add UI into the … wait for it… toolbar!! This makes controlling addons discoverable and immediate for users. The Viewport, Backgrounds, and A11y addons all show off this new feature.
  • Tab: Addons can also add new tabs to the main stories panel to embed alternative views onto your stories. The Notes addon shows off this feature, and we’ll be building out more creative integrations soon.

These new hooks are just the start of how we’ll be opening up SB5 to addons while maintaining a simple, streamlined API.

Addons can be placed in the easy access Toolbar or the revamped Addons panel

For addon users, installation and configuration has not changed in SB5. For addon authors interested in the new APIs, refer to the the Storybook addons documentation.

The brand new website

Designed by Dominic Nguyen with review/QA from Igor Davydkin, Sacha Greif, orta, and Aparajita Fishman. The site is implemented in Gatsby by Dominic, Tom, Dale Blackburn, Lucas Carl, and Chak Shun Yu. It’s a great reference point for how to systematically build websites in Storybook.

“But why do I need Storybook?”

I’m thrilled to announce a new intro video that answers this perennial question once and for all. In less than two minutes you’ll see why isolated component development is crucial for modern apps and how Storybook helps you do it.

The breathtaking intro video was animated by Daniel Egerev and directed by Dominic Nguyen.

Upgrade to Storybook 5.0

If you’re new to Storybook, check out the Storybook Tutorial for a step-by-step walkthrough of React/Angular/Vue.

Or if you prefer to just jump in, it takes 30 seconds to add SB5 to an existing project:

cd my-project
npx -p @storybook/cli sb init
yarn storybook

Thanks to the community

Storybook 5.0 contains code contributions from the following people:

@backbone87 @bertho-zero @dandean @domyen @donaldpipowitch @ebrearley @gabrielcsapo @gaetanmaisse @gbakernet @gongreg @greysteil @hypnosphi @igor-borisov @igor-dv @jessica-koch @jessidhia @jhummel @johot @jure @keraito @koenpunt @kroeder @kwm14 @kylemh @lauriejones @loklaan @maacky @manbeartm @marcobiedermann @martinmckenna @matteo-hertel @misund @mrmckeb @myoxocephalus @ndelangen @nitaking @pascalduez @petersendidit @pgoforth @pickra @piperchester @pksunkara @psyked @rwoverdijk @sayegh7 @sharils @shilman @tmeasday @tomraithel @web-padawan @wuweiweiwu

SB5 is the first time we’ve done a coordinated RC process. Thanks to everybody who tested and reported issues with a special shout out to MVP’s Alex Wilson and Leo Y. Li for putting SB5 through its paces.

If Storybook brings delight and efficiency to your UI development process, please consider helping make Storybook better. Whether you’re contributing a new feature like the ones described in this post, fixing a bug, or helping improve the documentation, there is a mountain of work that goes into every release. Join us on Discord, support us on Open Collective, or just jump in on Github.

Have questions or kudos? Say hi on Twitter, Discord, Github, or in the comments below. Please 👏 applaud this post and share to help more people discover it.


The UI development environment you'll ♥️ to use.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store