How to Use the Measure Addon for Layout Inspection in Storybook

The Measure addon renders an interactive overlay that displays exact dimensions, margins, padding, and borders when you hover over elements in a Storybook story.

The Measure addon is part of Storybook’s official Essentials suite in the storybookjs/storybook repository. It eliminates the need to open browser DevTools when checking spacing and sizing during component development, providing instant visual feedback directly in the canvas.

What Is the Measure Addon?

The Measure addon is a decorator-based visualization tool that activates when the measureEnabled global parameter is set to true. When active, it tracks mouse movement over the story’s DOM and draws a dynamic overlay showing:

• Width and height of the hovered element
• Margin (outer spacing)
• Padding (inner spacing)
• Border dimensions

This functionality is particularly useful for design system development where pixel-perfect spacing compliance is required.

How the Measure Addon Works Internally

Understanding the internal architecture helps when debugging or extending the addon. The implementation relies on three core files in code/core/src/measure/:

Core Implementation Files

constants.ts defines the addon’s identity and communication protocol:

// code/core/src/measure/constants.ts
export const ADDON_ID = 'storybook/measure-addon';
export const PARAM_KEY = 'measureEnabled';
// EVENTS object defines channel communication for toggling the overlay

withMeasure.ts contains the decorator logic that renders the overlay:

// code/core/src/measure/withMeasure.ts
const { measureEnabled } = context.globals || {};

if (context.viewMode === 'story' && measureEnabled) {
  // Attaches the measurement visualizer to the DOM
  // Draws canvas overlay showing dimensions, margin, padding, border
}

The decorator only activates when context.viewMode === 'story' to ensure the overlay does not interfere with Docs view or other non-canvas modes.

preview.ts registers the decorator globally when the feature flag is present:

// code/core/src/measure/preview.ts
export const decorators = globalThis.FEATURES?.measure ? [withMeasure] : [];

Enabling the Measure Addon for Layout Inspection

You can activate the Measure addon at three different scopes: globally, per-story, or interactively via the UI.

Global Configuration

To enable layout inspection for all stories in your Storybook instance, add the measure parameter to your .storybook/preview.ts or .storybook/preview.js file:

// .storybook/preview.ts
import type { Preview } from '@storybook/react';

const preview: Preview = {
  parameters: {
    // Enable measure addon for all stories
    measure: true,
  },
};

export default preview;

Setting measure: true sets the global measureEnabled flag that withMeasure.ts checks before rendering the overlay.

Per-Story Configuration

For granular control, enable the Measure addon for specific stories only by setting the parameter in the story’s metadata or export:

// src/components/Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';

const meta: Meta<typeof Button> = {
  component: Button,
  title: 'Components/Button',
  parameters: {
    // Enable measure only for stories in this file
    measure: true,
  },
};

export default meta;

type Story = StoryObj<typeof Button>;

export const Primary: Story = {
  args: { primary: true, label: 'Button' },
  parameters: {
    // Override to disable for this specific story
    measure: false,
  },
};

Toolbar and Keyboard Shortcuts

Once the Measure addon is enabled (either globally or per-story), users can toggle the layout inspection overlay interactively:

• Toolbar: Click the ruler icon (📏) in the Storybook toolbar to show or hide measurements.
• Keyboard: Press the m key to toggle the overlay on and off.

These controls emit events defined in constants.ts that update the measureEnabled state without requiring a page reload.

Programmatic Control of the Measure Overlay

For advanced use cases, such as creating custom toolbar buttons or integrating with other addons, you can control the Measure addon programmatically using Storybook’s channel API:

import { addons } from '@storybook/addons';
import { EVENTS } from '@storybook/addon-measure/constants';

// Emit event to request measurement mode
addons.getChannel().emit(EVENTS.REQUEST);

// Emit event to clear/remove measurement overlay
addons.getChannel().emit(EVENTS.CLEAR);

This approach accesses the same event constants defined in code/core/src/measure/constants.ts, allowing you to trigger the functionality implemented in withMeasure.ts directly.

Summary

• The Measure addon is an Essentials tool in storybookjs/storybook that visualizes element dimensions, margins, padding, and borders through an interactive overlay.
• Internally, it operates as a decorator (withMeasure.ts) that activates when context.globals.measureEnabled is true and context.viewMode === 'story'.
• Enable layout inspection globally via parameters: { measure: true } in .storybook/preview.ts, or per-story via story-level parameters.
• Users can toggle the overlay interactively using the toolbar ruler icon or the m keyboard shortcut.
• For custom integrations, control the addon programmatically via the channel API using EVENTS.REQUEST and EVENTS.CLEAR from storybook/addon-measure/constants.

Frequently Asked Questions

How do I disable the Measure addon for specific stories when it's enabled globally?

Set measure: false in the story’s parameters object. This overrides the global setting for that specific story. For example: MyStory.parameters = { measure: false }; in CSF format or parameters: { measure: false } in the story export.

What is the difference between the Measure addon and browser DevTools?

The Measure addon provides an immediate, persistent overlay directly in the Storybook canvas that follows your cursor, showing dimensions, margin, padding, and border simultaneously without opening inspector panels. Unlike DevTools, it is designed for rapid component-level layout checks and integrates with Storybook’s addon ecosystem and keyboard shortcuts.

Can I use the Measure addon in Docs view or only in Canvas view?

The Measure addon only activates in Canvas view (story view mode). According to the source code in withMeasure.ts, the decorator explicitly checks if (context.viewMode === 'story' && measureEnabled) before attaching the overlay. It will not render in Docs view to avoid interfering with documentation layouts.

Is the Measure addon available in Storybook 6.x or only in newer versions?

The Measure addon is part of the Essentials suite in modern Storybook versions (7.0+). In Storybook 6.x, similar functionality existed but may have been implemented differently or required manual addon registration. The current implementation described here relies on the global FEATURES flag and decorator architecture introduced in recent versions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}