Dark Mode

Dark mode is controlled uniformly by the theming system's darkMode and shares the same tokens as multiple themes: when the mode changes, the library recomputes the current theme's dark palette and writes it to both the global $u.color and CSS variables, so components re-color themselves without being aware of the mode. The built-in blue theme already ships with a dark palette and works out of the box.

Three modes

Value	Description
'auto'	Follow the system theme; switch to dark automatically when the system goes dark
'light'	Force light, ignoring the system setting
'dark'	Force dark

The default is 'light' (i.e. config.defaultDarkMode).

Configure at install time

Set the default mode in the theme option of app.use:

app.use(uViewProX, {
    theme: {
        themes: themes,          // optional: register multiple themes
        defaultTheme: 'purple',  // optional: default theme
        defaultDarkMode: 'auto', // default dark mode
        isForce: false           // when true, any saved choice is ignored
    }
})

defaultDarkMode is also a global config field, so it can go into the generic config:

app.use(uViewProX, {
    config: {
        defaultDarkMode: 'dark'
    }
})

Priority of the initial mode

A saved local choice > theme.defaultDarkMode / config.defaultDarkMode > the built-in default 'light'. When isForce: true, theme.defaultDarkMode takes top priority and any saved value is ignored.

Switch at runtime

Use useTheme to switch and read state in a page:

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

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

// Follow the system
setDarkMode('auto')
// Force dark
setDarkMode('dark')
// Toggle from the current mode (dark ↔ light)
toggleDarkMode()
// Read whether dark mode is currently active
const dark = isInDarkMode()

Member	Type	Description
darkMode	Ref<DarkMode>	The current mode ('auto' / 'light' / 'dark')
setDarkMode	(mode: DarkMode) => void	Set the mode and persist it
getDarkMode	() => DarkMode	Read the current mode
isInDarkMode	() => boolean	Whether dark mode is active ('auto' resolves via the system)
toggleDarkMode	() => void	Toggle between light and dark

How isInDarkMode() resolves: 'dark' is always true, 'light' is always false, and for 'auto' it reads uni.getDeviceInfo().osTheme on App and uni.getAppBaseInfo().hostTheme elsewhere.

The mode is persisted to local storage (key uview-pro-x-dark-mode) and restored on the next launch.

How the dark palette is derived

Each theme may provide an explicit darkColor; fields that are not provided are derived as follows:

• Structural tokens: take the built-in dark palette value directly and skip mixing. These include bgColor / bgWhite / bgGrayLight / bgGrayDark / bgBlack / borderColor / lightColor / mainColor / contentColor / tipsColor / whiteColor / blackColor / dividerColor / maskColor / shadowColor.
• Type tokens (primary / success / warning / error / info and their Dark / Disabled / Light derivatives): mixed from the light value with the built-in dark fallback at a 0.6 ratio, producing dark variants that keep the brand feel while fitting a dark background.

Built-in dark palette (excerpt):

Token	Dark value
primary	#8ab4ff
success	#4ade80
warning	#fbbf24
error	#ff6b6b
info	#a0a7b8
mainColor	#f5f6f7
bgColor	#111827
borderColor	#3a4251

For precise dark colors, provide darkColor explicitly to override the auto-derived values per field:

{
    name: 'purple',
    label: 'Purple',
    color: { primary: '#7c3aed' },
    darkColor: { primary: '#c4b5fd' } // set separately for dark
}

Platform integration

• App: switching the mode also calls uni.setAppTheme so the native page background and navigation bar follow along, avoiding white / black flashes.
• 'auto' mode: the library registers a system theme listener — uni.onOsThemeChange on App and uni.onHostThemeChange elsewhere — and recomputes the palette when the system theme changes (the listener is registered only once).

Using it in pages

Components read tokens automatically, and your own page styles can adapt to dark mode via CSS variables too:

<template>
    <view class="card">
        <text class="title">{{ title }}</text>
    </view>
</template>

<style scoped>
.card {
    background-color: var(--u-bg-white);
    color: var(--u-main-color);
}
</style>

To branch on the mode, call isInDarkMode() at an appropriate moment (e.g. onShow) and bind a class to the node; an extra mode marker variable --u-theme-mode is generated when a theme applies, valued light / dark.

Notes

1. Dark variants are auto-derived by mixing, not precise design values; if you need exact dark colors, provide darkColor explicitly.
2. In 'auto' mode, isInDarkMode() relies on the system theme APIs (App: uni.getDeviceInfo; others: uni.getAppBaseInfo) and treats light as the fallback when they are unavailable.
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 mode and theme choice are persisted separately (keys uview-pro-x-dark-mode and uview-pro-x-theme) and do not affect each other.
5. When the current mode is 'auto', toggleDarkMode() follows "anything but dark switches to dark", i.e. 'auto' → 'dark'.