useTheme

useTheme reads and changes the theme, the accent and the color scheme that ClawscaleProvider manages.

Usage#

import { useTheme } from "@clawscale/react";

const { theme, setTheme, accent, setAccent, colorScheme, resolvedColorScheme, setColorScheme } = useTheme();

Outside a ClawscaleProvider, it returns the default theme in light and setters that do nothing.

Return value#

Property	Type	Description
`theme`	`ThemeName`	The theme: `"default"` or your own.
`setTheme`	`(theme: ThemeName) => void`	Changes the theme and saves it.
`accent`	`string \| undefined`	The accent someone picked, such as `"teal"`. `undefined` means the theme's own.
`setAccent`	`(accent: string \| undefined) => void`	Changes the accent and saves it.
`colorScheme`	`ColorSchemePreference`	The saved preference: `"light"`, `"dark"` or `"system"`.
`resolvedColorScheme`	`ColorScheme`	The color scheme applied now: `"light"` or `"dark"`.
`setColorScheme`	`(colorScheme: ColorSchemePreference) => void`	Changes the preference and saves it.

@clawscale/react exports these types, and ThemeContextValue for the whole object. resolvedTheme remains as a deprecated name for resolvedColorScheme until 1.0.

During server rendering and hydration, theme, accent and colorScheme equal their defaults and "system" resolves to light. The saved values arrive right after hydration. For styles, prefer the --cs-* tokens: they follow the theme, the accent and the color scheme without a render.

Examples#

Toggle#

Pick the next color scheme from resolvedColorScheme. This button changes the color scheme of these docs.

core/use-theme/toggle.tsx

import { Button, useTheme } from "@clawscale/react";

export default function UseThemeToggle() {
  const { resolvedColorScheme, setColorScheme } = useTheme();
  const isDark = resolvedColorScheme === "dark";
  return (
    <Button
      icon={isDark ? "flash" : "moon"}
      text={isDark ? "Switch to light" : "Switch to dark"}
      onClick={() => setColorScheme(isDark ? "light" : "dark")}
    />
  );
}

Resolved values#

colorScheme can be "system". resolvedColorScheme is always light or dark. Use both values for what CSS cannot reach, such as colors drawn on a canvas.

theme: default
colorScheme: system
resolvedColorScheme: light
Chart line: #3563E9

core/use-theme/resolved.tsx

import { PropertyList, PropertyListItem, useTheme } from "@clawscale/react";
import { type BuiltInThemeName, chartPalettes } from "@clawscale/tokens";

export default function UseThemeResolved() {
  const { theme, colorScheme, resolvedColorScheme } = useTheme();
  // Colors for a canvas chart, which CSS variables cannot reach.
  const palette = chartPalettes[theme as BuiltInThemeName] ?? chartPalettes.default;
  return (
    <PropertyList style={{ width: "100%", maxWidth: 340 }}>
      <PropertyListItem label="theme" monospace>
        {theme}
      </PropertyListItem>
      <PropertyListItem label="colorScheme" monospace>
        {colorScheme}
      </PropertyListItem>
      <PropertyListItem label="resolvedColorScheme" monospace>
        {resolvedColorScheme}
      </PropertyListItem>
      <PropertyListItem label="Chart line" monospace>
        {palette[resolvedColorScheme][0]}
      </PropertyListItem>
    </PropertyList>
  );
}