Check out a free preview of the full Design Systems with React & Storybook course:
The "Using Add-ons & Themes" Lesson is part of the full, Design Systems with React & Storybook course featured in this preview video. Here's what you'd learn in this lesson:

Emma explains what addons are and how to use them with a theme in storybook.

Get Unlimited Access Now

Transcript from the "Using Add-ons & Themes" Lesson

[00:00:00]
>> We're gonna create some documentation, so we're gonna install a couple of ad-ons. Ad-ons are packages that you can install, and use with storybook to add additional capabilities. We're gonna have a bunch of them, so let's install them now, npm i, let me make this bigger here, we're gonna do Okay, that was my own thing.

[00:00:21] Npm i, we're gonna do renew app storybook slash preset, create react app, so we're telling story, but this is a create react app. We're gonna install actions, I have to believe that storybook actions though we'll find out, And add-on docs. Okay, so those three and those are on the website, feel free to go grab them and they're using add-on section.

[00:00:54] When we add these add-ons every time we add an add-on we have to tell storybook about it, and we can do that by going to this main file up here that I just mentioned. So, anytime we add an add-on it has to go in here. So, while that's loading let's go ahead and do that, so, lets add our preset create react app is actually already added here, so I actually didn't need to install it.

[00:01:18] We also have actions and so I don't know why I just added those but that's fine, not harming anything. And then we just need to add our docs, so @storybook/addon-docs. This is gonna give us that documentation for product management for design to go in and actually have something nice to look at.

[00:01:41] What I'm gonna recommend is that you actually go over to the course notes and under the add-ons story here using add-ons, I have this file, I have this big block of text here. This is marked down and this is gonna be like our fake documentation for our components, so what I would say is let's copy this, it's a lot, but we'll see it rendering and I'll walk you through it.

[00:02:03] So inside of components, create a new file, I'm gonna call it buttons.stories.js, okay? I'm just gonna copy and paste all this stuff in and then we'll walk through it in just a second. Okay, so we've imported add-on docs, and you'll see what all of these packages are doing in just a second, and we've also imported our button components.

[00:02:36] So at the top here, we've got some metadata, what's the title of the story, and what component is this going to be documenting. And actually, this should be the MDX, we're gonna be using MDX which is a way to write mark down with your JSX, okay? And so what we need to do now that we have our documentation added, I wanna tell stories but, hey this file could be a js file but also it could be an mdx file, so we're gonna add that or operator in there.

[00:03:08] Select by stories ending in js or mdx and let's render those, and this extension, this file extension will be MDX, so buttons.stories.mdx. So now we can actually use markdown to create documentation for our components. Every time you add an on on, you're gonna have to restart your dev server, it's very unfortunately, especially given that my computer is very slow today.

[00:03:35] Okay, so once you have npm-installed this addon-docs, we actually need to go and add it to our main.js file inside of this addons array. So this one's special, we wanna give it an option and this options configureJSX: true, just telling it basically that hey if we have JSX go ahead and actually recognize that.

[00:03:57] So we add our addon-docs to the addons array, and then this is just some mark down. So this is gonna render our mark down files into nice documentation you can deploy and use with any stakeholder, they don't have to just be developer, they can be designer they could be product, okay?

[00:04:13] And when you run NPM run storybook, if everything works as expected, you should now see this. So taking a look at this real quick, on our dock site, we have a header just as here's what buttons are used for, this is where you would use them. And then we look down here and we have this preview element, preview is coming from our add-on that we just added.

[00:04:34] So it comes from add-on docs, and then we create a story, I'm giving this name of primary, it's our primary button. You can see here the other store names are gonna be secondary and tertiary. These names correspond to the tabs on the side, so whatever I change this to it'll update here.

[00:04:51] And, for whatever reason, let me see, You should have this secondary tab appear docs, this is what our add on just added for us is this document tab, right? So we can pair the side by side, we have our title here, so buttons, here's the text underneath that, our usage and all of that.

[00:05:13] You can even I like props table as well for all your components, and this actually, you can see this is the code for it, okay? So that was our first add-on docs, now what you'll notice though, that our buttons are not actually retaining any theme, right? We wanna be able to trigger that, so lets go add another two plug-ins,two add-ons, that are gonna allow us to pass our theme and simulate a theme.

