A TypeScript library that creates interactive UI controls for CSS custom properties (CSS variables). Provides sliders for numeric values and color pickers for colors, all rendered in a Shadow DOM web component. Built with Lit for reactive, declarative templates.
npm install @codepen/slidevars
Just define CSS variables in your stylesheet and call init() with no arguments:
:root {
--box-size: 150px;
--box-color: #9c27b0;
--border-radius: 20px;
--font-size: 18px;
}
import { slideVars } from "@codepen/slidevars";
slideVars.init(); // That's it! Auto-detects all CSS variables
SlideVars will:
:root for all CSS custom propertiesFor more control, configure each variable manually:
import { slideVars } from "@codepen/slidevars";
slideVars.init(
{
"--width": {
type: "slider",
min: 10,
max: 100,
default: 50,
unit: "px",
scope: "#animation", // Apply to specific element
},
"--bg": {
type: "color",
default: "red",
},
},
{
defaultOpen: false, // Optional: set to true to show controls on load
}
);
There are only slider and color types for now.
Combine auto-detection with manual overrides:
slideVars.init(
{
// Manual config overrides auto-detected values
"--box-size": {
type: "slider",
min: 50,
max: 500, // Custom range instead of default
unit: "px",
},
},
{
auto: true, // Explicitly enable auto-detection
}
);
This will inject a <slide-vars> web component into the <body> as a fixed-position toggle button (🎛️) in the top right. Click it to open/close the controls.
To test the library with the interactive demo/documentation:
npm install
npm run example
This will start a dev server at http://localhost:3000 with a comprehensive single-page demo that includes:
The dev server supports hot reloading, so changes to the source files will update automatically.
npm run build
This uses Vite 7 with Rolldown (a fast Rust-based bundler) to create the distributable files in the dist/ folder. All styles are bundled into the JavaScript output (no separate CSS file).
npm run build:demo
This builds the demo/documentation site to the docs/ folder. The site is automatically deployed to GitHub Pages on every push to the main branch.
Just for fuzies, the library includes a custom <slidevars-logo> component that displays three animated range sliders. The sliders animate to different positions when the panel opens/closes:
<slidevars-logo open="false"></slidevars-logo>
By default, slideVars.init() creates and injects the <slide-vars> element automatically. However, you can manually place it in your HTML to control its position and add custom content via slots:
<!-- Place the element wherever you want in your HTML -->
<slide-vars>
<h2>🎛️ Control Panel</h2>
<p>Adjust the values below to customize your design:</p>
</slide-vars>
This approach gives you:
// Open the controls panel
slideVars.open();
// Close the controls panel
slideVars.close();
// Toggle the controls panel
slideVars.toggle();
// Destroy the component entirely
slideVars.destroy();
// Get the element reference
const element = slideVars.getElement();
The second parameter to init() accepts options:
interface SlideVarsOptions {
defaultOpen?: boolean; // Whether controls are open on load (default: false)
auto?: boolean; // Enable auto-detection (default: true if config is empty)
scope?: string; // Selector to read variables from (default: ":root")
}
Examples:
// Auto-detect from :root (default)
slideVars.init();
// Auto-detect from specific element
slideVars.init({}, { scope: "#my-component" });
// Open controls by default
slideVars.init({}, { defaultOpen: true });
// Manual config only (disable auto-detection)
slideVars.init(
{ "--my-var": { type: "slider", min: 0, max: 100, unit: "px" } },
{ auto: false }
);
Auto-detected sliders use these default ranges by unit type. Based on MDN CSS numeric data types:
Length Units:
px, cm, mm, in, pt, pc, qem, rem, ex, rex, cap, rcap, ch, rch, ic, ric, lh, rlhvw, vh, vi, vb, vmin, vmax, svw, svh, svi, svb, lvw, lvh, dvw, dvh, dvi, dvbcqw, cqh, cqi, cqb, cqmin, cqmaxOther Units:
deg (0-360), grad (0-400), rad (0-6.28), turn (0-1)s (0-10), ms (0-5000)Hz (0-20000), kHz (0-20)dpi (72-600), dpcm (28-236), dppx (1-4)% (0-100)fr (0-10)Ranges automatically expand if the current value is outside the defaults.
Auto-detected color variables support:
#rgb, #rrggbb, #rrggbbaargb(), rgba(), hsl(), hsla()transparent and currentColor)Note: newer color syntaxes (like oklch() / color()) aren’t currently auto-detected.
slideVars.init(config?: SlideVarsConfig, options?: SlideVarsOptions)Initialize the component. If config is empty or omitted, auto-detects CSS variables from :root.
slideVars.destroy()Remove the component from the DOM.
slideVars.getElement()Get a reference to the underlying SlideVarsElement instance.
This library is written in TypeScript and includes full type definitions. Import types as needed:
import {
slideVars,
SlideVarsConfig,
SliderConfig,
ColorConfig,
} from "@codepen/slidevars";
MIT © CodePen