css-variable-globalizer

Globalize CSS custom properties from selected child elements onto :root and keep then sync'd.

For example,

1. Specify :root { --globalize--accent-color: .card } to tell the library to read
2. --accent-color from .card and mirror it onto the :root element as
3. --global-accent-color and watch for changes.

Installation

npm install css-variable-globalizer

Usage

import { start } from 'css-variable-globalizer';

const controller = start();

controller.stop();

Browser Demo

Run npm run build, then open demo/index.html in a browser to see source custom properties mirrored onto :root and used by a live preview.

How it works

The package reads config custom properties from document.documentElement. Config variables use a prefix, by default --globalize--. Each config value is a selector, for example:

:root {
  --globalize--my-var1: .card .title;
}

.card .title {
  --my-var1: red;
}

After start(), the package copies the computed value of --my-var1 from the first matching element to :root as --global-my-var1.

Avoiding global variable name clash

To give the global output a more specific name, append -as--unique-name to the config variable. The output still keeps the --global- prefix. For example:

:root {
  --globalize--border-as--footer-border: footer;
}

footer {
  --border: 1px solid red;
}

After start(), the package reads --border from footer and writes it to :root as --global-footer-border.

API

start(options?)

Starts syncing and returns a controller.

Options:

• configPrefix?: string — default --globalize--
• globalPrefix?: string — default --global-
• root?: HTMLElement — root element to set global variables on
• observeRoot?: ParentNode — root to observe for DOM mutations
• debug?: boolean

sync()

Forces a sync if the package is active.

stop()

Disconnects observers and listeners.

Limitations

• Cannot detect pure stylesheet or media query changes unless a resize or mutation triggers sync.
• Only watches the first matching child element per configured variable.
• CSS cannot do this natively; this package bridges the gap with JavaScript.

React

Here's an example of a tidy way to use this in a React project

// src/components/CssVariableGlobalizer.tsx
import { start } from "css-variable-globalizer"; // ~1.6k gzipped
import { useEffect } from "react";

/**
 * Starts css-variable-globalizer after hydration so it can safely read the DOM
 * and mirror configured CSS custom properties onto `:root`.
 */
export function CssVariableGlobalizer() {
  useEffect(() => {
    const controller = start();

    return () => {
      controller.stop();
    };
  }, []);

  return null;
}

// app or layout or main (depending on your tech stack)
// Vite/CRA-style React: src/App.tsx or the top-level provider component rendered by main.tsx
// Next.js App Router: src/app/layout.tsx
// Next.js Pages Router: src/pages/_app.tsx
import { CssVariableGlobalizer } from "/src/components/CssVariableGlobalizer";
...
<CssVariableGlobalizer />