Originally published at https://practicaldevblog.blogspot.com/2026/11/storybook-react-component-workshop.html
Quick answer
Storybook React is a workshop that renders components on their own, outside your app, so you can see every state of a button, card, or badge without clicking through pages. You install it with npx storybook@latest init, write a story file next to each component, and open the workshop at localhost:6006. It pays off once a component has more than a couple of states, or someone else needs to see what it looks like.
You open your app to check a small change to an order badge, five clicks deep. You log in, find the order, and only then see the colour. Change one prop and you repeat the whole trip. Multiply that by five states and a ten-minute tweak turns into an afternoon of clicking. That is the problem Storybook solves. It takes the component out of the app and puts it on a bench, where you flip through its states. This post sets it up in a fresh Vite and React project, builds one real badge, and shows what breaks.
What I would check before using it
My first check is how many states the component has. A badge with five statuses earns its own workshop page, because testing each state in the full app means five different orders and five page loads. A heading with one fixed look does not, and a story for it is just overhead.
My second check is who else needs to see the component. Storybook doubles as a living catalogue, so a designer or teammate can open the badge, flip its status control, and confirm the colours without running the app. If you work alone, that audience does not exist yet, and the value drops.
My third check is the cost of keeping stories honest. A story is only useful while it matches the component, and a prop rename nobody updates in the story leaves a page that lies. I would want the type checker running over story files in CI, so a renamed prop fails the build instead of showing stale output. The demo below caught exactly that.
My fourth check is the test story. Storybook is not a replacement for unit tests. A story shows the badge; a test proves it renders the right label. The Vitest post shows how fast those tests run. Jest covers the same ground if that is what your project already uses.
My verdict, as judgement: adopt Storybook React when a component has several visual states, or when others need to review how it looks without running the app. Skip it for a one-off page or a prototype you will throw away. The recommendation flips the moment stories stop being maintained, because stale pages mislead faster than none.
One order badge, run end to end
The example is a badge from a small online shop in Karachi. An order has an id, a status, an item count, and an expected delivery date. Order PK-1042 has three items, status shipped, expected 18 Nov 2026. That is real data from the demo cart, not a textbook counter.
type OrderStatus = "placed" | "packed" | "shipped" | "delivered" | "cancelled";
const STATUS_LABELS: Record<OrderStatus, string> = {
placed: "Order placed",
packed: "Packed and ready",
shipped: "On its way",
delivered: "Delivered",
cancelled: "Cancelled",
};
const STATUS_COLOURS: Record<OrderStatus, string> = {
placed: "#2563eb",
packed: "#d97706",
shipped: "#7c3aed",
delivered: "#15803d",
cancelled: "#b91c1c",
};
export interface OrderStatusBadgeProps {
orderId: string;
status: OrderStatus;
itemCount: number;
expectedDate: string;
}
export function OrderStatusBadge({ orderId, status, itemCount, expectedDate }: OrderStatusBadgeProps) {
const label = STATUS_LABELS[status];
const colour = STATUS_COLOURS[status];
const itemWord = itemCount === 1 ? "item" : "items";
return (
<div style={{ border: `2px solid ${colour}`, borderRadius: "10px", padding: "16px", maxWidth: "340px", fontFamily: "system-ui, sans-serif" }}>
<span style={{ backgroundColor: colour, color: "#ffffff", borderRadius: "999px", padding: "4px 12px", fontSize: "14px", fontWeight: 600 }}>
{label}
</span>
<p style={{ margin: "12px 0 4px", fontWeight: 700 }}>Order {orderId}</p>
<p style={{ margin: 0, color: "#444444" }}>
{itemCount} {itemWord} - expected {expectedDate}
</p>
</div>
);
}
The story file sits next to the component and declares one story per state:
import type { Meta, StoryObj } from "@storybook/react-vite";
import { OrderStatusBadge } from "./OrderStatusBadge";
const meta = {
title: "Shop/OrderStatusBadge",
component: OrderStatusBadge,
tags: ["autodocs"],
argTypes: {
status: {
control: "select",
options: ["placed", "packed", "shipped", "delivered", "cancelled"],
},
},
} satisfies Meta<typeof OrderStatusBadge>;
export default meta;
type Story = StoryObj<typeof meta>;
export const Shipped: Story = {
args: {
orderId: "PK-1042",
status: "shipped",
itemCount: 3,
expectedDate: "18 Nov 2026",
},
};
export const Delivered: Story = {
args: {
orderId: "PK-1038",
status: "delivered",
itemCount: 1,
expectedDate: "14 Nov 2026",
},
};
export const Cancelled: Story = {
args: {
orderId: "PK-1045",
status: "cancelled",
itemCount: 2,
expectedDate: "17 Nov 2026",
},
};
The thing that went wrong was a small slip in the Shipped story: I typed state: "shipped" instead of status: "shipped". The type checker caught it at once:
src/components/OrderStatusBadge.stories.tsx(22,5): error TS2353: Object literal may only specify known properties, and 'state' does not exist in type 'Partial<{ orderId: string; status: OrderStatus; itemCount: number; expectedDate: string; }> & { orderId: string; status: OrderStatus; itemCount: number; expectedDate: string; }'.
The fix is one word: rename the arg to status. This is exactly why stories should be type-checked. Storybook's build uses esbuild and does not type-check, so without the tsc step this typo would have shipped silently and rendered with no status at all. After the fix, the type check and the Vitest render test both pass, and the build succeeds:
Rendered OrderStatusBadge for order PK-1042:
<div style="border:2px solid #7c3aed;border-radius:10px;padding:16px;max-width:340px;font-family:system-ui, sans-serif"><span style="background-color:#7c3aed;color:#ffffff;border-radius:999px;padding:4px 12px;font-size:14px;font-weight:600">On its way</span><p style="margin:12px 0 4px;font-weight:700">Order PK-1042</p><p style="margin:0;color:#444444">3 items - expected 18 Nov 2026</p></div>
---
Test Files 1 passed (1)
Tests 2 passed (2)
--- storybook build ---
Vite built in 2.66s
Storybook build completed successfully
The built output lists four entries, the docs page plus the three stories, proving Storybook picked up the file, and the dev server answered HTTP 200 at localhost:6006. If you style the badge with utility classes, the same isolation trick works for a Tailwind CSS component, and the component's state handling follows the same rules as the React useEffect post. TypeScript is what made the typo a build error instead of a silent bug.
Common mistakes and how to fix them
First, naming a story arg that does not match a prop, like the state slip above. The symptom is a story rendering with a missing value, or a type error from the checker. The fix is to rename the arg to match the prop, and to run tsc over your story files, because the Storybook build alone will not catch it.
Second, putting stories in a folder Storybook does not scan. The symptom is an empty sidebar: the workshop starts fine, but your component never appears. The fix is to check the stories glob in .storybook/main.ts and confirm your file matches it.
Third, writing stories that depend on app state, like a logged-in user or a router. The symptom is a story that crashes with "useNavigate may be used only in the context of a Router" or renders a blank page. The fix is to keep components pure where you can, and wrap the story in a decorator that provides the router or context it needs.
Frequently Asked Questions
Does Storybook ship to production with my app? No. It is a development tool with its own build, and your app bundle never includes the stories. You can deploy the static build separately as a shared catalogue.
Do I need a separate story for every state? Not for every tiny variation, but one per state that changes how the component looks. A badge with five statuses deserves five stories, so you can see each one without staging five orders.
Can I use Storybook with plain JavaScript instead of TypeScript? Yes, the same story format works in .jsx files. You lose the type checking that caught the arg typo here, so check arg names by hand.
Does Storybook replace unit tests? No. Stories show the component; tests prove it behaves. This post does both, and the Vitest run above is the proof.
What to remember
- One story per visual state, so every variant is one click away.
- Run tsc over story files, because the Storybook build does not type-check.
- Keep stories next to their components, so a prop rename is visible in the same folder.
- Pair stories with a render test, because a story shows the component and a test proves it.
- Share the static build as a catalogue when designers need to see components without running the app.
Where this leaves you
Storybook earns its place the moment a component has more states than you can comfortably reach inside the running app. The badge demo proved the two things that matter: the workshop builds and serves all three stories, and the type checker catches a mistyped arg before it goes silent. Seeing every state, plus a safety net for typos, is the whole point. Set it up with one command, write one story per state, and type-check in CI. If the stories stay current, the workshop saves a click-through every time a component changes. If they go stale, delete them, because a lying catalogue is worse than none.
Further reading
- Storybook docs, getting started, https://storybook.js.org/docs/
- Storybook docs, writing stories, https://storybook.js.org/docs/writing-stories
- Vitest Explained: Tests That Finish Before You Blink, https://practicaldevblog.blogspot.com/2026/11/vitest-explained-tests-that-finish.html
- Jest Explained: Testing JavaScript Without the Setup Headache, https://practicaldevblog.blogspot.com/2026/10/jest-explained-testing-javascript.html
- Tailwind CSS Explained: Styling Without Leaving Your HTML, https://practicaldevblog.blogspot.com/2026/10/tailwind-css-explained-styling-without.html
- React useEffect Explained: When to Use It and Skip It, https://practicaldevblog.blogspot.com/2026/10/react-useeffect-explained-when-to-use.html
- TypeScript Explained: Types That Catch Bugs Before They Run, https://practicaldevblog.blogspot.com/2026/10/typescript-explained-types-that-catch.html
- Figma Explained: The Design Tool Developers Actually Receive, https://practicaldevblog.blogspot.com/2026/10/figma-explained-design-tool-developers.html
Waqas Shahid is a software engineer from Karachi with more than 12 years of experience, including 6+ years in engineering leadership. He writes The Practical Developer.
Top comments (0)