storybook-addon-range-controls

Storybook Addon Range Controls

Storybook Addon Range Controls lets you discover layout issues by adjusting story args with sliders.

DEMO

Motivation

Originally, I used Storybook’s built-in argTypes with type: "range" sliders to check design variations.
This was great for interactively testing data growth and reduction.

However, setting it up often required extra boilerplate code.
For simple primitives like strings and numbers, it wasn’t a big issue, but for more complex structures—such as arrays of nested objects (e.g., tags inside a card)—I found myself writing the same setup code repeatedly.

That repetitive overhead was what motivated me to create this addon:
a simpler way to configure sliders for strings, numbers, image, and arrays to stress-test UIs more easily.

Installation

npm install --save-dev storybook-addon-range-controls

Then, register it as an addon in .storybook/main.js.

// .storybook/main.js

// Replace your-framework with the framework you are using (e.g., @storybook/react, @storybook/nextjs)
// Note: This addon currently supports React based Storybook projects.
import type { StorybookConfig } from "@storybook/react";

const config = {
  // ...rest of config
  addons: [
    "@storybook/addon-docs",
    "storybook-addon-range-controls", // 👈 register the addon here
  ],
};

export default config;

Usage

The primary way to use this addon is to define the range parameter. You can do this the component level, as below, to affect all stories in the file, or you can do it for a single story.

// Card.stories.ts

// Replace your-framework with the framework you are using (e.g., @storybook/react, @storybook/nextjs)
import type { Meta } from "@storybook/your-framework";

import { Card } from "./Card";

const meta: Meta<typeof Card> = {
  component: Card,
  parameters: {
    range: {
      // See API section below for available parameters
    },
  },
};

export default meta;

API

This addon contributes a range parameter to Storybook, defined using PropConfig objects.

export type StringPropConfig = {
  type: "string";
  min?: number;
  max?: number;
  step?: number;
  defaultChar?: string;
};

export type NumberPropConfig = {
  type: "number";
  min?: number;
  max?: number;
  step?: number;
};

export type ArrayPropConfig = {
  type: "array";
  min?: number;
  max?: number;
  step?: number;
  items?: PropConfig;
  defaultItem?: any | ((index: number) => any);
};

export type ImagePropConfig = {
  type: "image";
  width?: {
    min?: number;
    default?: number;
    max?: number;
    step?: number;
  };
  height?: {
    min?: number;
    default?: number;
    max?: number;
    step?: number;
  };
  src?: ({ width, height }: { width?: number; height?: number }) => string;
};

export type BooleanPropConfig = {
  type: "boolean";
};

export type EnumPropConfig = {
  type: "enum";
  selection?: "single" | "multiple";
  options?: string[] | number[] | { label: string; value: any }[];
};

export type ObjectPropConfig = {
  type: "object";
} & {
  [K in string as K extends "type" ? never : K]: PropConfig;
};

export type PropConfig =
  | StringPropConfig
  | NumberPropConfig
  | ArrayPropConfig
  | ImagePropConfig
  | BooleanPropConfig
  | EnumPropConfig
  | ObjectPropConfig;

export type PropConfigs = {
  [key: string]: PropConfig;
};

Configuration

The range parameter accepts the following configuration options.

type	description	options
string	Adjust string length via a slider	min, max, step, defaultChar
number	Adjust a numeric value via a slider	min, max, step
array	Adjust array length via a slider	min, max, step, items, defaultItem
image	Adjust image width/height via a slider	width, height, src
enum	Enum with single or multiple selection	selection, options
boolean	Toggle true/false	—
object	Nested fields, each defined by its own type	—

Common options (string, number, array)

key	type	default	description
min	number	0	Minimum value of the range
max	number	100	Maximum value of the range
step	number	1	Step interval

string only

key	type	default	description
defaultChar	string	"x"	Character used when padding length via slider

array only

key	type	description
items	PropConfig	Definition of element type.
defaultItem	any | (index: number) => any	Default element value. Can be fixed or generated by a function.

image only

key	type	description
width	{ min, default, max, step }	Slider settings for width. Defaults: default=300, min=50, max=800, step=1
height	{ min, default, max, step }	Slider settings for height. Defaults: default=200, min=50, max=800, step=1
src	({ width, height }) => string	Custom URL generator. Defaults to https://placehold.co/{width}x{height}

enum only

key	type	description
selection	"single" | "multiple"	Single or multiple selection
options	string[] | number[] | { label: string; value: any }[]	List of options. Supports arrays of label/value pairs

object only

Define nested fields, each with its own type:

{
  type: "object",
  name: { type: "string" },
  price: { type: "number" }
}

Examples

Configure range on a story (or per-file) to control strings, numbers, arrays, enums, booleans, and nested objects with interactive controls.

// Card.stories.ts
import type { Meta } from "@storybook/your-framework";
import { Card } from "./Card";

const meta: Meta<typeof Card> = {
  component: Card,

  parameters: {
    range: {
      // string
      title: { type: "string", min: 0, max: 50, step: 5 },
      subtitle: { type: "string", min: 0, max: 30, step: 1, defaultChar: "·" },

      // number
      likes: { type: "number", min: 0, max: 999, step: 1 },

      // boolean
      featured: { type: "boolean" },

      // array of primitives
      tags: {
        type: "array",
        min: 0,
        max: 5,
        step: 1,
        items: { type: "string" },
        defaultItem: (i: number) => `tag-${i + 1}`,
      },

      // array of objects
      users: {
        type: "array",
        min: 1,
        max: 3,
        items: {
          type: "object",
          name: { type: "string", min: 0, max: 20 },
          age: { type: "number", min: 0, max: 120, step: 1 },
        },
        defaultItem: { name: "Alice", age: 20 },
      },

      // image
      thumbnail: {
        type: "image",
        width: { min: 100, default: 300, max: 600, step: 10 },
        height: { min: 100, default: 200, max: 400, step: 10 },
        src: ({ width, height }) =>
          `https://picsum.photos/${width}/${height}?random=1`,
      },

      // enum (single)
      size: {
        type: "enum",
        selection: "single",
        options: ["sm", "md", "lg"],
      },

      // enum (multiple)
      colors: {
        type: "enum",
        selection: "multiple",
        options: [
          { label: "Red", value: "#f00" },
          { label: "Green", value: "#0f0" },
          { label: "Blue", value: "#00f" },
        ],
      },

      // object with nesting
      product: {
        type: "object",
        name: { type: "string" },
        price: { type: "number", min: 0, max: 1000, step: 10 },

        specs: {
          type: "object",
          weight: { type: "number", min: 0, max: 5000, step: 50 },
        },
      },
    },
  },
};

export default meta;