Skip to content

Theming ​

14:24

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:

GroupFields
Primaryprimary / primaryDark / primaryDisabled / primaryLight
Successsuccess / successDark / successDisabled / successLight
Warningwarning / warningDark / warningDisabled / warningLight
Errorerror / errorDark / errorDisabled / errorLight
Infoinfo / infoDark / infoDisabled / infoLight
TextmainColor / contentColor / tipsColor / lightColor
Border & maskborderColor / dividerColor / maskColor / shadowColor
BackgroundbgColor / bgWhite / bgGrayLight / bgGrayDark / bgBlack
SolidwhiteColor / 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:

ShapeTypeDescription
Omitted / null-Use only the built-in blue theme
Single-theme overrideThemeColorMerge your tokens into the default theme to produce one theme
Multiple themesTheme[]A non-empty array is the final theme list; built-in themes only act as per-name baselines
Multiple themes + defaultsThemesMultiple themes plus defaultTheme / defaultDarkMode / isForce

Single-theme override ​

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

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

The single-theme shape only overrides light tokens

ThemeColor contains color tokens only — it has no darkColor / css / darkCss / label field (values under those keys are never read):

  • The dark palette is always derived from the light tokens; structural colors (background / border / text) fall back to the built-in dark baseline;
  • No extra CSS variables and no custom display label;
  • config.defaultTheme is reset to uviewpro.

To control dark colors precisely, switch to the array shape, even with a single theme:

ts
import { BASE_THEME_NAME } from '@/uni_modules/uview-pro-x-uts'

app.use(uViewProX, {
    theme: [
        {
            name: BASE_THEME_NAME,
            label: 'Brand orange',
            color: { primary: '#ff5a1f', primaryLight: '#fff1eb' },
            darkColor: { primary: '#ff8a5c', primaryLight: '#4a2418', bgColor: '#141414' },
            css: { '--u-surface': '#ffffff' },
            darkCss: { '--u-surface': '#1a1a1a' }
        }
    ]
})

With a single item the switcher shows one theme as well: it behaves like the single-theme shape but keeps dark colors and CSS variables fully controllable.

Multiple themes ​

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

ts
// 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'
        }
    }
]
ts
import themes from './theme.uts'

app.use(uViewProX, {
    // the array is the final list; the built-in theme is not appended automatically
    theme: themes
})

Multiple themes + defaults ​

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

ts
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). When not configured it defaults to 'light' and does not follow the system.

  • 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.
  • Final dark value order: explicit darkColor → value derived from the light tokens → built-in dark baseline (the baseline only fills keys not declared in color).
  • 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:

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

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:

MemberTypeDescription
themesRef<Theme[]>All registered themes
currentThemeRef<Theme | null>The current theme
darkModeRef<DarkMode>The current dark-mode setting
cssVarsRef<UTSJSONObject>The generated CSS variables
setTheme(name: string) => voidSwitch theme by name and persist
getAvailableThemes() => Theme[]Get all themes
getCurrentTheme() => Theme | nullGet the current theme
setDarkMode(mode: DarkMode) => voidSet dark mode and persist
getDarkMode() => DarkModeGet the current dark-mode setting
isInDarkMode() => booleanWhether dark mode is currently active
toggleDarkMode() => voidToggle between light and dark
initTheme(theme?) => voidInitialize 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. A non-empty themes array is the final list; built-in themes only act as per-name baselines. To keep the built-in blue, declare { name: BASE_THEME_NAME, color: {} } explicitly. isForce only affects default priority, not the list content.
  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.
  6. Theme entries with an empty or missing name are dropped (there is no implicit fallback); to override the built-in theme, declare it explicitly with the BASE_THEME_NAME constant.