What Is a Story?

Purpose and Scope

A story is the smallest useful unit of authoring in Storybook: it captures the rendered state of a UI component. Instead of opening an entire application and navigating to the screen where a component happens to appear, developers write separate stories for the interesting states that component supports. The getting-started flow introduces this idea with the example Button, Header, and Page components created by the installation CLI, then uses the Button to show how a single component state becomes visible, editable, and testable in the Storybook UI.

Sources: docs/get-started/whats-a-story.mdx

This page is for readers who have installed Storybook and need the mental model required before writing their own story files. It explains what a story represents, where the examples appear in the sidebar, how arguments connect story data to rendered output, and how the authoring workflow changes slightly by renderer. It does not try to document the full Component Story Format reference; instead, it prepares you to recognize a story file, create a first state, and use Storybook’s UI to refine that state while developing a component in isolation.

Sources: docs/get-started/whats-a-story.mdx

Relevant Source Files

• docs/get-started/whats-a-story.mdx — Defines a story as a rendered component state, introduces the installed Button, Header, and Page examples, explains story file suffixes, describes CSF and Svelte-specific story formats, and outlines the early workflow for viewing, editing, and creating stories.

Story as Component State

A story should be read as an example of one component under one named condition. The source documentation phrases this as rendering the Button in its primary state and exporting a story called Primary. That naming pattern matters because stories are not arbitrary screenshots; they are reusable examples that Storybook can browse, document, and connect to addon panels. When a component has multiple meaningful modes, such as default, primary, disabled, loading, empty, or error, each mode can become its own story so the team can review behavior without rebuilding the surrounding application.

Sources: docs/get-started/whats-a-story.mdx

Story files live behind the UI that readers browse after installation. For most renderers in this getting-started page, stories are written in Component Story Format, an ES modules based standard for component examples, and the files end with .stories.js or .stories.ts. The Svelte branch calls out an additional possibility: stories may be written in standard CSF or with Svelte native template syntax through Svelte CSF. In both cases, the developer-facing goal remains the same: keep the example close enough to code that it can evolve with the component while remaining easy to discover in Storybook.

Sources: docs/get-started/whats-a-story.mdx

Args, Controls, and Actions

The Button example introduces arguments, usually called args, as the values that make a rendered state concrete. The documentation points out that values specified in args are used to render the component and match the values shown in the Controls panel. That relationship is central to the authoring model: a story is not only a static sample, but a configured render where inputs can be inspected and adjusted. For a new author, the practical rule is to express the state you care about as story data first, then let Storybook show the result in the canvas.

Sources: docs/get-started/whats-a-story.mdx

Args also create the bridge between story authoring and Storybook Essentials. The page notes two immediate benefits in the Button example: callbacks are logged in the Actions panel, and arguments are dynamically editable in the Controls panel. This means a Button story can demonstrate both appearance and interaction without requiring a custom demo application. You can click the rendered Button to see callback activity, then adjust controls to explore alternative labels, variants, or flags. Once those values represent a useful state, they can become the basis for another named story.

Sources: docs/get-started/whats-a-story.mdx

Working with Stories

The working model is intentionally tight: Storybook lets you focus on one component in one state at a time, and when you edit either the component code or its stories, the browser re-renders without a manual refresh. That feedback loop is why stories are useful during implementation rather than only after a component is complete. You can start with a basic story, change the component, adjust its arguments, and immediately verify whether the primary, secondary, disabled, or other states still render correctly. The story becomes the repeatable workspace for a specific UI condition.

Sources: docs/get-started/whats-a-story.mdx

When a component has no stories yet, the page describes two creation paths depending on the renderer. In React, the sidebar includes a plus button flow that can search for a component and create a basic story. In other renderers, and as a general recommendation, the docs suggest creating a story file next to the component source by copying an existing story file and adjusting it for the new component. For Svelte template syntax, the automatic creation feature is called out as unsupported unless the project opts into Storybook’s Component Story Format.

Sources: docs/get-started/whats-a-story.mdx

Source-to-Workflow Mapping

The getting-started page maps each concept to a reader action. First, identify the example components that the CLI generated, such as Button, Header, and Page. Second, open a story from the sidebar and inspect how its configured values produce the rendered component. Third, use the Controls and Actions panels to understand the connection between inputs, callbacks, and the live preview. Fourth, create or copy a story file for your own component. Finally, continue by modeling additional interesting states rather than trying to represent every possible application route in one large example.

Sources: docs/get-started/whats-a-story.mdx

This framing also explains why story names are important. A story named Primary is not merely a variable name; it becomes the label for a state that designers, developers, QA engineers, and documentation readers can discuss. By keeping each story narrow, teams build a catalog of component behavior that can later feed documentation, interaction tests, accessibility checks, and visual review. The first story you write should therefore be simple and representative. After that, add states that reveal decisions or risks: alternative content, missing data, selected states, validation errors, loading indicators, or disabled interactions.

Sources: docs/get-started/whats-a-story.mdx

Next Steps

After understanding the story model, continue to the pages that explain the mechanics in depth. Read Component Story Format when you need the export structure and portable story conventions. Read Args and Arg Types to understand how story inputs become controls and documentation tables. Read Controls and Actions when you want richer interactive panels for editing values and observing callbacks. If you are working in Svelte, pay attention to the distinction between standard CSF and Svelte CSF before relying on UI-assisted story creation. The immediate next task is to open an existing story, change one argument, and save a new state only when it communicates a real component behavior.

Sources: docs/get-started/whats-a-story.mdx