[00:05:40] So, in your terminal were gonna install two more add-ons, Let me clear this so it's a little easier to read. So nom install and those are gonna be @storybook/addon-backgrounds. It's gonna allow us to change the background of our storybook, and @storybook/addon-contexts, just like that, okay? And anytime we add an addon we have to add it to the addon array inside of main.js, so while that is installing, Let's go ahead an add it here, I probably typed that wrong addon backgrounds, that's cuz backgrounds has an S, seems to be the theme today.

[00:06:32] Let's try that again, in the meantime, I'm gonna go add these, so @storybook addon-contexts, this needs to have a register at the end. So slash register we have to tell story about that we need to use this, okay? It's gonna be the same for background so I'm just gonna copy and paste that, this is just gonna be changed to backgrounds, so register both of those.

[00:07:00] Now, we actually need to create our context, so we've told story, but we want to add this plug in, let's tell it what we want it to do, you can use this for language if you wanna change the language of your application, we're gonna use it for theme.

[00:07:10] So let's create a new file called context.js, and we're gonna import a couple of things, first is { ThemeProvider } from 'styled-components'. The second is our themes we need to actually pass our theme so import, defaultTheme and darkTheme from our utils folder. And then we're just gonna export an array of different like properties, and it's gonna be an array of objects.

[00:07:42] So each object has a different configuration, so export const context = { } array so you can have multiple contexts we're just gonna have one, it's gonna be an object We can set icon this one's gonna be shown in the toolbar, don't need to set that it's really not useful right now.

[00:08:04] For title we wanna give it themes as our color theme, for components, we're gonna be using theme provider that's gonna go into an array. And now we need to give it some parameters, so params, what do we need this theme provider to kind of switch between. So the first we're gonna call default theme, that's the name of it that'll show up in the toolbar, and the property, ThemeProvider needs a theme.

[00:08:32] So this will be our defaultTheme, and optionally, we can pass just one more argument default: true. So this will be what it's originally set to, And we're gonna do the same for dark theme so this would be dark theme the props this will set the theme to dark theme, and that's it.

[00:08:52] So those are our parameters, I think I messed up a bracket, Where did I mess it up? Okay, I have a couple too many, Theme: defaultTheme.
>> Left of default.
>> Left of default here? Wait, Yeah, yeah you're totally right thank you. That should not be closed there, there we go, when it auto like pretties you're like, yeah, I'm good, awesome.

[00:09:33] We're just gonna set like two more options down here, so right after the params array here, add one more object, just the options. So deep true, this is gonna say hey, we need to pass this property all the way through every child component, so pass our theme all the way through every single component.

[00:09:57] Disable, we don't want this to be disableable, that's the word today and cancelable: False. So this is not gonna be optional, so someone brought up a really good point that I made a mistake. I actually forgot to wrap my dark theme within context.js in curly brackets, so make sure that those are wrapped.

[00:10:19] And inside of preview.js, make sure your backgrounds has an s, cuz I did just make that mistake and it didn't actually work, okay? So now we have our context, and we can actually pass this, So we need to make one more file in our storybook folder to get this to work, it's gonna be called preview.js.

[00:10:42] And this is where we're gonna configure all of our like decorators, so a decorator is gonna be what we use with our addons. So let's say we're gonna import [addParameters] from 'storybook/react', this will all make sense in a second once we get these parameters. Add decorator, that's coming from the same place, I'm gonna combine those, Import with contexts, so we need to actually pass our context to our decorator.

[00:11:18] This is coming from '@storybook/addon-contexts/react'; cuz this is a react application. And let's just import that context we just made { contexts } from 'contexts';. Cool, so the first parameter we wanna add is our background, so let's do addParameters {( so what do we want to set a dark background when we have our default theme so we can see our components and we wanna set a light background when we have our dark theme components.

[00:11:52] So, backgrounds: [ it's gonna be an array, so {}name:'Default theme', is going to have a value: '#ffffff' of white, so when our components are dark colored, we want that on a white background so we can see them. And this is gonna be the default value, so we'll set default again to true},.

[00:12:12] And the other is just gonna be the 'Dark theme', so when our components are in their dark theme, let's set the background to a Dark Blue #050449. And the only other thing that we need to do to get this to work is just add a decorator We want to actually use our theme now.

[00:12:37] So with contexts and pass it the context we just made, So whenever you add an addon, you're going to actually have to restart your storybook server. So make sure you stop and restart it, and when you do, you should have these two up here, these two little icons are very tiny, the first one on the left is going to be our theme.

[00:12:59] So if we change to a dark theme our components disappear and they have our dark theme. Obviously we can't see them that's why we also need to change our background, so there we go. Now we actually can see our components dark theme, and you can do this for any theme that you have.