React Design Inspector

Developer-only visual inspection for React apps.

React Design Inspector lets code-first product teams inspect the running browser surface instead of measuring static screens. Drop one component into your app, toggle inspection mode, and hover any rendered element to see its size, position, computed styles, class names, and best-effort React component ownership.

Code is the source of truth. The browser is the design surface.

Install

npm install @zacrify/react-design-inspector

React and React DOM are peer dependencies:

npm install react react-dom

Usage

Render the inspector once near the root of your app. It does not require changes to your existing application components.

import { DesignInspector } from '@zacrify/react-design-inspector';

export function Root() {
  return (
    <>
      <App />

      {import.meta.env.DEV && <DesignInspector />}
    </>
  );
}

For non-Vite apps, use whatever development flag your framework provides:

{process.env.NODE_ENV === 'development' && <DesignInspector />}

Toggle

Press:

• Cmd+Shift+D on macOS
• Ctrl+Shift+D on Windows/Linux

When disabled, the component returns null and does not track pointer movement.

What You See

Hover any element while the inspector is enabled to show:

• HTML tag name
• width and height
• x and y viewport position
• padding
• border width
• margin
• background color
• text color
• font size
• font weight
• border radius
• detected utility class names, including common Tailwind classes
• best-effort React component root names

Measurements come from:

element.getBoundingClientRect();

Computed styles come from:

getComputedStyle(element);

Keyboard Navigation

After hovering an element, use arrow keys to walk nearby DOM nodes:

• ArrowUp: parent element
• ArrowDown: first child element
• ArrowLeft: previous sibling
• ArrowRight: next sibling
• Shift+ArrowUp: nearest ancestor React component root
• Shift+ArrowDown: nearest descendant React component root

The overlay shows compact labels for available parent, child, previous, and next targets.

Tailwind Awareness

The inspector does not parse Tailwind configuration yet. It simply detects and displays class names with common utility prefixes, such as:

p-6
gap-4
rounded-2xl
text-base
bg-white
font-bold

This keeps the first version lightweight while still making utility-heavy UIs easier to inspect.

React Component Detection

React component detection is best effort. The package reads React Fiber metadata attached to DOM nodes by React, which is not a public React API.

That means component names may be unavailable or imperfect in some builds, frameworks, React versions, or minified production bundles. The inspector is defensive: if component detection fails, DOM measurement still works.

Overlay Behavior

The overlay is designed not to interfere with your application:

• fixed positioning
• pointer-events: none
• high z-index
• inline styles
• no required CSS import
• dark translucent tooltip
• small monospace text

Because the overlay is non-interactive, it should not steal clicks, hovers, focus, or pointer events from the app being inspected.

Performance

React Design Inspector keeps updates lightweight:

• pointer tracking only runs while enabled
• pointer movement is throttled with requestAnimationFrame
• measurements are read directly from the DOM
• the application component tree is not re-rendered
• only the inspector overlay updates

Storybook

The package is Storybook-compatible because it is just a React component. Add it to a preview decorator in development:

import type { Preview } from '@storybook/react';
import { DesignInspector } from '@zacrify/react-design-inspector';

const preview: Preview = {
  decorators: [
    (Story) => (
      <>
        <Story />
        <DesignInspector />
      </>
    ),
  ],
};

export default preview;

Local Development

Build once:

npm run build

Build continuously while using npm link or a local file dependency:

npm run dev

The package serves compiled files from dist, so source edits must be rebuilt before consuming apps see them.

API

import { DesignInspector, getComponentName } from '@zacrify/react-design-inspector';

DesignInspector

<DesignInspector />

Adds the developer-only inspection overlay.

getComponentName(element)

const name = getComponentName(element);

Returns the nearest detected React component name for a DOM element, or null if no component name can be resolved.

Current Scope

Implemented:

• hover inspection
• bounding box highlight
• measurement tooltip
• computed style display
• utility class display
• best-effort component root display
• keyboard navigation through DOM and component roots

Not implemented yet:

• source file mapping
• design token mapping
• open source file action
• open Storybook story action
• Figma reference linking
• screenshot export
• JSON export
• accessibility inspection

License

MIT