---
title: "useTheme"
description: "The state and actions behind the theme picker - primary color, neutral color, radius, icon set, black as primary and color mode. Visitor choices persist in localStorage and can be exported as app.config or CSS. Use it for a custom theme picker or to switch themes from a page."
canonical_url: "https://docs.mhaibaraai.cn/en/docs/reference/composables/use-theme"
---
# useTheme

> The state and actions behind the theme picker - primary color, neutral color, radius, icon set, black as primary and color mode. Visitor choices persist in localStorage and can be exported as app.config or CSS. Use it for a custom theme picker or to switch themes from a page.

`useTheme()` drives the `ThemePicker` in the header. The theme configured in `app.config` is the baseline; visitor changes in the picker override it and persist to localStorage under keys prefixed with the site name (`site.name` in kebab-case).

## Usage

```vue
<script setup lang="ts">
const { primary, neutral, mode, resetTheme } = useTheme()
</script>

<template>
  <UButton label="Blue" @click="primary = 'blue'" />
  <UButton label="Dark" @click="mode = 'dark'" />
  <UButton label="Reset" @click="resetTheme()" />
</template>
```

## Signature

```ts
function useTheme(): {
  primary: WritableComputedRef<string>
  primaryColors: string[]
  neutral: WritableComputedRef<string>
  neutralColors: string[]
  radius: WritableComputedRef<number>
  radiuses: number[]
  icon: WritableComputedRef<string>
  icons: { label: string, icon: string, value: string }[]
  mode: WritableComputedRef<string>
  modes: ComputedRef<{ label: string, icon: string }[]>
  blackAsPrimary: ComputedRef<boolean>
  setBlackAsPrimary: (value: boolean) => void
  color: ComputedRef<string | undefined>
  style: { innerHTML: ComputedRef<string>, id: string, tagPriority: number }[]
  hasCSSChanges: ComputedRef<boolean>
  hasConfigChanges: ComputedRef<boolean>
  configLabel: string
  exportCSS: () => string
  exportConfig: () => string
  resetTheme: () => void
}
```

## Return Value

| Name | Type | Description |
| --- | --- | --- |
| `primary` | `WritableComputedRef<string>` | Primary color, written to `appConfig.ui.colors.primary`; setting it turns off black as primary |
| `primaryColors` | `string[]` | Available primary colors: `vermilion` plus the chromatic Tailwind palettes |
| `neutral` | `WritableComputedRef<string>` | Neutral color, written to `appConfig.ui.colors.neutral` |
| `neutralColors` | `string[]` | Available neutrals: `paper`, `slate`, `gray`, `zinc`, `neutral`, `stone`, `taupe`, `mauve`, `mist`, `olive` |
| `radius` | `WritableComputedRef<number>` | Border radius in rem |
| `radiuses` | `number[]` | Available radii: `0`, `0.125`, `0.25`, `0.375`, `0.5` |
| `icon` | `WritableComputedRef<string>` | Icon set; writing it also replaces `appConfig.ui.icons` |
| `icons` | `{ label, icon, value }[]` | Available icon sets: `lucide`, `phosphor`, `tabler` |
| `mode` | `WritableComputedRef<string>` | Color mode, written to `colorMode.preference` |
| `modes` | `ComputedRef<{ label, icon }[]>` | `light`, `dark` and `system` |
| `blackAsPrimary` | `ComputedRef<boolean>` | Whether black (white in dark mode) is used as the primary color |
| `setBlackAsPrimary` | `(value: boolean) => void` | Toggle black as primary |
| `color` | `ComputedRef<string \| undefined>` | The neutral 50 / 950 shade for the current mode, used for `theme-color` |
| `style` | `object[]` | `<style>` tags for radius and black as primary, injected into head by the shell |
| `hasCSSChanges` | `ComputedRef<boolean>` | Whether radius or black as primary differs from the baseline |
| `hasConfigChanges` | `ComputedRef<boolean>` | Whether primary, neutral or icon set differs from the baseline |
| `configLabel` | `string` | File name of the exported config, always `app.config.ts` |
| `exportCSS` | `() => string` | Export CSS variables that differ from the baseline |
| `exportConfig` | `() => string` | Export `defineAppConfig(...)` code for values that differ from the baseline |
| `resetTheme` | `() => void` | Clear visitor preferences and restore the `app.config` baseline |

## Baseline

The baseline is read from `app.config` on first call: `ui.colors.primary`, `ui.colors.neutral`, plus `theme.radius` (default `0.25`), `theme.icons` (default `lucide`) and `theme.blackAsPrimary` (default `false`). To change the site's default theme, edit `app.config` rather than writing these refs in code, see [Theme and Fonts](https://docs.mhaibaraai.cn/en/docs/guide/theme).

## Changelog

See commit history for [layer/app/composables/useTheme.ts](https://github.com/mhaibaraai/movk-nuxt-docs/commits/main/layer/app/composables/useTheme.ts).

---

- [GitHub](https://github.com/mhaibaraai/movk-nuxt-docs/blob/main/layer/app/composables/useTheme.ts)


## Sitemap

See the full [sitemap](https://docs.mhaibaraai.cn/sitemap.md) for all pages.
