Theming

Theming in uView Pro X is driven by tokens: a set of color tokens is written at runtime to both the global $u.color and CSS variables. Components only read tokens, so re-skinning never touches component source. One default blue theme is built in, and you can register multiple themes, switch at runtime, and use dark mode.

Theme tokens

A theme is described by ThemeColor, whose fields form the full spectrum of each color group:

Group	Fields
Primary	primary / primaryDark / primaryDisabled / primaryLight
Success	success / successDark / successDisabled / successLight
Warning	warning / warningDark / warningDisabled / warningLight
Error	error / errorDark / errorDisabled / errorLight
Info	info / infoDark / infoDisabled / infoLight
Text	mainColor / contentColor / tipsColor / lightColor
Border & mask	borderColor / dividerColor / maskColor / shadowColor
Background	bgColor / bgWhite / bgGrayLight / bgGrayDark / bgBlack
Solid	whiteColor / blackColor

Only provide the fields you need; missing fields fall back to the built-in palette.

Configuration forms

The theme option of app.use accepts four shapes, normalized internally:

Shape	Type	Description
Omitted / null	-	Use only the built-in blue theme
Single-theme override	ThemeColor	Merge your tokens into the default theme to produce one theme
Multiple themes	Theme[]	Register several themes, merged with the built-in one (same name overrides)
Multiple themes + defaults	Themes	Multiple themes plus defaultTheme / defaultDarkMode / isForce

Single-theme override

To change only the brand color, pass a token object:

app.use(uViewProX, {
    theme: {
        primary: '#7c3aed',
        success: '#10b981',
        warning: '#f59e0b',
        error: '#f43f5e'
    }
})

Multiple themes

Export several themes as an array and pass it at install time:

// theme.uts
export default [
    {
        name: 'purple',
        label: 'Purple',
        color: {
            primary: '#7c3aed',
            primaryDark: '#6d28d9',
            primaryLight: '#f3e8ff',
            success: '#10b981',
            warning: '#f59e0b',
            error: '#f43f5e',
            info: '#6b7280'
        }
    },
    {
        name: 'green',
        label: 'Green',
        color: {
            primary: '#059669',
            success: '#16a34a',
            warning: '#eab308',
            error: '#dc2626',
            info: '#78716c'
        }
    }
]

import themes from './theme.uts'

app.use(uViewProX, {
    // merged with the built-in blue theme into three themes
    theme: themes
})

Multiple themes + defaults

Use the Themes shape to set the default theme and mode:

app.use(uViewProX, {
    theme: {
        themes: themes,
        defaultTheme: 'purple',
        defaultDarkMode: 'auto',
        isForce: false
    }
})

When isForce is true, defaultTheme / defaultDarkMode take top priority and any locally saved choice is ignored.

Dark mode

Dark mode is controlled by darkMode, which is 'auto' (follow system) / 'light' (force light) / 'dark' (force dark).

• Each theme may provide an explicit darkColor; when omitted, the library mixes the light tokens with the built-in dark palette at a 0.6 ratio to derive dark variants, while structural tokens (background, border, text colors, etc.) take the built-in dark values directly.
• On App, switching the mode also calls uni.setAppTheme so the native page background and navigation bar follow along, avoiding white / black flashes.
• In 'auto' mode the system theme is watched (App: onOsThemeChange; other platforms: onHostThemeChange) and the palette is recomputed automatically.

Dark mode has its own page

For mode priority, how the dark palette is derived, platform integration, and page-side usage, see Dark Mode.

Runtime API

Use useTheme to read state and switch themes:

import { useTheme } from '@/uni_modules/uview-pro-x'

const { currentTheme, themes, darkMode, setTheme, setDarkMode, toggleDarkMode, isInDarkMode } = useTheme()

// Switch to a registered theme
setTheme('purple')
// Force dark
setDarkMode('dark')
// Toggle between light and dark
toggleDarkMode()

useTheme returns:

Member	Type	Description
themes	Ref<Theme[]>	All registered themes
currentTheme	Ref<Theme | null>	The current theme
darkMode	Ref<DarkMode>	The current dark-mode setting
cssVars	Ref<UTSJSONObject>	The generated CSS variables
setTheme	(name: string) => void	Switch theme by name and persist
getAvailableThemes	() => Theme[]	Get all themes
getCurrentTheme	() => Theme | null	Get the current theme
setDarkMode	(mode: DarkMode) => void	Set dark mode and persist
getDarkMode	() => DarkMode	Get the current dark-mode setting
isInDarkMode	() => boolean	Whether dark mode is currently active
toggleDarkMode	() => void	Toggle between light and dark
initTheme	(theme?) => void	Initialize the theming system

Theme choice and dark mode are persisted separately (storage keys uview-pro-x-theme, uview-pro-x-dark-mode) and restored on the next launch.

CSS variables

When a theme is applied, a set of CSS variables is generated, usable by both components and your own styles:

• Plain tokens: --u-<kebab>, e.g. --u-main-color, --u-bg-color.
• Type tokens (primary / success / warning / error / info and their derivatives): --u-type-<kebab>, e.g. --u-type-primary, --u-type-primary-light.
• RGB variants: tokens resolvable to hex also produce a -rgb variable, e.g. --u-type-primary-rgb, handy for building rgba().
• Mode marker: --u-theme-mode, valued light / dark.

Notes

1. A token must be a full 6-digit hex (#rrggbb) to produce a -rgb variant; values like rgba() are not split into RGB components.
2. The themes array merges with the built-in theme by name; a matching name overrides the built-in theme. isForce only affects default priority, not the merge.
3. Native background / navbar sync on App relies on uni.setAppTheme; make sure it is called after switching modes (setDarkMode handles this internally).
4. Dark variants are auto-derived by mixing; if you need precise dark colors, provide darkColor explicitly to override per field.
5. A theme's name is used for persistence and switching; renaming it invalidates the saved choice, falling back to the default theme.