dialkit

v1.0.0

Published

a day ago

Real-time parameter tweaking for React and Solid apps

0High
0Medium
0Low

joshpuckett

react solid solidjs animation tweaking parameters devtools

dialkit

Real-time parameter tweaking for React + Motion.

Quick Start

npm install dialkit motion

// layout.tsx
import { DialRoot } from 'dialkit';
import 'dialkit/styles.css';

export default function Layout({ children }) {
  return (
    <html>
      <body>
        {children}
        <DialRoot />
      </body>
    </html>
  );
}

// component.tsx
import { useDialKit } from 'dialkit';

function Card() {
  const p = useDialKit('Card', {
    blur: [24, 0, 100],
    scale: 1.2,
    color: '#ff5500',
    visible: true,
  });

  return (
    <div style={{
      filter: `blur(${p.blur}px)`,
      transform: `scale(${p.scale})`,
      color: p.color,
      opacity: p.visible ? 1 : 0,
    }}>
      ...
    </div>
  );
}

useDialKit

const params = useDialKit(name, config, options?)

| Param | Type | Description | |-------|------|-------------| | name | string | Panel title displayed in the UI | | config | DialConfig | Parameter definitions (see Control Types below) | | options.onAction | (path: string) => void | Callback when action buttons are clicked |

Returns a fully typed object matching your config shape with live values. Updating a control in the UI immediately updates the returned values.

Control Types

Slider

Numbers create sliders. There are three ways to define them:

Explicit range — [default, min, max]:

blur: [24, 0, 100]

Explicit range + step — [default, min, max, step]:

blur: [24, 0, 100, 5]    // snaps in increments of 5

When step is omitted, it's inferred from the range (see table below).

Auto-inferred — bare number:

scale: 1.2

A single number auto-infers a reasonable min, max, and step:

| Value range | Inferred min/max | Step | |-------------|-----------------|------| | 0–1 | 0 to 1 | 0.01 | | 0–10 | 0 to value × 3 | 0.1 | | 0–100 | 0 to value × 3 | 1 | | 100+ | 0 to value × 3 | 10 |

Returns: number

Sliders support click-to-snap (with spring animation), drag with rubber-band overflow, and direct text editing (hover the value for 800ms, then click to type).

Toggle

enabled: true
darkMode: false

Booleans create an Off/On segmented control.

Returns: boolean

Text

title: 'Hello'                                    // auto-detected from string
subtitle: { type: 'text', default: '', placeholder: 'Enter subtitle...' }

Non-hex strings are auto-detected as text inputs. Use the explicit form for a placeholder or to set a default.

Returns: string

Color

color: '#ff5500'                           // auto-detected from hex string
bg: { type: 'color', default: '#000' }     // explicit

