New
Automatic visual tests in Storybook, plus 2.2x faster build times for React+TSVisual test with Chromatic
Star80,494
Back to integrations
Add your integration
Categories
  • ⭐️ Popular
  • 🧩 Essentials
  • 🛠 Code
  • ⚡️ Data & state
  • ✅ Test
  • 💅 Style
  • 🎨 Design
  • ⚙️ Appearance
  • 🗄 Organize
How to install addons Create an addon

Integrate Material UI and Storybook

Material UI is a component library based on Google's Material Design spec. This recipe shows you how to get the most out of Material UI in Storybook.

This recipe assumes that you already have a React app using the @mui/material package set up with Storybook 7.0 or newer. If you don’t have a project ready, check out this Stackblitz to follow along.

How to setup Material UI and Storybook

Material UI offers a set of themeable components that devs can use to start building UIs right away. It’s based on Material Design language from Google.

Storybook is a frontend workbench for building UIs in isolation. By combining Storybook and Material UI, you can build UIs faster without all the grunt work. This recipe shows you how to configure Storybook to load Material UI components and dynamically interact with their API.

  • 📦 Bundle your fonts for fast and consistent rendering
  • 🎨 Load your custom theme and add a theme switcher
  • ♻️ Reuse Material UI types to auto-generate story controls

Install @storybook/addon-styling

Add the @storybook/addon-styling package to your DevDependencies

Auto-config

Before running this codemod, please ensure that you have no other changes in your git branch.

As of version 1.3, @storybook/addon-styling offers a codemod for to automatically configure your storybook with Material UI.

To try it out, run the following script:

If the codemod didn't work, please let us know in this GitHub issue so we can continue to make the codemod even better. In the meantime, the instructions below will get you up and running in no time.

Manual

Register the addon

Register the addon with Storybook in .storybook/main.js.

Bundle fonts and icons for better perf

Material UI depends on two fonts to render as intended, Google’s Roboto and Material Icons. While you can load these fonts directly from the Google Fonts CDN, bundling fonts with Storybook is better for performance.

  • 🏎️ Fonts load faster because they are coming from the same place as your app
  • ✈️ Font will load offline so you can continue developing your stories anywhere
  • 📸 No more inconsistent snapshot tests because fonts load instantly

To get started, install the fonts as dependencies.

Then import the CSS files into .storybook/preview.js, the entrypoint of your storybook.

Load custom themes and add a theme switcher

Material UI comes with a default theme out of the box, but you can also create and provide your own themes. Given the popularity of dark mode, you'll likely end with more than one custom theme. Let's look at how you can load custom themes and switch between them with just a click.

Switching between light and dark mode using a theme switcher in the Storybook toolbar

For example, take these custom light and dark mode themes.

Then apply the custom themes to our stories. We’ll need to wrap them in Material UI’s ThemeProvider using the withThemeFromJSXProvider decorator.

Awesome! Now when Storybook is reloaded, you'll see that our withThemeFromJSXProvider decorator is providing our custom light theme by default.

Use Material UI prop types for better controls and docs

Storybook controls give you graphical controls to manipulate a component’s props. They’re handy for finding edge cases of a component and prototyping in the browser.

Usually, you have to manually configure controls. But if you’re using Typescript, you can reuse Material UI’s component prop types to auto generate story controls. As a bonus, this will also automatically populate the prop table in your documentation tab.

Changing the button components props using Storybook controls

Let’s take the following Button component for example.

Here I’m using the label prop as the MuiButton’s child and passing all other props through. However, when we render this into Storybook, our controls panel only lets us change the label prop that we declared ourselves.

The button story with only a label prop control

This is because Storybook only adds props to the controls table that are explicitly declared in the component’s prop types or in the Story Args. Let’s update Storybook’s Docgen configuration to bring Material UI‘s Button props into the controls table as well.

We also want to update the parameters in .storybook/preview.js to show the description and default columns for the controls table.

Lastly, update the ButtonProps type to extend from Material UI’s Button props to add all of these props to the controls.

Restart your Storybook server so that these config changes take effect. You should now see that Button has controls for all of MuiButton's props as well.

The button story with all 27 prop controls from the MUI button props

Choose which controls are visible

Our button now has 27 props, which is perhaps a little much for your use case. To control which props are visible we can use TypeScript’s Pick<type, keys> and Omit<type, keys> utilities.

And now our Button will only take the variant, size, and color props from MuiButton.

The button story with only the controls specified

📣 Shout out to Eric Mudrak’s awesome Storybook with React & TypeScript article that inspired this tip.

Join the community
6,326 developers and counting
WhyWhy StorybookComponent-driven UI
Open source software
Storybook

Maintained by
Chromatic
Special thanks to Netlify and CircleCI