color-mode

Reactive color mode with persistence and DOM application.


Package	`@vizejs/composable/color-mode`
Own the source	`vize lib pull composable:color-mode`
Runtime exports	`useColorMode`, `useDark`
Gzip budget	3840 B

Usage

import { useColorMode, useDark } from "@vizejs/composable/color-mode";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useColorMode`	media	experimental	deterministic-fallback	caller-managed	reactive-scope	web, desktop	`document`, `window`	`useMediaQuery`, `resolveElement`, `tryOnScopeDispose`
`useDark`	media	experimental	deterministic-fallback	caller-managed	reactive-scope	web, desktop	`document`, `window`	`useColorMode`

API

`useColorMode`

Reactive color mode with persistence and DOM application. The stored mode is read synchronously during setup through the injected storage, so a cookie adapter yields identical server and client renders. On the client the resolved mode is written to the target's class list (or attribute) after each change, optionally with transitions suppressed. Nothing touches the DOM during server rendering.

function useColorMode<const Custom extends string = never>( options: UseColorModeOptions<Custom> = {}, ): ColorModeControls<Custom>

`useDark`

Boolean dark-mode switch built on useColorMode. Setting the ref to the current system preference stores "auto", so the page keeps following the system until the user picks the opposite mode.

function useDark(options: UseDarkOptions = {}): WritableComputedRef<boolean>

Types

`UseColorModeOptions`

Options for useColorMode.

Member	Type	Description
`modes`?	`Readonly<Partial<Record<BasicColorMode, string>> & Record<Custom, string>>`	Class name (or attribute value) written for each mode. Custom modes must be listed here.
`attribute`?	`string`	`"class"` toggles class names; any other value is used as an attribute name (e.g. `"data-theme"`).
`target`?	`MaybeElementTarget`	Element that receives the class/attribute.
`initialValue`?	`ColorModeValue<Custom>`	Mode used when nothing is stored.
`storageKey`?	`string \| null`	Storage key. `null` disables persistence.
`storage`?	`ColorModeStorage \| null`	Persistence adapter. `null` disables persistence.
`ssrSystem`?	`BasicColorMode`	System preference assumed while no media capability exists (server rendering).
`disableTransition`?	`boolean`	Suppress CSS transitions for one frame while switching modes.
`host`?	`MaybeRefOrGetter<MediaQueryHost \| null \| undefined>`	Media capability used to read `prefers-color-scheme`.

`ColorModeControls`

Reactive color mode returned by useColorMode.

Member	Type	Description
`mode`	`WritableComputedRef<ColorModeValue<Custom>>`	Selected mode, including `"auto"`. Assigning persists and applies it.
`system`	`ComputedRef<BasicColorMode>`	System preference from `prefers-color-scheme`.
`state`	`ComputedRef<BasicColorMode \| Custom>`	Resolved mode (`"auto"` replaced by the system preference).
`stored`	`ComputedRef<ColorModeValue<Custom>>`	Value read from storage at creation (or the initial value).

`UseDarkOptions`

Options for useDark.

Member	Type	Description
`valueDark`?	`string`	Class/attribute value applied in dark mode.
`valueLight`?	`string`	Class/attribute value applied in light mode.