Storybook is all about writing stories. A story usually contains a single state of one component, almost like a visual test case.
Typically you see Storybook used for React or other frameworks, but the library has recently introduced the option to use HTML for your Storybook projects. As a prototyping tool or playground this is great! No larger scale knowledge of other frameworks needed.
Run the following in a directory that you would like to install Storybook in - it will add a set of boilerplate files for your Storybook project:
npx -p @storybook/cli sb init --type html
This will take a while to pull down assets and compile.
If you run into issues see manual setup here: Storybook HTML docs
After install has completed run:
npm run storybook
And boom! You're up and running. If the site doesn't launch for you, check out http://localhost:6006 to see Storybook in action.
Check out the demo in your browser. Included by default we can see demo component represented with header and button stories. Any useful tools you already notice?
Now let's take a look at the code. Fire up your favorite IDE and open the project root. Take a look inside .stories/index.stories.js. Within you will find that that component and the two stories that have been pre-created.
The docs obviously provide more detail - but a brief overview will show there are simply a adding storiesOf() is a reference to the component and then individual stories are chained together.
Every story returns the HTML to be rendered - or in the case of the .button the JS which creates the button and attaches a click handler to log the output.
Let's add a callout (my own term) - a component that is intended to call a users attention to informational content.
This is what it looks like. It's pretty ugly.
Let's simply create a new component hierarchy using storiesOf() and add some HTML.add the following to the stories.js file
storiesOf('Callout', module)
.add('default', () => '<div class="callout"><p>Important information</p></div>')
Hot reloading is in effect - so we should see the component and story right away!
What if we wanted to represent more than just a default representation for a callout. Say a callout which represents an error? What might that look like? Add the story for this with some HTML which might represent that differently.
For example:
add('default', () => '<div class="callout -error"><p>Important information oops an error</p></div>')
Now let's add a few styles that will help us define the visual look of our callout.
Add a new file at the root of the project: ./styles.css
Add some styles!
.callout {
font-size: 2em;
background-color: orange;
}
Go crazy - add whatever you would like.
Go back to your ./stories/index.stories.js and make sure to import the CSS at the top of the page via:
// from local path
import './../styles.css';
Let's add that variation for the callout error. What might it look like? Here's an example:
.callout.-error {
background-color: red;
}
Now we have our own HTML stories added - one would be the default story for a callout, and the other the error state would represent the additional story.
A lot of the power of Storybook is in add-ons. There are a ton of things to add that can help teams and developers. Copying source code for reuse, accessibility, notes, and the ability to set dynamic content.
Let's install an add-on for accessibility. In your Terminal run:
npm install @storybook/addons @storybook/addon-a11y
We then need to import those add-ons in a file Storybook expects so that when the app gets booted the right add-ons are imported.
Go into ./storybook in your project root and add addons.js. Storybook looks for this file to exist so you can register your add ons. Add the following:
import '@storybook/addon-a11y/register';
Restart Storybook (Ctrl-C and then npm run storybook) to get the new add on imported. Then we want to add the accessibility add on in as a decorator.
Open up ./stories/index.stories.js and add at the top of the file:
import { storiesOf, addDecorator } from '@storybook/html';
import { withA11y } from '@storybook/addon-a11y';
addDecorator(withA11y)
Check out your Storybook instance. Accessibility information now shows in the bottom pane!
How can we break accessibility.. give it a try!
This demo shows simple HTML use cases in isolation - the main intention is to usually add Storybook to an existing project. For React you would you would develop a component as you normally would and then simply create a .storybook folder alongside your component and import into whatever story you would like to create. This would then be added to your Storybook component playground!
I believe the add-on itself has TypeScript support. Creating stories themselves though shouldn't required TS in any sense.
Here's what I see in the add-on directory: https://github.com/storybookjs/storybook/tree/master/app/html