Tweakpane Draggable Theme

Dark, legible styling for Tweakpane with an optional draggable header and collapse control.

Features

• Dark blue-grey palette with clear type and affordances
• Scoped .tp-dark-theme variables so the theme stays self-contained
• Optional draggable header with built-in collapse button
• Programmatic helpers to enable/disable dragging and adjust position
• Auto-injected styles (no network fetch) plus a distributable CSS file for manual control

Installation

npm install tweakpane-draggable-theme

Usage

Apply the theme to an existing pane

import { Pane } from 'tweakpane';
import { applyTheme } from 'tweakpane-draggable-theme';

const pane = new Pane({ title: 'Settings' });

// Apply styling and make the pane draggable
const api = applyTheme(pane, {
  draggable: true,        // defaults to true
  dragThreshold: 3,       // pixels before a drag starts
  boundaryPadding: 10,    // viewport inset in pixels
  title: 'Controls'       // header label shown in the drag bar
});

applyTheme injects the stylesheet once via an inline <style> tag, adds the .tp-dark-theme class to the pane DOM element, and (optionally) prepends the custom header used for dragging. The inline injection avoids Vite-style optimizer warnings that happen when packages load relative CSS files at runtime.

Theme API

The object returned from applyTheme exposes:

• setDraggable(enabled: boolean) – Toggle the draggable header at runtime.
• setPosition({ top, right, bottom, left }) – Manually position the pane (CSS values such as '120px' or '10%').
• getPosition() – Returns the pane’s current offset relative to the viewport ({ top, right, bottom, left } in pixels).

Create a themed pane in one call

import { createThemedPane } from 'tweakpane-draggable-theme';

const { pane, api } = await createThemedPane(
  { title: 'Settings' },        // forwarded to the Tweakpane constructor
  { draggable: true, title: 'Demo Controls' } // same options as applyTheme
);

createThemedPane loads Tweakpane on demand, constructs a pane, and applies the theme before returning { pane, api }.

Controlling CSS injection yourself

By default applyTheme/createThemedPane call injectThemeStyles(document) for you. If you prefer to manage styles manually you have two options:

// Option 1: import the packaged stylesheet once at app startup
import 'tweakpane-draggable-theme/css';

// Option 2: inject the CSS string on demand
import { injectThemeStyles, getThemeCss } from 'tweakpane-draggable-theme';

injectThemeStyles();       // inserts a <style> tag if it does not exist
const css = getThemeCss(); // string export for SSR or custom bundlers

applyTheme will detect the existing <style> tag created by either approach and skip a second injection, so you can keep manual control without warnings.

CSS-only usage

If you simply want the dark styling without the JavaScript helpers:

<link rel="stylesheet" href="/node_modules/tweakpane-draggable-theme/tweakpane-theme.css">
<div class="tp-dark-theme">
  <!-- Tweakpane will render here -->
</div>

Make sure the element that hosts the pane receives the tp-dark-theme class so the scoped rules apply.

Customisation

All colours derive from CSS custom properties defined on .tp-dark-theme. Override them to match your brand:

.tp-dark-theme {
  --tp-base-background-color: hsla(210, 24%, 12%, 1);
  --tp-container-foreground-color: hsla(210, 20%, 80%, 1);
  --tp-input-background-color-hover: hsla(210, 24%, 16%, 1);
  /* Draggable header */
  --tp-drag-header-background-color: hsla(210, 24%, 10%, 1);
  --tp-drag-header-foreground-color: hsla(210, 24%, 85%, 1);
  --tp-drag-handle-color: hsla(210, 24%, 65%, 1);
}

The draggable header, folder levels, and dropdowns each expose dedicated variables (for example --tp-drag-header-background-color-hover, --tp-folder-background-color-level2, --tp-dropdown-item-foreground-color-selected) so you can tweak the new components without increasing selector specificity.

Key surface colours (defaults shown):

• Pane background: hsla(220, 18%, 10%, 1)
• Drag header: hsla(220, 18%, 7%, 1) (hover 9%, active 12%)
• Text: hsla(220, 14%, 75%, 1)
• Buttons (default): hsla(220, 14%, 25%, 1) with lighter hover/active states
• Folder hierarchy: lightens slightly at each nested level (10% → 13% → 16% → 19%)

Styled components

The theme provides coverage for:

• Pane containers, headers, and separators
• Folder hierarchies (including the collapse chevron)
• Inputs (text, number, slider), buttons, and monitors
• Dropdown lists and popup menus

Browser support

Modern browsers that support CSS custom properties (current Chrome, Edge, Firefox, Safari). Internet Explorer is not supported.

Development

git clone https://github.com/jeffreycastellano/tweakpane-draggable-theme.git
cd tweakpane-draggable-theme
# Files are plain CSS/ES modules – no build step required.

License

MIT