useTheme

useTheme is the core composable of the theme customization system, managing the primary color, neutral color, border radius, font family, 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, font selection, 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

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

Font and radius customization

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

// Change the font
font.value = 'Inter'

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

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

Switching the icon set

<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

<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

<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

<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.
font
Ref<string>
The font family. Possible values: Alibaba PuHuiTi / Public Sans / DM Sans / Geist / Inter / Poppins / Outfit / Raleway (8 in total).
fonts
string[]
The array of all available font 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).
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-font: the font configuration
  • {site name}-ui-icons: the icon set configuration
  • {site name}-ui-black-as-primary: black primary color mode

Changelog

No recent changes
Copyright © 2024 - 2026