Browser

useCssVar

Reactively read and write CSS custom properties (CSS variables) on DOM elements.

Demo

useCssVar

Reactively read and write CSS custom properties on DOM elements.

#7fa998

CSS Variable

--demo-bg

Value

#7fa998

Usage

Hook
Scope

import { 
import useRef$
useRef$, 
const useCssVar: (prop: MaybeObservable<string | null | undefined>, target?: MaybeEventTarget, options?: DeepMaybeObservable<UseCssVarOptions>) => UseCssVarReturn
useCssVar } from "@usels/web";

function 
function Component(): JSX.Element
Component() {
  const 
const el$: any
el$ = 
import useRef$
useRef$<
interface HTMLDivElement
HTMLDivElement>();
  const 
const color$: any
color$ = 
function useCssVar(prop: MaybeObservable<string | null | undefined>, target?: MaybeEventTarget, options?: DeepMaybeObservable<UseCssVarOptions>): UseCssVarReturn
Framework-agnostic reactive CSS custom property (CSS variable) tracker.
Creates an Observable<string> that reflects (and writes back to) a CSS
custom property on a DOM element. Reactive inputs (prop, target, and
options) propagate through observe() — the old property is cleaned off
the previous element before the new one is written.
Must be called inside a useScope factory.
useCssVar("--color", 
const el$: any
el$);

  // Read the value
  
const color$: any
color$.
any
get(); // → "#7fa998"

  // Set the value
  
const color$: any
color$.
any
set("#df8543");

  return <
JSX.IntrinsicElements.div: DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>
div 
RefAttributes<HTMLDivElement>.ref?: Ref<HTMLDivElement> | undefined
Allows getting a ref to the component instance.
Once the component unmounts, React will set ref.current to null
(or call the ref with null if you passed a callback ref).
@see ― https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom React Docs
ref={
const el$: any
el$} />;
}

import { createRef$ } from "@usels/core";
import { createCssVar } from "@usels/web";

function Component() {
  "use scope";
  const el$ = createRef$<HTMLDivElement>();
  const color$ = createCssVar("--color", el$);

  color$.get();
  color$.set("#df8543");

  return <div ref={el$} />;
}

Default to documentElement

When no target is provided, useCssVar operates on document.documentElement.

// @noErrors
import { useCssVar } from "@usels/web";

const theme$ = useCssVar("--theme-color");
theme$.get(); // reads from :root
theme$.set("#ff0000"); // sets on :root

With initialValue

import { useCssVar } from "@usels/web";

const color$ = useCssVar("--color", el$, { initialValue: "#000000" });

With MutationObserver

Use observe: true to re-read the CSS variable when the element’s style or class attributes change externally.

import { useCssVar } from "@usels/web";

const color$ = useCssVar("--color", el$, { observe: true });

Type

Parameters

Parameter	Type	Description
`prop`	`MaybeObservable<string \| null \| undefined>`	-
`target`	`MaybeEventTarget` (optional)	-
`options`	`UseCssVarOptions` (optional)	-

UseCssVarOptions

Option	Type	Default	Description
`initialValue`	`string`	`-`	-
`observe`	`boolean`	`false`	Use MutationObserver to monitor variable changes
`window`	`WindowSource`	`-`	-

Returns

ObservablePrimitive<string>

Name	Type	Description
`peek`	`{ (): string; (): string; }`	-
`get`	`(trackingType?: TrackingType \| GetOptions) => string`	-
`onChange`	`(cb: ListenerFn<string>, options?: { trackingType?: TrackingType; initial?: boolean \| undefined; immediate?: boolean \| undefined; noArgs?: boolean \| undefined; } \| undefined) => () => void`	-
`set`	`{ (value: (prev: string) => string): void; (value: ObservablePrimitive<string>): void; (value: string \| ImmutableObservableBase<string> \| Promise<...> \| (() => string \| ... 1 more ... \| Promise<...>)): void; (value: Promise<...>): void; (value: string): void; }`	-
`delete`	`() => void`	-

Source

View on GitHub