use-css-var

Read and write a CSS custom property reactively.

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/composable

Import the entry directly. Call lifecycle-bound utilities inside <script setup> so cleanup follows the component scope; consult the runtime contract for this entry's SSR and hydration behavior.

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

Try it

Theme a card with a CSS variable

Read and write a CSS custom property on one element from script.

Open the interactive example

What to observe: Choose Blue accent: the border and the printed value change to #3b82f6. Other elements keep their own value.

Pass the element ref as the target; without one the variable is set on :root. initialValue applies before the element mounts.

Compare the initial and interacted states

Copy the example

Save this complete SFC in your Vue project. Its public imports and source are the same ones executed in the preview.

<script setup lang="ts">
import { useTemplateRef } from "vue";
import { useCssVar } from "@vizejs/composable/use-css-var";

const card = useTemplateRef<HTMLElement>("card");
const { value: accent } = useCssVar("--accent", card, { initialValue: "#42b883" });
const colors = [
  { label: "Green", value: "#42b883" },
  { label: "Blue", value: "#3b82f6" },
  { label: "Orange", value: "#f97316" },
];
</script>

<template>
  <div class="composable-example">
    <p>Theme one card by changing a CSS custom property from script.</p>
    <div class="example-actions">
      <button
        v-for="color in colors"
        :key="color.label"
        type="button"
        @click="() => (accent = color.value)"
      >
        {{ color.label }} accent
      </button>
    </div>
    <article ref="card" class="accent-card">
      Accent: <output aria-live="polite">{{ accent }}</output>
    </article>
  </div>
</template>

<style scoped>
.accent-card {
  border: 3px solid var(--accent);
  padding: 12px;
}
</style>

Runtime contract

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.

CssVarTarget

Element subset used by useCssVar.

CssVarObserver

Minimal MutationObserver instance.

CssVarHost

Capabilities used by useCssVar.

UseCssVarOptions

Options for useCssVar.

CssVarControls

Reactive state returned by useCssVar.