---
title: Define and provide preferences
description: Declare the application preference shape and mount the provider with an SSR-safe snapshot.
order: 10
toc:
  - id: declare-preferences
    title: Declare preferences
  - id: define-defaults
    title: Define defaults
  - id: mount-the-provider
    title: Mount the provider
---

## Declare preferences {#declare-preferences}

Use module augmentation in an application-owned TypeScript module:

```ts
import "@workspace/preferences"

declare module "@workspace/preferences" {
  interface PreferencesCustom {
    "navigation-density": "comfortable" | "compact"
    "theme-mode": "light" | "dark" | "system"
  }
}
```

The declaration updates `Preferences`, `PreferenceKey`, `PreferenceValue`, `PreferenceUpdate`, and both preference hooks.

## Define defaults {#define-defaults}

Definitions keep parsing, serialization, defaults, and runtime validation together:

```ts
const definitions = {
  "navigation-density": {
    cookie: "navigation-density",
    defaultValue: "comfortable",
    is: (value) => value === "comfortable" || value === "compact",
    parse: (value) => (value === "compact" ? "compact" : "comfortable"),
    serialize: (value) => value,
  },
  "theme-mode": {
    cookie: "theme-mode",
    defaultValue: "system",
    is: (value) => value === "light" || value === "dark" || value === "system",
    parse: (value) =>
      value === "light" || value === "dark" ? value : "system",
    serialize: (value) => value,
  },
} satisfies PreferenceDefinitions<Preferences>

const defaultPreferences = createDefaultPreferences(definitions)
```

## Mount the provider {#mount-the-provider}

Pass the complete server-derived snapshot to the provider:

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

Read one preference with an API matching `useState`:

```tsx
const [themeMode, setThemeMode] = usePreference("theme-mode")
```