# @askrjs/themes/theme

> Published API exports for @askrjs/themes/theme.

Source: [https://askrjs.com/docs/reference/api/themes/theme](https://askrjs.com/docs/reference/api/themes/theme)

Status: stable. Packages: @askrjs/themes/theme.

**Published packages are authoritative.** Examples may lag behind a published contract. When guidance differs, verify the exports and TypeScript declarations in your installed package, then file an issue.

## Exports

This entrypoint publishes 15 exports from the declarations shipped by @askrjs/themes.

### `CAT_THEME_NAMES`

```ts
CAT_THEME_NAMES: readonly ["tabby", "ginger", "tuxedo", "calico", "torty"]
```

Names of the built-in "cat" theme presets.

### `CAT_THEME_OPTIONS`

```ts
CAT_THEME_OPTIONS: readonly ThemeOption[]
```

Theme options for the built-in "cat" theme presets, keyed to {@link CAT_THEME_NAMES}.

### `CatThemeName`

```ts
CatThemeName: (typeof CAT_THEME_NAMES)[number]
```

A built-in "cat" theme name, one of {@link CAT_THEME_NAMES}.

### `DEFAULT_THEME_OPTIONS`

```ts
DEFAULT_THEME_OPTIONS: readonly ThemeOption[]
```

Default light/dark/system theme options used by {@link ThemeScope} and {@link ThemePicker}.

### `theme`

```ts
theme: () => ThemeScopeValue
```

Reads the current {@link ThemeScopeValue} from the nearest enclosing {@link ThemeScope}.

### `ThemeName`

```ts
ThemeName: "light" | "dark" | "system" | CatThemeName | (string & {})
```

Any theme identifier accepted by {@link ThemeScope}: `"light"`, `"dark"`, `"system"`, a {@link CatThemeName}, or a custom string.

### `ThemeOption`

```ts
ThemeOption: {
  value: ThemeName;
  label: string;
}
```

A theme choice offered by {@link ThemePicker}/{@link ThemeToggle}: a `value` paired with a display `label`.

### `ThemePicker`

```ts
ThemePicker: (props: ThemePickerProps) => JSX.Element
```

A `<select>` bound to the current {@link theme}, listing `themes` (defaults to the enclosing scope's options).

### `ThemePickerProps`

```ts
ThemePickerProps: Omit<JSX.IntrinsicElements["select"], "children" | "value" | "defaultValue" | "onChange"> & {
  themes?: readonly ThemeOption[];
  label?: string;
}
```

Props for the {@link ThemePicker} component.

- `label`: label?: string | undefined;

- `themes`: themes?: readonly ThemeOption[] | undefined;

### `ThemeScope`

```ts
ThemeScope: (props: ThemeScopeProps) => JSX.Element
```

Establishes a theme boundary: tracks the active theme (persisted to
`localStorage` under `storageKey` and synced across tabs/scopes), resolves
the OS `"system"` preference, and reflects the choice onto the DOM via
`data-theme`/`data-theme-choice` attributes. Nested scopes cooperate
through a shared coordinator so the deepest explicitly-set scope wins.

### `ThemeScopeProps`

```ts
ThemeScopeProps: {
  children?: unknown;
  defaultTheme?: ThemeName;
  themes?: readonly ThemeOption[];
  storageKey?: string;
}
```

Props for the {@link ThemeScope} component.

- `children`: children?: unknown;

- `defaultTheme`: defaultTheme?: ThemeName | undefined;

- `storageKey`: storageKey?: string | undefined;

- `themes`: themes?: readonly ThemeOption[] | undefined;

### `ThemeScopeValue`

```ts
ThemeScopeValue: {
  theme: () => ThemeName;
  resolvedSystemTheme: () => "light" | "dark";
  setTheme: (theme: ThemeName) => void;
  themes: readonly ThemeOption[];
  storageKey: string;
}
```

Value read from {@link theme}: the active theme, its resolved system value, a setter, and the available theme options.

### `ThemeToggle`

```ts
ThemeToggle: (props: ThemeToggleProps) => JSX.Element
```

A button that cycles through `themes` (defaults to `["light", "dark"]`) on
press. Supports icon props per theme, or a function-as-children render
prop receiving {@link ThemeToggleRenderContext}.

### `ThemeToggleProps`

```ts
ThemeToggleProps: Omit<ButtonNativeProps, "children" | "onPress"> & {
  children?: unknown | ((context: ThemeToggleRenderContext) => unknown);
  lightIcon?: unknown;
  darkIcon?: unknown;
  systemIcon?: unknown;
  themes?: readonly ThemeName[];
  onPress?: (event: PressEvent) => void;
}
```

Props for the {@link ThemeToggle} component.

- `children`: children?: unknown;

- `darkIcon`: darkIcon?: unknown;

- `lightIcon`: lightIcon?: unknown;

- `onPress`: onPress?: ((event: PressEvent) => void) | undefined;

- `systemIcon`: systemIcon?: unknown;

- `themes`: themes?: readonly ThemeName[] | undefined;

### `ThemeToggleRenderContext`

```ts
ThemeToggleRenderContext: {
  theme: ThemeName;
  nextTheme: ThemeName;
}
```

Render context passed to a function-as-children {@link ThemeToggleProps.children}.

## Documentation navigation

[Previous](https://askrjs.com/docs/reference/api/themes/components/index.md) | [Next](https://askrjs.com/docs/reference/api/themes/ssr/index.md)