use-css-var

Read and write a CSS custom property reactively.


Package	`@vizejs/composable/use-css-var`
Own the source	`vize lib pull composable:use-css-var`
Runtime exports	`useCssVar`
Gzip budget	2048 B

Usage

import { useCssVar } from "@vizejs/composable/use-css-var";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useCssVar`	dom	experimental	deterministic-fallback	caller-managed	reactive-scope	web, desktop	`window`	—

API

`useCssVar`

Read and write a CSS custom property reactively. The value is read from the target's computed style whenever the reactive name, target, or host changes (and, with observe, when its style/class attribute changes). Assigning value writes an inline style.setProperty; assigning "" removes the inline declaration. Values read from the element are never written back, so a stylesheet-provided variable is not frozen into inline style. Server rendering: nothing is read or written; value holds initialValue. Keep server markup and the first client render identical by rendering from initialValue until mounted. The observer and watchers are released with the owning reactive scope.

function useCssVar( name: MaybeRefOrGetter<string>, target?: MaybeRefOrGetter<CssVarTarget | null | undefined>, options: UseCssVarOptions = {}, ): CssVarControls

const accent = useCssVar("--accent", rootRef, { initialValue: "#0af" });
accent.value.value = "#f60";

Types

`CssVarStyle`

Style declaration subset used by useCssVar.

Member	Type	Description
`getPropertyValue`	`(name: string) => string`	Read a property value.
`setProperty`	`(name: string, value: string \| null) => void`	Write a property value.
`removeProperty`	`(name: string) => string`	Remove a property.

`CssVarTarget`

Element subset used by useCssVar.

Member	Type	Description
`style`	`CssVarStyle`	Inline style declaration.

`CssVarObserver`

Minimal MutationObserver instance.

Member	Type	Description
`observe`	`(target: CssVarTarget, options: { attributes: true; attributeFilter: string[] }) => void`	Start observing `target`.
`disconnect`	`() => void`	Stop observing.

`CssVarHost`

Capabilities used by useCssVar.

Member	Type	Description
`getComputedStyle`	`(target: CssVarTarget) => Pick<CssVarStyle, "getPropertyValue">`	Resolved (computed) style of a target.
`documentElement`	`CssVarTarget`	Target used when none is given (the document root element).
`createObserver`?	`(callback: () => void) => CssVarObserver`	Observer factory used when `observe` is enabled.

`UseCssVarOptions`

Options for useCssVar.

Member	Type	Description
`initialValue`?	`string`	Value used while the variable is unset and during server rendering.
`observe`?	`boolean`	Re-read the variable when the target's `style` or `class` attribute changes (MutationObserver).
`host`?	`MaybeRefOrGetter<CssVarHost \| null \| undefined>`	Style capability for alternate runtimes and tests.

`CssVarControls`

Reactive state returned by useCssVar.

Member	Type	Description
`value`	`Ref<string>`	Writable variable value; assignments are written as inline style.
`supported`	`ComputedRef<boolean>`	Whether a style capability and target are attached.