Hex strings (#RGB, #RRGGBB, #RRGGBBAA) are auto-detected as color pickers. Each color control has a text display (click to edit the hex value), and a swatch button that opens the native color picker.

Returns: string (hex color)

Select

layout: {
  type: 'select',
  options: ['stack', 'fan', 'grid'],
  default: 'stack',
}

Options can be plain strings or { value, label } objects for custom display text:

shape: {
  type: 'select',
  options: [
    { value: 'portrait', label: 'Portrait' },
    { value: 'square', label: 'Square' },
    { value: 'landscape', label: 'Landscape' },
  ],
  default: 'portrait',
}

If default is omitted, the first option is selected.

Returns: string (the selected option's value)

Spring

// Time-based (simple mode)
spring: { type: 'spring', visualDuration: 0.3, bounce: 0.2 }

// Physics-based (advanced mode)
spring: { type: 'spring', stiffness: 200, damping: 25, mass: 1 }

Creates a visual spring editor with a live animation curve preview. The editor supports two modes, toggled in the UI:

Time (simple) — visualDuration (0.1–1s) and bounce (0–1). Ideal for most animations.
Physics (advanced) — stiffness (1–1000), damping (1–100), and mass (0.1–10). Full control over spring dynamics.

The returned config object is passed directly to Motion's transition prop:

const p = useDialKit('Card', {
  spring: { type: 'spring', visualDuration: 0.5, bounce: 0.04 },
  x: [0, -200, 200],
});

<motion.div animate={{ x: p.x }} transition={p.spring} />

Returns: SpringConfig (pass directly to Motion)

Action

const p = useDialKit('Controls', {
  shuffle: { type: 'action' },
  reset: { type: 'action', label: 'Reset All' },
}, {
  onAction: (path) => {
    if (path === 'shuffle') shuffleItems();
    if (path === 'reset') resetToDefaults();
  },
});

Action buttons trigger callbacks without storing any value. The label defaults to the formatted key name (camelCase becomes Title Case). Multiple adjacent actions are grouped vertically. Action buttons can be placed at the root or nested inside folders.

Folder

Any nested plain object becomes a collapsible folder. Folders can nest arbitrarily deep.

shadow: {
  blur: [10, 0, 50],
  opacity: [0.25, 0, 1],
  color: '#000000',
}

// Access nested values:
params.shadow.blur     // number
params.shadow.color    // string

Folders are open by default. Add _collapsed: true to start a folder closed. This is a reserved metadata key — it controls the UI only and won't appear in your returned values.

shadow: {
  _collapsed: true,    // folder starts closed
  blur: [10, 0, 50],
  opacity: [0.25, 0, 1],
}

DialKit also supports dynamic config updates. If your config shape, defaults, options, or labels change over time, the panel updates while preserving current values where paths still exist.

Dynamic configs work with both inline objects and memoized configs — no special consumer action needed:

const values = useDialKit('Controls', {
  style: { type: 'select', options: dynamicOptions },
});

DialRoot

<DialRoot position="top-right" />

| Prop | Type | Default | |------|------|---------| | position | 'top-right' \| 'top-left' \| 'bottom-right' \| 'bottom-left' | 'top-right' | | defaultOpen | boolean | true |

Mount once at your app root. The panel renders via a portal on document.body. It collapses to a small icon button and expands to 280px wide on click.

Panel Toolbar

When the panel is open, the toolbar provides:

Presets — A version dropdown for saving and loading parameter snapshots. Click "+" to save the current state as a new version. Select a version to load it. Changes auto-save to the active version. "Version 1" always represents the original defaults.
Copy — Exports the current values as JSON to your clipboard.

Full Example

import { useDialKit } from 'dialkit';
import { motion } from 'motion/react';

function PhotoStack() {
  const p = useDialKit('Photo Stack', {
    // Text inputs
    title: 'Japan',
    subtitle: { type: 'text', default: 'December 2025', placeholder: 'Enter subtitle...' },

    // Color pickers
    accentColor: '#c41e3a',
    shadowTint: { type: 'color', default: '#000000' },

    // Select dropdown
    layout: { type: 'select', options: ['stack', 'fan', 'grid'], default: 'stack' },

    // Grouped sliders in a folder
    backPhoto: {
      offsetX: [239, 0, 400],
      offsetY: [0, 0, 150],
      scale: [0.7, 0.5, 0.95],
      overlayOpacity: [0.6, 0, 1],
    },

    // Spring config for Motion
    transitionSpring: { type: 'spring', visualDuration: 0.5, bounce: 0.04 },

    // Toggle
    darkMode: false,

    // Action buttons
    next: { type: 'action' },
    previous: { type: 'action' },
  }, {
    onAction: (action) => {
      if (action === 'next') goNext();
      if (action === 'previous') goPrevious();
    },
  });

  return (
    <motion.div
      animate={{ x: p.backPhoto.offsetX }}
      transition={p.transitionSpring}
      style={{ color: p.accentColor }}
    >
      <h1>{p.title}</h1>
      <p>{p.subtitle}</p>
    </motion.div>
  );
}

Types

All config and value types are exported:

import type {
  SpringConfig,
  ActionConfig,
  SelectConfig,
  ColorConfig,
  TextConfig,
  DialConfig,
  DialValue,
  ResolvedValues,
  ControlMeta,
  PanelConfig,
  Preset,
} from 'dialkit';

Return values are fully typed: params.blur infers as number, params.color as string, params.spring as SpringConfig, params.shadow as a nested object, etc.

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

dialkit

Quick Start

useDialKit

Control Types

Slider

Toggle

Text

Color

Select

Spring

Action

Folder

DialRoot

Panel Toolbar

Full Example

Types

License