useTheme
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
| 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.
Changelog
useCategory
Provides the sidebar category definitions that decide how pages with a category are grouped and ordered within a section. Declare them in docs.categories in app.config; override the composable in your project only when categories must be computed at runtime.
useDocsRoute
Check whether the current route is a docs page, covering /docs/* for the default locale and /{locale}/docs/* for others. Use it in site-wide components such as a custom header or footer that should show something only on docs pages.