Args and Arg Types

Purpose and Scope

Args are the public story inputs that let Storybook render a component in a particular state. Arg types describe those inputs: their value constraints, display names, documentation text, table metadata, control widgets, conditional visibility, and mappings between user-friendly options and rendered values. This page focuses on the API namespace for argTypes, while still explaining how it relates to everyday story authoring with args and the Controls and Docs experiences. Treat args as the values that change, and argTypes as the schema-like metadata that tells Storybook and addons how to present, validate, and document those values.

Sources: docs/api/arg-types.mdx

The repository documentation defines ArgTypes as metadata that specifies the behavior of args. That distinction matters because many Storybook features do not need to know a component framework directly; they need a normalized description of the component inputs. A control panel can choose a color picker, a generated table can show a description and default value, and docs can display categories or type summaries because argTypes gives addons a shared vocabulary. Manual entries can enrich or override inferred entries when static analysis cannot fully express the product-facing API you want readers to see.

Sources: docs/api/arg-types.mdx

Relevant Source Files

• docs/api/arg-types.mdx - Defines the public ArgTypes documentation page, including the relationship between args and argTypes, automatic inference, manual declaration locations, and the documented TypeScript shape of the argTypes object.

Core Primitives

The first primitive is an arg: a named value used by a story when rendering a component state. The second primitive is an arg type: an object keyed by the same arg name that explains how Storybook should understand that value. The docs explicitly connect argTypes to args and to addons that consume arg metadata, with Controls as the clearest example. If an arg represents backgroundColor, its arg type can tell Storybook to display a color UI instead of a generic text input, while still allowing the story to receive the resolved arg value.

Sources: docs/api/arg-types.mdx

The third primitive is the rendered ArgTypes or Controls table. The documentation describes the ArgTypes doc block as the most concrete realization of argTypes, with each table row corresponding to a single argType and the current value of that arg. This means argTypes is not only a configuration object for live editing. It is also documentation data. A well-maintained arg type can improve the authoring UI, generated docs, and the communication between component maintainers and consumers at the same time.

Sources: docs/api/arg-types.mdx

Automatic Inference and Manual Overrides

Storybook can infer argTypes when the Docs addon is enabled and the CSF meta default export identifies a component. The docs describe this as framework-aware static analysis: React uses react-docgen by default or react-docgen-typescript; Vue uses vue-docgen-api; Angular uses Compodoc; Web Components use custom-element.json; and Ember uses YUI doc. The important implementation contract for users is that the resulting structure is designed to match those tool outputs, so inferred props, descriptions, and types can be surfaced without hand-authoring every field.

Sources: docs/api/arg-types.mdx

Manual argTypes are still a normal part of authoring. The docs state that properties specified manually override inferred values, which lets teams correct static analysis, add addon-specific behavior, or make documentation more product-oriented. The page shows three scopes: component-level argTypes in the CSF meta default export, project-level argTypes in preview.*, and story-level argTypes attached to a specific story. Choose the narrowest scope that matches the behavior. Global entries are useful for shared conventions; component entries document a component contract; story entries should be reserved for state-specific differences.

Sources: docs/api/arg-types.mdx

API Reference

The documented argTypes value is an object whose keys match arg names. Each key maps to metadata consumed by Storybook and addons. The top-level fields include control, description, if, mapping, name, options, table, and type. Several fields are specifically relevant to generated documentation: description supplies explanatory text, name can change the displayed label, and table can group rows, show default values, summarize types, or disable an arg in the docs table. Controls-related fields shape the interactive UI shown beside a story.

Sources: docs/api/arg-types.mdx

{
  [key: string]: {
    control?: ControlType | { type: ControlType; /* See below for more */ } | false;
    description?: string;
    if?: Conditional;
    mapping?: { [key: string]: { [option: string]: any } };
    name?: string;
    options?: string[];
    table?: {
      category?: string;
      defaultValue?: { summary: string; detail?: string };
      disable?: boolean;
      subcategory?: string;
      type?: { summary?: string; detail?: string };
    };
    type?: SBType | SBScalarType['name'];
  }
}

Authoring Flow

Start with inferred argTypes whenever your framework integration can analyze component metadata. Add the component to the CSF meta export so Storybook has a source for extraction, then inspect the generated Args or Controls table in docs. If the generated table is accurate, avoid duplicating metadata. If the table lacks a description, uses an unhelpful control, or exposes implementation details, add a manual argTypes entry at the component level. This keeps the source of truth close to the stories while preserving automatic behavior for the rest of the component API.

Sources: docs/api/arg-types.mdx

Use story-level argTypes for intentional exceptions. For example, a component might expose the same variant arg across all stories, but one scenario could limit available options to demonstrate a constrained design system context. Use project-level argTypes in preview.* for recurring shared args, such as a global convention that many stories use. Because manual properties override inferred values, partial overrides are practical: you can keep inferred type information while adding only a control type, table category, description, or display name where the generated output needs refinement.

Sources: docs/api/arg-types.mdx

Addon and Documentation Integration

ArgTypes are deliberately addon-facing. The docs call out Controls as an addon that uses argTypes to decide how an arg should be edited, and the ArgTypes doc block as the visible table that turns arg metadata into documentation. This makes argTypes a bridge between story execution and the manager UI. A story can render from plain args, while addons use the argTypes layer to build a form, show documentation, filter rows, or attach richer semantics to values that would otherwise just be JavaScript data.

Sources: docs/api/arg-types.mdx

When writing reusable story files, prefer argTypes that describe the component's public API rather than the internal implementation. A table category can organize related inputs, a default value summary can explain what the component assumes, and mapping can hide complex objects behind stable option labels. Conditional fields are useful when a control should only make sense in a particular state. These choices improve the experience for developers browsing stories, designers reviewing variants, and documentation readers trying to understand which inputs are safe to change.

Sources: docs/api/arg-types.mdx

Next Steps

To apply this API, open the CSF file for a component and compare its generated controls table with the intended component contract. Add component-level argTypes only where inference needs help, then use story-level overrides for scenario-specific controls. If your goal is live editing, continue with Controls. If your goal is generated reference documentation, continue with Autodocs, DocsPage, and doc blocks. If your goal is broader story structure, review Component Story Format and the Args guide before adding more metadata.