React Dev Panel

A lightweight, type-safe development panel for React that lets you control component state and props in real-time during development.

Features

• One Hook: Single useDevPanel hook - no providers, no setup
• 13 Control Types: Text, Number, Boolean, Select, Color, Range, Date, Button, LocalStorage, and more
• Auto-Persistence: Optional localStorage sync for control values
• Type-Safe: Full TypeScript support with IntelliSense
• Themeable: 21 built-in themes + CSS custom properties
• Lightweight: ~16 KB gzipped, zero runtime dependencies

Installation

npm install -D @berenjena/react-dev-panel

Quick Start

import { useState } from "react";
import { useDevPanel } from "@berenjena/react-dev-panel";

function App() {
    const [name, setName] = useState("John");
    const [age, setAge] = useState(25);
    const [theme, setTheme] = useState("dark");

    useDevPanel("Settings", {
        name: { type: "text", value: name, onChange: setName },
        age: { type: "number", value: age, min: 0, max: 100, onChange: setAge },
        theme: { type: "select", value: theme, options: ["light", "dark"], onChange: setTheme },
    });

    return <div>Hello, {name}!</div>;
}

That's it! Press Ctrl+Shift+A to toggle the panel.

Control Types

All 13 control types available:

{
  text: { type: "text", value: string, onChange: (v) => void }
  number: { type: "number", value: number, min?: number, max?: number, onChange: (v) => void }
  boolean: { type: "boolean", value: boolean, onChange: (v) => void }
  select: { type: "select", value: string, options: string[], onChange: (v) => void }
  multiselect: { type: "multiselect", value: string[], options: string[], onChange: (v) => void }
  color: { type: "color", value: string, onChange: (v) => void }
  range: { type: "range", value: number, min: number, max: number, step?: number, onChange: (v) => void }
  date: { type: "date", value: string, min?: string, max?: string, onChange: (v) => void }
  button: { type: "button", onClick: () => void }
  buttonGroup: { type: "buttonGroup", buttons: Array<{label: string, onClick: () => void}> }
  dragAndDrop: { type: "dragAndDrop", onChange: (files: FileList) => void }
  localStorage: { type: "localStorage", onRefresh?: () => void }
  separator: { type: "separator", variant?: "line" | "label" | "space" }
}

Common options (available on most controls):

• label?: string - Display label
• description?: string - Help text
• disabled?: boolean - Disable control
• persist?: boolean - Auto-save to localStorage

📖 Full control documentation →

Configuration

Custom Hotkey

useDevPanel("Settings", controls, {
    hotKeyConfig: { key: "d", ctrlKey: true, shiftKey: true },
});

Open from the console

Once the panel is in use, a devPanel helper is available on window so you can drive it straight from the browser console — handy when the hotkey clashes with another shortcut:

devPanel.open(); // show the panel
devPanel.close(); // hide it
devPanel.toggle(); // flip visibility (same as the hotkey)

It's registered automatically when the first (enabled) useDevPanel call mounts, so it isn't present in builds where the panel is disabled.

Panel Theme

useDevPanel("Settings", controls, {
    theme: "neon", // 21 built-in themes available
    panelTitle: "My Dev Panel",
});

Event Handling

Choose when controls trigger updates:

{
  type: "text",
  value: searchTerm,
  event: "onChange", // Update on every keystroke (default)
  onChange: setSearchTerm
}

{
  type: "text",
  value: apiKey,
  event: "onBlur", // Update only when focus is lost
  onChange: setApiKey
}

Disabling in Production

Use the enabled flag to turn the panel off at runtime. When false, the call is a no-op — the section is not registered and the panel does not mount. It defaults to true.

useDevPanel("Settings", controls, {
    enabled: import.meta.env.DEV, // Vite
    // enabled: process.env.NODE_ENV !== "production", // Webpack / Next / CRA
});

⚠️ enabled does not remove the panel from your bundle. It stops the panel from running, but the library code is still imported and shipped to users. To strip the code out of production builds entirely (e.g. a Vite plugin that stubs the package), see the Production & SSR guide.

SSR / Next.js

The package is import-safe on the server (it never touches document/localStorage at import time) and ships the "use client" directive, so it works under the Next.js App Router. The panel mounts and renders on the client only.

📖 Styling guide | Event handling | Advanced usage | Production & SSR

Documentation

Guides:

• Control Types - All 12 control types with examples
• Persistence - Auto-save to localStorage
• Styling & Theming - Themes and CSS customization
• Event Handling - onChange vs onBlur strategies
• Advanced Usage - Complex patterns and optimization
• Production & SSR - Disabling in production, bundle stripping, Next.js
• Bundle Size - Size tracking and optimization
• Development - Contributing and setup

Live Examples:

• Storybook - Interactive component demos
• Run locally: npm run storybook

API Reference

useDevPanel(sectionName, controls, options?)

Parameters:

• sectionName: string - Unique identifier for this control group
• controls: ControlsGroup - Object mapping control keys to control definitions
• options?: DevPanelProps - Optional configuration

Options:

{
  panelTitle?: string;           // Custom panel header
  theme?: string;                // Built-in theme name
  enabled?: boolean;             // Activate this call (default true; false = no-op)
  hotKeyConfig?: {               // Custom toggle hotkey
    key: string;
    ctrlKey?: boolean;
    shiftKey?: boolean;
    altKey?: boolean;
    metaKey?: boolean;
  }
}

enabled gates runtime behaviour only — it does not remove the panel from your bundle. See the Production & SSR guide for build-time stripping.

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

Development:

git clone https://github.com/Berenjenas/react-dev-panel.git
cd react-dev-panel
npm install
npm run storybook

License

MIT © Berenjena

Links: NPM · GitHub · Issues · Berenjena

Made with ❤️ by the Berenjena team