---
title: Set up appearance preferences
description: Aggregate appearance definitions and effects with the application's shared preferences.
order: 1
toc:
  - id: provider
    title: Aggregate preferences
  - id: effects
    title: Register effects
  - id: theme-style
    title: Inject theme variables
  - id: persistence
    title: Persist updates
---

## Aggregate preferences {#provider}

Build one complete preference definition map at the application boundary. Spread definitions from appearance, locale, keyboard, and other feature packages into this map, then create or load the initial values.

```tsx
import {
  createDefaultPreferences,
  PreferencesProvider,
} from "@workspace/preferences"
import {
  appearancePreferenceDefinitions,
  appearancePreferenceEffect,
} from "@workspace/appearance"

const preferenceDefinitions = {
  ...appearancePreferenceDefinitions,
  ...localePreferenceDefinitions,
}

const initialPreferences = createDefaultPreferences(preferenceDefinitions)
const preferenceEffects = [
  appearancePreferenceEffect,
  localePreferenceEffect,
] as const

export function Root({ children }: { children: React.ReactNode }) {
  return (
    <PreferencesProvider
      effects={preferenceEffects}
      initialPreferences={initialPreferences}
    >
      {children}
    </PreferencesProvider>
  )
}
```

`defaultAppearancePreferences` remains available when only the appearance slice is needed, but the definition map is the preferred source when several packages are combined.

## Register effects {#effects}

`appearancePreferenceEffect` combines two exported callbacks: `applyAppearancePreferenceEffect` updates document classes and theme variables before paint, while `subscribeSystemThemePreferenceEffect` watches the operating-system theme after paint. Register the composed effect in the stable `effects` array passed to `PreferencesProvider`.

## Inject theme variables {#theme-style}

Use `buildThemeStyleSheet` to generate the CSS variables for light, dark, and system modes. Keep the stable element ID so the appearance effect can update the same node when color preferences change.

```tsx
import {
  buildThemeStyleSheet,
  THEME_STYLE_ELEMENT_ID,
} from "@workspace/appearance"

;<style
  id={THEME_STYLE_ELEMENT_ID}
  dangerouslySetInnerHTML={{
    __html: buildThemeStyleSheet(themeLight, themeDark),
  }}
/>
```

## Persist updates {#persistence}

The shared `onPreferenceChange` receives a typed `{ key, value }` only when a value actually changes. Forward it to a server function or cookie writer owned by the application.

```tsx
<PreferencesProvider
  effects={preferenceEffects}
  initialPreferences={preferences}
  onPreferenceChange={(update) => savePreference(update)}
>
  {children}
</PreferencesProvider>
```