Doc blocks for component documentation
🌱 This post is in the growth phase. It may still be useful as it grows up.
Storybook doc blocks help you document and share UI components with generated interface documentation, interactive playgrounds, and copy-pasteable source code.
Let’s take a look at all the doc blocks you can use to quickly document and share UI components.
Let’s dive in…
I’m working in a CSF file, using a custom docs page template.
Let’s start our component documentation with title and description.
First, import doc blocks from
(I’ll leave this import block empty — with the expectation that VS Code will import named exports as I use them.)
The Title component renderes a styled
Without props, it displays the auto-title or
title, defined in component
But it also accepts
children if you want to override that default.
The Description component renderes a styled
It displays the JSDoc comment, above the component declaration.
Earlier versions of
Description took a
children prop. But this option was deprecated in version 7.
Finally, the Subtitle component renders a styled
Without props, it displays the component meta value
And it accepts
children, for cust./om values.
The Title, Description, and Subtitle components make it possible to keep written documentation in sync with component source code!
How to generate documentation from source code, in Storybook.
Storbook isn’t just a stickerbook of visual components. You can display source code for every story. This makes it easy for teammates to copy and paste exactly the code they need.
The Story component (without props) displays your first story component directly into the document.
The Source component to display a copy-pasteable snippet of the code used to produce that story.
The Canvas component is like both
It wraps a story in a little box with a collapsable source code accordian.
All the these story components take an
of prop, where we can pass a story object.
In this file, we have a
So let’s add Story, Source, and Canvas, for the
Secondary story as well.
It would be a real slog to update our docs page template every time we add or remove Stories. So Storybook provides a Stories component that renders all of your stories with title and description.
The Story, Source, and Canvas components give you three different ways to display your components in documentation. And they make it easy for others to copy and paste precise component source code into their projects.
How to generate copy-pasteable source code and examples in Storybook.
How to generate interactive documentation with Storybook.
And the Primary component displays a full Storybook
Canvas, with the addition of these zoom and re-render buttons.
And it does so for only the first Story in Storybook.
It’s designed for use with interactive docs.
Table of component props generated by TypeScript and/or JSDoc comment Learn more in (linked video)
Like the ArgTypes table with an additional Control column Where component args are set up, Controls update the Story components above. Learn more about args and controls in (linked video)
The stories component renders all the stories contained in a story module — showing off all of the known permutations of your component. Each with the titles and descriptions of their stories.
I hope that you’re inspired to start communicating your components thru clear, interactive documentation, using Storybook and doc blocks.
The new reference docs on storybook.js.org are incredible. They go into details far beyond what we can cover in quick tips like this.
If you’d like to continue learning with me, check out one of these recent videos on related component documentation topics.
That’s it for today. I’m chantastic. I’ll see you in the next one. Bye!