---
title: "useTheme"
description: "useTheme is the core composable of the theme customization system, managing the primary color, neutral color, border radius, and icon set configuration, with support for dark, light, and system color modes. From the ThemePicker, you can export CSS variables or app.config.ts configuration to persist your theme."
canonical_url: "https://docs.mhaibaraai.cn/en/docs/composables/use-theme"
---
# useTheme

> useTheme is the core composable of the theme customization system, managing the primary color, neutral color, border radius, and icon set configuration, with support for dark, light, and system color modes. From the ThemePicker, you can export CSS variables or app.config.ts configuration to persist your theme.

## Overview

`useTheme` provides complete theme customization, allowing users to dynamically adjust the site's visual style, including the color scheme, border radius, icon set, and light/dark mode switching. All configuration is automatically persisted to localStorage.

### Theme configuration options

- **Colors**: primary and neutral color configuration
- **Fonts**: 7 preset font families
- **Radius**: 5 border radius options
- **Icon sets**: Lucide / Phosphor / Tabler
- **Color mode**: light / dark / system

## Usage examples

### Basic theme switching

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

// Change the primary color
primary.value = 'blue'

// Change the neutral color
neutral.value = 'zinc'

// Change the color mode
mode.value = 'dark'
</script>
```

### Radius customization

```vue
<script setup lang="ts">
const { radius, radiuses } = useTheme()

// Adjust the border radius (in rem)
radius.value = 0.5

// Get all available options
console.log('Available radiuses:', radiuses)
</script>
```

> [!NOTE]
> 
> The font is not managed by 
> 
> useTheme
> 
> : it is build-time configuration, declared as 
> 
> --font-sans
> 
>  in the 
> 
> @theme
> 
>  block of 
> 
> app/assets/css/main.css
> 
> . Chinese fonts are split by 
> 
> unicode-range
> 
> , so switching at runtime would mean re-downloading several MB of shards — hence no switching is offered.

### Switching the icon set

```vue
<script setup lang="ts">
const { icon, icons } = useTheme()

// Switch to the Phosphor icon set
icon.value = 'phosphor'

// List all icon set options
console.log(icons)
// [
//   { label: 'Lucide', icon: 'i-lucide-feather', value: 'lucide' },
//   { label: 'Phosphor', icon: 'i-ph-phosphor-logo', value: 'phosphor' },
//   { label: 'Tabler', icon: 'i-tabler-brand-tabler', value: 'tabler' }
// ]
</script>
```

### Exporting the theme

```vue
<script setup lang="ts">
const {
  exportCSS,
  exportAppConfig,
  hasCSSChanges,
  hasAppConfigChanges
} = useTheme()

// Check whether there is custom configuration
if (hasCSSChanges.value) {
  const cssCode = exportCSS()
  console.log('CSS configuration:\n', cssCode)
}

if (hasAppConfigChanges.value) {
  const appConfigCode = exportAppConfig()
  console.log('App Config:\n', appConfigCode)
}
</script>
```

### Resetting the theme

```vue
<script setup lang="ts">
const { resetTheme } = useTheme()

function handleReset() {
  if (confirm('Are you sure you want to reset the theme to its default settings?')) {
    resetTheme()
  }
}
</script>

<template>
  <UButton @click="handleReset" color="neutral" variant="outline">
    Reset theme
  </UButton>
</template>
```

### Advanced: black primary color mode

```vue
<script setup lang="ts">
const { setBlackAsPrimary } = useTheme()

// Enable black primary color mode
// Use black as the primary color in light mode and white in dark mode
setBlackAsPrimary(true)
</script>
```

## API

### `useTheme()`

Returns the theme configuration management object, containing all theme-related state and operations.

### Return values

**primary** (`Ref<string>`): The primary color, chosen from the Tailwind colors (excluding neutral colors).

**primaryColors** (`string[]`): The array of all available primary color options.

**neutral** (`Ref<string>`): The neutral color. Possible values: slate / gray / zinc / neutral / stone / taupe / mauve / mist / olive.

**neutralColors** (`string[]`): The array of all available neutral color options.

**radius** (`Ref<number>`): The border radius (in rem). Possible values: 0 / 0.125 / 0.25 / 0.375 / 0.5.

**radiuses** (`number[]`): The array of all available radius options.

**icon** (`Ref<string>`): The icon set. Possible values: lucide / phosphor / tabler.

**icons** (`Array<{ label: string; icon: string; value: string }>`): All available icon set options, each containing a label, icon class name, and value.

**mode** (`Ref<'light' | 'dark' | 'system'>`): The color mode, supporting light, dark, and follow-system modes.

**modes** (`Array<{ label: string; icon: string }>`): All color mode options, each containing a label and corresponding icon.

**setBlackAsPrimary** (`(value: boolean) => void`): Set whether to use black as the primary color (black in light mode, white in dark mode).Whether to enable black primary color mode.

**blackAsPrimary** (`Ref<boolean>`): A computed property: whether black primary color mode is currently enabled.

**hasCSSChanges** (`Ref<boolean>`): A computed property that determines whether there is CSS-related custom configuration (radius, font, black primary color, custom colors, CSS variables).

**hasAppConfigChanges** (`Ref<boolean>`): A computed property that determines whether there is App Config–related custom configuration (primary color, neutral color, icon set).

**exportCSS** (`() => string`): Export the current theme's CSS configuration code, including the Tailwind CSS variable declarations.

**exportAppConfig** (`() => string`): Export the current theme's app/app.config.ts configuration code.

**resetTheme** (`() => void`): Reset all theme settings to their default values and clear the persisted data in localStorage.

## Persistence mechanism

All theme configuration is automatically saved to localStorage, with key names in the format `{site name}-ui-{option}`:

- `{site name}-ui-primary`: the primary color configuration
- `{site name}-ui-neutral`: the neutral color configuration
- `{site name}-ui-radius`: the radius configuration
- `{site name}-ui-icons`: the icon set configuration
- `{site name}-ui-black-as-primary`: black primary color mode

## 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.