Using Storybook Controls Addon for Live Prop Editing

Live prop editing with Storybook Controls

Storybook’s Controls addon lets you change a component’s props in the UI without reloading the story, giving instant feedback while you experiment with different states. This guide shows the minimal setup, a worked CSF story example, the limits of the addon, and frequent pitfalls to avoid.

Install and register the addon

Run the installation command in your project root (you need write access to the node_modules folder):

npm i -D @storybook/addon-controls

Then edit .storybook/main.js to add the addon to the addons array (and to presets if you use the preset‑based setup):

module.exports = {
  addons: ['@storybook/addon-controls'],
  // optional preset for TypeScript projects
  presets: [require.resolve('@storybook/preset-typescript')],
};

Write a CSF story that uses args

Controls reads the args object of a story and renders editable fields for each plain‑JavaScript property. Here is a simple button component story:

import { Button } from './Button';

export default {
  title: 'UI/Button',
  component: Button,
};

export const Primary = {
  args: {
    label: 'Click me',
    onClick: () => alert('clicked'),
  },
};

When Storybook starts, the Controls panel appears in the right‑hand sidebar. The label shows as a text input, and onClick> shows as a button that triggers the alert when clicked.

How Controls appear and work

• Storybook loads the addon during startup.
• The addon scans the story’s args and builds a UI control for each property that is a plain JSON‑compatible value (string, number, boolean, enum, etc.).
• Changing a control updates the args object, which Storybook passes to the component, causing an instant re‑render.

Limitations and things to watch

• Controls only works with plain JavaScript objects. Functions, class instances, or circular structures may be ignored or cause errors.
• Storybook 6.0 or newer is required; older versions lack the Controls API.
• When using TypeScript, you must enable the typescript preset (or manually define argTypes) so Controls can infer prop types from interfaces.
• Over‑reliance on Controls can hide prop‑type mismatches that would be caught by unit tests or TypeScript checks.

Common mistakes and how to fix them

• Forgot to register the addon: The Controls panel will not appear. Verify that @storybook/addon-controls is present in the addons array of .storybook/main.js.
• Using an outdated Storybook version: Run npm list storybook and ensure the version is >=6.0. Upgrade with npm i -D @storybook/*@latest if needed.
• Manual argTypes mismatch: If you define argTypes that conflict with the actual args, Controls may show the wrong control type. Keep argTypes in sync or omit them to let Controls infer from args.
• Using complex prop values: Passing a function as a prop works for the component, but Controls will render it as a non‑editable placeholder. For live editing of callbacks, wrap them in a mock function in args and test the call separately.

Verification steps

1. Start Storybook: npm run storybook (or yarn storybook).
2. Open the story for the component you just added.
3. Look for the Controls sidebar on the right. You should see editable fields matching the args properties.
4. Change a value (e.g., edit the label text field) and confirm the rendered button updates instantly.
5. Open the browser developer console and verify there are no errors related to @storybook/addon-controls.

Practical way to confirm it works

After performing the steps above, try toggling a boolean prop or selecting a value from a dropdown control. The component should reflect the change without a full page reload. If the UI does not update, re‑check the console for messages like "Cannot find addon @storybook/addon-controls" or "Invalid argType" and correct the configuration accordingly.