Diagnosing Storybook Controls That Don’t Update the Story

Recognizable condition

When you open a story in Storybook, the Controls panel lists the component’s props and lets you change their values. However, adjusting a slider, typing in a field, or toggling a switch does not cause the rendered story to update; the component stays static despite the UI indicating interaction.

Cause / diagnostic table

Possible cause	What to look for
Missing or incomplete argTypes	Story exports only args (or nothing) and no explicit argTypes; Storybook may warn about missing definitions.
Decorator hard‑coding props	A decorator returns a wrapped story with static props that override the args passed from Controls.
Controls disabled via parameters	Story or global parameters contain { controls: { disable: true } } or { parameters: { controls: false } }.
Storybook version < 6.0	Using an older Storybook release where the Controls addon behaves differently or requires manual registration.

Ordered checks

1. Verify args/argTypes export

   Open the story file (e.g., Button.stories.js) and ensure it either returns an args object or defines argTypes that match the component’s props.

   export default {
     title: 'Example/Button',
     component: Button,
     argTypes: {   // optional if args are returned
       label: { control: 'text' },
       primary: { control: 'boolean' },
       size: { control: { type: 'select', options: ['small', 'medium', 'large'] } }
     },
   };
   
   export const Primary = { args: { label: 'Button', primary: true, size: 'medium' } };
   

2. Check the browser console

   Look for warnings such as "Missing argTypes for …" or "Controls are disabled for this story." Their presence points to a configuration gap.

3. Inspect decorators

   If you use a decorator (global or per‑story), temporarily comment it out and see if controls start working. A decorator like the following overrides args:

   export const decorators = [
     (Story) => <div style={{ padding: '20px' }}><Story /></div>,
     // problematic: hard‑coded props
     (Story) => <Story label="Fixed" />
   ];
   

4. Review story parameters for controls disable flags

   Search for parameters objects in the story or in preview.js that set controls: { disable: true } or controls: false.

5. Confirm Storybook version and preset

   Run npm list @storybook/react (or the appropriate framework package) and ensure the version is 6.x or later. If you are not using the @storybook/addon-essentials preset, make sure @storybook/addon-controls is explicitly added to main.js.

   // .storybook/main.js
   module.exports = {
     addons: [
       '@storybook/addon-essentials', // includes controls
       // or explicitly:
       // '@storybook/addon-controls',
     ],
   };
   

Fixes tied to findings

• Add or complete argTypes

  If the story only returns args, you can rely on Storybook’s automatic inference (CSF3). Ensure you are using CSF3 syntax; otherwise, explicitly define argTypes for each prop.

• Adjust or remove overriding decorators

  Remove any decorator that hard‑codes props, or modify it to spread the incoming story args:

  export const decorators = [
    (Story) => <div style={{ margin: '20px' }}><Story /></div>,
    // now passes through args
    (Story) => <Story {...Story.parameters?.args || {}} />
  ];
  

• Enable controls in parameters

  Delete or set controls: { disable: false } (or simply omit the controls key) in the story’s parameters block or in global preview.js.

• Upgrade Storybook

  If you are on a version < 6.0, follow the official migration guide to upgrade to 6.x (or the latest 7.x). After upgrading, restart the Storybook dev server.

• Restart Storybook after changes

  Stop and start npm run storybook (or equivalent) to ensure the updated configuration is loaded.

Escalation criteria

If you have completed all checks and applied the corresponding fixes yet the controls still do not affect the story:

1. Create a minimal reproduction: a fresh Storybook project with only the problematic story and its component.
2. Verify that no other addon (e.g., @storybook/addon-actions) is interfering with args by temporarily disabling them.
3. Consult the version‑specific migration guide for any breaking changes in the Controls addon.
4. Open an issue in the Storybook repository, attaching the minimal reproduction and your Storybook version.

Verification

After applying a fix, reload the story, manipulate a control, and confirm the component updates instantly. The browser console should show no warnings about missing argTypes or disabled controls.