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

<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

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

NameTypeDescription
primaryWritableComputedRef<string>Primary color, written to appConfig.ui.colors.primary; setting it turns off black as primary
primaryColorsstring[]Available primary colors: vermilion plus the chromatic Tailwind palettes
neutralWritableComputedRef<string>Neutral color, written to appConfig.ui.colors.neutral
neutralColorsstring[]Available neutrals: paper, slate, gray, zinc, neutral, stone, taupe, mauve, mist, olive
radiusWritableComputedRef<number>Border radius in rem
radiusesnumber[]Available radii: 0, 0.125, 0.25, 0.375, 0.5
iconWritableComputedRef<string>Icon set; writing it also replaces appConfig.ui.icons
icons{ label, icon, value }[]Available icon sets: lucide, phosphor, tabler
modeWritableComputedRef<string>Color mode, written to colorMode.preference
modesComputedRef<{ label, icon }[]>light, dark and system
blackAsPrimaryComputedRef<boolean>Whether black (white in dark mode) is used as the primary color
setBlackAsPrimary(value: boolean) => voidToggle black as primary
colorComputedRef<string | undefined>The neutral 50 / 950 shade for the current mode, used for theme-color
styleobject[]<style> tags for radius and black as primary, injected into head by the shell
hasCSSChangesComputedRef<boolean>Whether radius or black as primary differs from the baseline
hasConfigChangesComputedRef<boolean>Whether primary, neutral or icon set differs from the baseline
configLabelstringFile name of the exported config, always app.config.ts
exportCSS() => stringExport CSS variables that differ from the baseline
exportConfig() => stringExport defineAppConfig(...) code for values that differ from the baseline
resetTheme() => voidClear 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.

Changelog

No recent changes
Copyright © 2024 - 2026