useTheme
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
slate / gray / zinc / neutral / stone / taupe / mauve / mist / olive.0 / 0.125 / 0.25 / 0.375 / 0.5.Alibaba PuHuiTi / Public Sans / DM Sans / Geist / Inter / Poppins / Outfit / Raleway (8 in total).lucide / phosphor / tabler.app/app.config.ts configuration code.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
useCategory
useCategory manages the category configuration system for the documentation sidebar, defining each category's display title and ordering rules via the categories property to group component or composable documentation by feature. Override the implementation at app/composables/useCategory.ts to customize the category configuration.
useFetchComponentMeta
useFetchComponentMeta fetches the metadata of Vue components registered via nuxt-component-meta, including the complete type definitions for Props, Events, and Slots. It returns a reactive useAsyncData ref, with automatic cache reuse during SSR and client-side navigation, and zero duplicate requests.