css-var-bind 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jacob Berglund
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+# css-var-bind
+
+A lightweight web component that binds HTML input elements to CSS custom properties (variables).
+
+## Installation
+
+```bash
+npm install css-var-bind
+```
+
+## Usage
+
+```html
+<css-var-bind variable="--scale" unit="px" target=":root" strategy="global">
+  <input type="range" min="0" max="100" value="50" />
+  <input type="number" min="0" max="100" value="50" />
+</css-var-bind>
+```
+
+The component automatically:
+
+- Updates the CSS variable when inputs change
+- Syncs values between multiple inputs
+- Applies the unit to the value
+
+## Attributes
+
+| Attribute  | Required | Default     | Description                                                     |
+| ---------- | -------- | ----------- | --------------------------------------------------------------- |
+| `variable` | Yes      | -           | CSS custom property name (must start with `--`)                 |
+| `unit`     | No       | `""`        | Unit to append (e.g., `px`, `rem`, `%`, `deg`)                  |
+| `target`   | No       | -           | CSS selector for the element to set the variable on             |
+| `strategy` | No       | `"closest"` | How to resolve the target: `"closest"`, `"global"`, or `"self"` |
+
+### Strategy Options
+
+- **`closest`** (default): Finds the nearest ancestor matching the `target` selector
+- **`global`**: Uses `document.querySelector(target)` for global lookup
+- **`self`**: Sets the variable on the component itself (ignores `target`)
+
+## Examples
+
+**Color picker:**
+
+```html
+<css-var-bind target="body" variable="--bg-color">
+  <input type="color" value="#b4d455" />
+</css-var-bind>
+```
+
+**Scoped to ancestor:**
+
+```html
+<div class="card">
+  <css-var-bind variable="--card-padding" unit="rem" target=".card">
+    <input type="number" min="0" max="5" value="2" />
+  </css-var-bind>
+</div>
+```
+
+**Self-binding:**
+
+```html
+<css-var-bind variable="--opacity" strategy="self">
+  <input type="range" min="0" max="1" step="0.1" value="1" />
+</css-var-bind>
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+/**
+ * A custom element that binds input elements to a CSS variable.
+ * It also syncs values between different inputs, like range and number.
+ *
+ * @element css-var-bind
+ *
+ * @attr {string} variable - **Required.** The CSS custom property name to bind to.
+ *   Must start with `--` (e.g., `--scale`, `--primary-color`).
+ *
+ * @attr {string} [unit=""] - Optional unit to append to the value when setting the CSS variable.
+ *   Common values: `px`, `%`, `em`, `rem`, `deg`, etc.
+ *
+ * @attr {string} [target] - CSS selector for the element on which to set the CSS variable.
+ *   How this selector is resolved depends on the `strategy` attribute.
+ *
+ * @attr {"closest"|"global"|"self"} [strategy="closest"] - How to resolve the target selector.
+ *   - `"closest"` — Uses `element.closest(target)` to find an ancestor (default).
+ *   - `"global"` — Uses `document.querySelector(target)` for global lookup.
+ *   - `"self"` — Ignores `target` and binds to the component itself.
+ *
+ * @example
+ * ```html
+ * <!-- Bind to a global element (document.querySelector) -->
+ * <css-var-bind variable="--scale" unit="px" target=":root" strategy="global">
+ *   <input type="range" min="0" max="100" />
+ *   <input type="number" />
+ * </css-var-bind>
+ *
+ * <!-- Bind to the closest ancestor with a class (default strategy) -->
+ * <div class="card">
+ *   <css-var-bind variable="--card-padding" unit="rem" target=".card">
+ *     <input type="number" min="0" max="5" />
+ *   </css-var-bind>
+ * </div>
+ *
+ * <!-- Bind to the component itself -->
+ * <css-var-bind variable="--opacity" strategy="self">
+ *   <input type="range" min="0" max="1" step="0.1" />
+ * </css-var-bind>
+ * ```
+ */
+declare class CssVarBind extends HTMLElement {
+    bindToElement: HTMLElement | null;
+    cssVariableName: string;
+    inputs: NodeListOf<HTMLInputElement> | null;
+    unit: string;
+    private boundHandleInput;
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private handleInput;
+    handleSteppedInputs(target: HTMLInputElement): void;
+    setValueIfCSSPropertyExists(): void;
+    syncInputs(changedInput: HTMLInputElement): void;
+}
+export default CssVarBind;

package/dist/index.js

@@ -0,0 +1,140 @@
+/**
+ * A custom element that binds input elements to a CSS variable.
+ * It also syncs values between different inputs, like range and number.
+ *
+ * @element css-var-bind
+ *
+ * @attr {string} variable - **Required.** The CSS custom property name to bind to.
+ *   Must start with `--` (e.g., `--scale`, `--primary-color`).
+ *
+ * @attr {string} [unit=""] - Optional unit to append to the value when setting the CSS variable.
+ *   Common values: `px`, `%`, `em`, `rem`, `deg`, etc.
+ *
+ * @attr {string} [target] - CSS selector for the element on which to set the CSS variable.
+ *   How this selector is resolved depends on the `strategy` attribute.
+ *
+ * @attr {"closest"|"global"|"self"} [strategy="closest"] - How to resolve the target selector.
+ *   - `"closest"` — Uses `element.closest(target)` to find an ancestor (default).
+ *   - `"global"` — Uses `document.querySelector(target)` for global lookup.
+ *   - `"self"` — Ignores `target` and binds to the component itself.
+ *
+ * @example
+ * ```html
+ * <!-- Bind to a global element (document.querySelector) -->
+ * <css-var-bind variable="--scale" unit="px" target=":root" strategy="global">
+ *   <input type="range" min="0" max="100" />
+ *   <input type="number" />
+ * </css-var-bind>
+ *
+ * <!-- Bind to the closest ancestor with a class (default strategy) -->
+ * <div class="card">
+ *   <css-var-bind variable="--card-padding" unit="rem" target=".card">
+ *     <input type="number" min="0" max="5" />
+ *   </css-var-bind>
+ * </div>
+ *
+ * <!-- Bind to the component itself -->
+ * <css-var-bind variable="--opacity" strategy="self">
+ *   <input type="range" min="0" max="1" step="0.1" />
+ * </css-var-bind>
+ * ```
+ */
+class CssVarBind extends HTMLElement {
+    bindToElement = null;
+    cssVariableName = "";
+    inputs = null;
+    unit = "";
+    boundHandleInput;
+    constructor() {
+        super();
+        this.boundHandleInput = this.handleInput.bind(this);
+    }
+    connectedCallback() {
+        this.cssVariableName = this.getAttribute("variable") || "";
+        this.unit = this.getAttribute("unit") || "";
+        this.inputs = this.querySelectorAll("input");
+        if (!this.cssVariableName.startsWith("--")) {
+            console.error("CSS variable name must start with --");
+            return;
+        }
+        if (!this.inputs.length) {
+            console.warn("css-var-bind: No input elements found");
+            return;
+        }
+        const target = this.getAttribute("target");
+        const strategy = this.getAttribute("strategy") || "closest";
+        switch (strategy) {
+            case "global":
+                this.bindToElement = target ? document.querySelector(target) : null;
+                break;
+            case "self":
+                this.bindToElement = this;
+                break;
+            default:
+                this.bindToElement = target ? this.closest(target) : this;
+                break;
+        }
+        if (!this.bindToElement) {
+            console.warn(`css-var-bind: Target element "${target}" not found`);
+            return;
+        }
+        this.inputs.forEach((input) => {
+            this.setValueIfCSSPropertyExists();
+            input.addEventListener("input", this.boundHandleInput);
+        });
+    }
+    disconnectedCallback() {
+        if (this.inputs) {
+            this.inputs.forEach((input) => {
+                input.removeEventListener("input", this.boundHandleInput);
+            });
+        }
+    }
+    handleInput(event) {
+        if (!(event.target instanceof HTMLInputElement))
+            return;
+        this.handleSteppedInputs(event.target);
+    }
+    handleSteppedInputs(target) {
+        if (!this.bindToElement)
+            return;
+        this.bindToElement.style.setProperty(this.cssVariableName, target.value + this.unit);
+        this.syncInputs(target);
+    }
+    setValueIfCSSPropertyExists() {
+        if (!this.bindToElement || !this.inputs)
+            return;
+        const root = getComputedStyle(this.bindToElement);
+        this.inputs.forEach((input) => {
+            if (input.type === "radio")
+                return;
+            if (input.type === "range") {
+                const cssValue = root.getPropertyValue(this.cssVariableName);
+                if (!cssValue) {
+                    console.warn(`css-var-bind: CSS variable ${this.cssVariableName} is not set on the target element`);
+                }
+                else {
+                    input.value = cssValue;
+                }
+            }
+            if (input.value) {
+                // if input has a value already, set the css variable to that value
+                this.bindToElement?.style.setProperty(this.cssVariableName, input.value + this.unit);
+            }
+            if (input.value === "") {
+                input.value = root.getPropertyValue(this.cssVariableName);
+            }
+        });
+    }
+    syncInputs(changedInput) {
+        if (!this.inputs)
+            return;
+        this.inputs.forEach((input) => {
+            if (input !== changedInput) {
+                input.value = changedInput.value;
+            }
+        });
+    }
+}
+export default CssVarBind;
+customElements.define("css-var-bind", CssVarBind);

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "css-var-bind",
+  "version": "0.0.1",
+  "description": "A utility web component which binds (and syncs) inputs to CSS variables",
+  "keywords": [
+    "web-components",
+    "css-variables",
+    "custom-elements",
+    "css-custom-properties",
+    "input-binding",
+    "reactive",
+    "vanilla-js"
+  ],
+  "author": "Jacob Berglund",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jberglund/css-var-bind.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jberglund/css-var-bind/issues"
+  },
+  "homepage": "https://github.com/jberglund/css-var-bind#readme",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun run tsc",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "publint": "bunx publint",
+    "dev": "bun index.html",
+    "prepublishOnly": "bun run lint && bun run build"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.14",
+    "typescript": "^5.9.3"
+  }
+}