react-boxmodel-inspector

A zero-dependency React developer tool that wraps any element and visually debugs its CSS box model — margin, border, padding, and content — with live overlays and a draggable floating panel.

⚠️ This is a developer tool. Don't ship it to production.

Features

• 🔍 Long-press any element to inspect it
• 📦 Live layered overlays — dashed rectangles for margin (orange), padding (green), and content (purple), each with pixel edge labels
• 🪟 Draggable floating panel showing T·R·B·L values for margin, border, padding, and content size
• 🔄 Live updates via ResizeObserver, MutationObserver, and scroll/resize listeners
• ⌨️ Keyboard shortcuts — press backtick (`) to toggle, ESC to close
• ⚡ Zero overhead when disabled — renders only children when not in use
• 🎨 Expandable CSS property groups — typography, layout, flex/grid, color, transform, and more
• 🔷 First-class TypeScript support — fully typed with exported interfaces

What's New in v2.0.0

• ✅ Fully rewritten in TypeScript
• ✅ Ships with built-in type declarations (.d.ts) — no @types/ package needed
• ✅ Exported BoxModelInspectorProps interface for type-safe usage
• ✅ 100% backward-compatible with JavaScript/JSX projects

Installation

npm install react-boxmodel-inspector

Basic Usage

JavaScript (JSX)

import BoxModelInspector from 'react-boxmodel-inspector';

function App() {
  return (
    <BoxModelInspector>
      <YourApp />
    </BoxModelInspector>
  );
}

TypeScript (TSX)

import BoxModelInspector from 'react-boxmodel-inspector';
// Optionally import the props type
import type { BoxModelInspectorProps } from 'react-boxmodel-inspector';

function App() {
  return (
    <BoxModelInspector>
      <YourApp />
    </BoxModelInspector>
  );
}

Then in the browser:

• Press ` (backtick) to activate the inspector
• Long-press any element to inspect it
• Press ESC or click ✕ to close the panel
• Drag the panel anywhere

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | children | ReactNode | — | The component tree to wrap | | longPressDuration | number | 500 | How long (ms) to hold before inspection triggers | | toggleKey | string | "`" | Key to toggle the inspector on/off |

TypeScript Integration

This package is written in TypeScript and ships with built-in type declarations. No additional @types/ packages are needed.

Importing Types

import BoxModelInspector from 'react-boxmodel-inspector';
import type { BoxModelInspectorProps } from 'react-boxmodel-inspector';

Using with Custom Wrappers

import BoxModelInspector, { BoxModelInspectorProps } from 'react-boxmodel-inspector';

// Create a custom wrapper with additional props
interface DevInspectorProps extends BoxModelInspectorProps {
  enabled?: boolean;
}

function DevInspector({ enabled = true, ...props }: DevInspectorProps) {
  if (!enabled) return <>{props.children}</>;
  return <BoxModelInspector {...props} />;
}

Minimum TypeScript Version

• TypeScript 5.0+ recommended
• Works with TypeScript 4.7+ (moduleResolution: "bundler" or "node16")

Usage with Entry Point

main.tsx (TypeScript)

import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import App from './App';
import BoxModelInspector from 'react-boxmodel-inspector';

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <BoxModelInspector>
      <App />
    </BoxModelInspector>
  </StrictMode>
);

main.jsx (JavaScript)

import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import App from './App.jsx';
import BoxModelInspector from 'react-boxmodel-inspector';

createRoot(document.getElementById('root')).render(
  <StrictMode>
    <BoxModelInspector>
      <App />
    </BoxModelInspector>
  </StrictMode>
);

Custom Toggle Key and Duration

<BoxModelInspector toggleKey="F2" longPressDuration={300}>
  <App />
</BoxModelInspector>

How It Works

1. Press the toggle key to activate inspector mode — a blue banner appears at the top of the screen.
2. Long-press any element in the page. A circular ripple indicates the progress.
3. On trigger, three dashed overlays appear directly on the element:
   • Orange — margin box with T/R/B/L labels
   • Green — padding box with T/R/B/L labels
   • Purple — content box with width × height
4. A dark floating panel also appears to the right, showing numeric T·R·B·L values for margin, border, padding, and content size.
5. Expand "All properties" in the panel to see grouped CSS values (typography, layout, flex, color, etc).

Requirements

• React 17+ or 18+
• TypeScript 5+ (for type-checking; not required at runtime)
• Works in any browser with ResizeObserver and MutationObserver support (all modern browsers)

License

MIT