Writing Stories Overview
Purpose and Scope
This page orients developers who are ready to move from installing Storybook to modeling component behavior as stories. In Storybook terminology, a story captures the rendered state of a UI component. The state is described with annotations and a set of arguments, or args, that correspond to framework-specific inputs such as React props, Vue props, Angular inputs, slots, styles, or similar component-facing data. The goal of the writing-stories section is to help you create small, repeatable examples first, then scale that same model to complex screens, decorators, data loading, and mocked integrations.
Sources: docs/writing-stories/index.mdx, docs/writing-stories/args.mdx
The workflow is intentionally development-only: a component’s story file lives next to the component file, but it is not part of the production bundle. Keeping stories beside the component makes each component’s examples discoverable for maintainers while allowing Storybook to list, render, document, and test them as separate states. A typical component folder contains the implementation and a matching story file such as Button.stories.js, Button.stories.ts, Button.stories.tsx, or a framework-specific equivalent.
Sources: docs/writing-stories/index.mdx
Relevant Source Files
- docs/writing-stories/index.mdx — Defines the reader-facing story model, where story files live, and the Component Story Format concepts used throughout the section.
- docs/writing-stories/args.mdx — Explains args as the main mechanism for describing component inputs, live editing stories, and composing state across stories.
- docs/writing-stories/decorators.mdx — Documents decorators, story context, and the provider or layout wrapping patterns used when a component needs a rendering harness.
- docs/writing-stories/loaders.mdx — Covers asynchronous loaders, loader inheritance, and why args remain the recommended default for story data.
- docs/writing-stories/build-pages-with-storybook.mdx — Shows how the same story model scales from atomic components to presentational pages, connected components, and screen-level composition.
- docs/writing-stories/mocking-data-and-modules/index.mdx — Provides the section entry point for mocking data and modules in the story-authoring navigation.
Core Story-Authoring Primitives
The central primitive is Component Story Format, commonly abbreviated CSF. For standard CSF files, the default export describes the component and provides metadata that Storybook and addons use to list and process stories. Named exports describe individual stories, and Storybook recommends UpperCamelCase names for those story exports. Svelte has an additional Svelte CSF path where defineMeta describes the component and a Story component describes individual examples, but the underlying idea is the same: metadata identifies the component, and stories identify important rendered states.
Sources: docs/writing-stories/index.mdx
Args are the next primitive because they let Storybook represent component inputs as a JSON-serializable object. Args can be attached at the story level, component level, or global level. Story-level args apply only to one state; component-level args establish defaults for every story in that file unless overridden; global args come from the project preview configuration and apply broadly. When an arg changes, Storybook re-renders the component, which is how UI features such as Controls can live edit examples without requiring changes to the component’s implementation.
Sources: docs/writing-stories/args.mdx
Decorators and loaders are supporting primitives for cases where args alone are not enough. A decorator wraps a story with extra rendering functionality, such as spacing, layout, theme providers, mock providers, or addon-specific instrumentation. A loader is an asynchronous function that runs before rendering and injects loaded data into the story context. The loaders documentation explicitly frames loaders as an advanced escape hatch and recommends args for story data when possible, because the Storybook ecosystem is built around the args model.
Sources: docs/writing-stories/decorators.mdx, docs/writing-stories/loaders.mdx
Story File Workflow
Start by placing the story file alongside the component so the example evolves with the implementation. The documentation’s folder sketch places Button.js, Button.ts, Button.jsx, Button.tsx, Button.vue, or Button.svelte next to a matching Button.stories.* file. That convention supports the everyday task: open a component, add or adjust its example states, and immediately see those states in Storybook. Because story files are development-only, they can import test data, mock fixtures, or helper wrappers that would not belong in a production bundle.
Sources: docs/writing-stories/index.mdx
Next, describe the component in the default export or equivalent framework-specific metadata. Storybook uses that metadata to list stories and provide information to addons. The docs also call out a build-time constraint: starting with Storybook 7.0, story titles are statically analyzed, so a default export needs a statically readable title or a component from which Storybook can compute an automatic title. If you customize a story URL with an id, that value also needs to be statically readable.
Sources: docs/writing-stories/index.mdx
Then export named stories that represent meaningful component states. A primary button, disabled button, long-label button, loading view, empty list, or error message are all examples of states that can be modeled with args. The writing-stories docs emphasize JavaScript object reuse and object spread for composing story args, which keeps similar examples close together without repeating the entire state object. When many stories share the same inputs, component-level args are the better default because they reduce repetition while still allowing each story to override the details that matter.
Sources: docs/writing-stories/args.mdx
Scaling from Components to Pages
The same approach works for pages and screens, but the tradeoffs become more visible as components move up the hierarchy. The pages guide distinguishes pure presentational pages from connected components. Presentational pages are easiest to render because all data can be encoded in args, and this integrates cleanly with other Storybook tooling such as Controls. This pattern encourages application code to keep data fetching and connected logic in a wrapper outside Storybook while the page component receives explicit inputs that stories can reproduce.
Sources: docs/writing-stories/build-pages-with-storybook.mdx
Args composition is especially useful for screen-level stories. If a screen combines a layout, a header, user details, and a list, the page story can reuse args from the subcomponent stories rather than duplicating all fixtures. The source docs describe this as a way to pick and choose realistic scenarios from existing component stories while keeping maintenance low. In practice, this means a team can build a catalog of reliable lower-level states, then assemble them into larger flows that remain understandable and editable.
Sources: docs/writing-stories/build-pages-with-storybook.mdx, docs/writing-stories/args.mdx
Connected components require a different plan because they depend on external data, modules, services, browser environment, or context. The pages guide points readers to several mocking layers: mocking imported modules, mocking network requests for REST or GraphQL APIs, and mocking providers that supply context. Decorators often participate in that provider case because they can wrap a story with the same context shape the app normally supplies. Loaders may also participate when a story must fetch or prepare external data before render, but they should be used deliberately.
Sources: docs/writing-stories/build-pages-with-storybook.mdx, docs/writing-stories/decorators.mdx, docs/writing-stories/loaders.mdx, docs/writing-stories/mocking-data-and-modules/index.mdx
System-to-Code Mapping
| Concept | What the reader does | Source-backed location |
|---|---|---|
| Story | Captures one rendered component state using annotations and args. | docs/writing-stories/index.mdx |
| CSF metadata | Describes the component for listing, addon processing, and static analysis. | docs/writing-stories/index.mdx |
| Named story export | Defines an individual state such as Primary or another UpperCamelCase example. | docs/writing-stories/index.mdx |
| Args | Supplies serializable component inputs at story, component, or global scope. | docs/writing-stories/args.mdx |
| Decorator | Wraps stories with layout, providers, or other rendering behavior. | docs/writing-stories/decorators.mdx |
| Loader | Runs asynchronous setup before a story and its decorators render. | docs/writing-stories/loaders.mdx |
| Page story | Composes lower-level story args into realistic screen scenarios. | docs/writing-stories/build-pages-with-storybook.mdx |
Execution Flow
A practical authoring loop begins with one component and one state. Create the story file next to the component, export component metadata, and add a named story with args that describe the first important visual or behavioral state. Run Storybook, inspect the rendered state, and use Storybook’s UI to adjust args where relevant. Once that baseline state is stable, add sibling stories for the other states that matter to design review, development, documentation, and testing.
Sources: docs/writing-stories/index.mdx, docs/writing-stories/args.mdx
As requirements grow, choose the smallest primitive that solves the problem. Prefer story or component args when you can express the state as component inputs. Add a decorator when the component needs a wrapper, provider, layout, or story-context-aware harness. Add a loader only when the story needs asynchronous setup that cannot be represented more simply. For pages, first decide whether the page can be presentational; if it can, compose args from child stories. If it is connected, mock imports, API services, or providers at the appropriate boundary.
Sources: docs/writing-stories/args.mdx, docs/writing-stories/decorators.mdx, docs/writing-stories/loaders.mdx, docs/writing-stories/build-pages-with-storybook.mdx
Next Steps
Read the focused pages in this section in the order that matches your current problem. Start with Component Story Format when you need exact story-file structure, then Args and Arg Types when you want editable state. Move to Decorators for providers and layout wrappers, Loaders for asynchronous setup, and Mocking data and modules when connected components need controlled dependencies. When you are ready to model full screens, use the building-pages guide to compose existing component stories into page-level scenarios instead of inventing a separate workflow.
Sources: docs/writing-stories/index.mdx, docs/writing-stories/args.mdx, docs/writing-stories/decorators.mdx, docs/writing-stories/loaders.mdx, docs/writing-stories/build-pages-with-storybook.mdx, docs/writing-stories/mocking-data-and-modules/index.mdx