ThemeToggle

Usage examples

import { useState } from 'react';
import { ThemeToggle, type ShellCookieStore, type ThemePreference } from '@rookcom/monarch-react/shell';

/** Docs examples keep their choice in memory, so they never change this site's own theme. */
function useDemoCookies(initial?: ThemePreference): ShellCookieStore {
  const [store] = useState<ShellCookieStore>(() => {
    const jar = new Map<string, string>(initial ? [['rook_theme', initial]] : []);
    return { get: (n) => jar.get(n) ?? null, set: (n, v) => void jar.set(n, v) };
  });
  return store;
}

function MenuDemo() {
  const cookies = useDemoCookies('dark');
  return (
    <div style={{ display: 'flex', gap: 'var(--mn-space-3)', alignItems: 'center' }}>
      <ThemeToggle variant="menu" cookies={cookies} applyToDocument={false} />
      <ThemeToggle variant="menu" showLabel={false} cookies={cookies} applyToDocument={false} />
    </div>
  );
}

<MenuDemo />

import { useState } from 'react';
import { ThemeToggle, type ThemePreference } from '@rookcom/monarch-react/shell';

function ControlledDemo() {
  const [theme, setTheme] = useState<ThemePreference>('light');
  return (
    <div style={{ display: 'grid', gap: 'var(--mn-space-2)' }}>
      <ThemeToggle
        size="sm"
        value={theme}
        onValueChange={setTheme}
        cookies={null}
        applyToDocument={false}
        messages={{ label: 'Appearance' }}
      />
      <p style={{ margin: 0, color: 'var(--mn-color-text-muted)', fontSize: 'var(--mn-text-sm)' }}>
        Saved preference: {theme}
      </p>
    </div>
  );
}

<ControlledDemo />

Purpose

Lets a person choose the Rook theme once and have every Rook app follow it. The choice lives in the rook_theme cookie (on .rookhq.com by default) and is applied to <html> exactly as appearanceScript() from @rookcom/monarch-tokens applies it before first paint. Needed by: app, calendar, friends, signal.

Design principles

• Three choices, always including System, so the OS setting is respected (one of the two capabilities the registry found missing).
• One source of truth: the shared cookie. The toggle never keeps a second copy that could disagree with another app.
• Hydration-safe: the server renders defaultValue, the client switches to the saved choice through useSyncExternalStore, and the pre-paint script has already painted the right theme.
• Cookie I/O is injectable (cookies), so tests, docs and embedded frames never touch the real cookie.

API reference

import { ROOK_THEME_COOKIE, ROOK_THEME_EVENT, ThemeToggle, applyThemePreference } from '@rookcom/monarch-react/shell';

applyThemePreference(preference, root?) applies a preference the same way the toggle does and returns the resolved theme. Use it after reading the cookie on your own.

ROOK_THEME_COOKIE (rook_theme) and ROOK_THEME_EVENT (rook-theme, fired on window after every change) are the cross-app contract.

ShellCookieStore is { get(name), set(name, value, { maxAge, domain }) }.

Generated from the TypeScript declarations of packages/react/src/components/interaction/theme-toggle.

Properties

Controlled with value + onValueChange, or uncontrolled (reads and writes the cookie).

cookies={null} keeps the choice in memory for this page only; applyToDocument={false} leaves <html> alone.

Variants

States

Interaction behaviour

• Choosing saves the cookie for a year, applies the theme to <html>, fires rook-theme and calls onValueChange.
• Every toggle on the page re-reads the cookie on rook-theme, on window focus and when the tab becomes visible, so a change made in another Rook app shows up when you come back.
• The contrast preference (data-mn-contrast) is kept as it is.

Keyboard support

Accessibility

Role

radiogroup (segmented) or a menu button with menuitemradio items (menu)

Accessible name

messages.label (default "Theme"); the menu button adds the current choice: "Theme: System".

• Built on SegmentedControl and DropdownMenu from @rookcom/monarch-react, which follow the APG radio group and menu button patterns.
• Icons are decorative; every choice has a text label, also when the menu button hides its text.
• Changing the theme does not move focus.

Responsive behaviour

• The segmented control never grows wider than its container.
• In a collapsed rail use variant="menu" with showLabel={false}; the menu opens to the side you choose (side="right").

Theme support

• Uses the theme of the surface it sits on: tokens only, so light, dark and more-contrast all apply.
• Pair with appearanceScript({ themeCookie: "rook_theme" }) in <head> for a flash-free first paint.

Do and don't

Related components

• RookRail: Has a slot for the theme toggle.
• SegmentedControl: The control the segmented variant is built on.
• DropdownMenu: The menu the menu variant is built on.
• Brand Theme Engine (stable): Product accents, which the theme combines with.

Dependencies

Testing coverage

• Labelled radio group with the saved choice checked; unknown cookie values fall back to the default.
• Choosing writes the cookie (name, one-year max-age, domain), applies the theme to <html> and calls onValueChange; cookie name and domain are configurable.
• Arrow keys move and select; controlled mode follows the value prop only.
• Menu variant: the button names the current choice, the menu has checked radio items, choosing applies; hidden text and translated messages.
• system follows the OS, data-rook-theme-routes keeps other routes light, contrast is kept.
• Server render uses the default and hydration switches to the saved choice without errors.

Tests: packages/react/src/components/interaction/theme-toggle