Runtime Theme API
Use the runtime theming contract from Nuvex UI to inspect, change, persist, and extend the active theme without rebuilding the base theme flow yourself.
Before you start
- You already understand that light and dark are the built-in baseline themes.
- You want to operate the active theme from app code instead of redefining the whole visual system.
- Nuvex UI is already installed and rendering correctly in your project.
How the initial theme resolves
The library first tries to restore a valid stored theme, then checks system preference, and finally falls back to the configured default or the built-in baseline.
If a stored value does not exist in the real theme registry, the library skips it and continues with the next resolution step.
app/plugins/nuvex-ui.ts
Inspect theme state
Use the runtime state that Nuvex UI already exposes instead of reading DOM attributes or keeping a parallel theme registry in your app.
components/ThemeInspector.vue <script setup>
components/ThemeSelector.vue <script setup>
components/ThemeInspector.vue <script setup>
Change the active theme
Use these operations when the app needs to set a known theme, toggle between options, or return to the library fallback.
setTheme ignores unknown names and preserves the current valid state, but that case should still be treated as an integration mistake in app code.
components/AppThemeToggle.vue <script setup>
components/ThemeSelector.vue <script setup>
components/ThemeResetButton.vue <script setup>
Persist the user choice
Nuvex UI already supports storage by key or a custom adapter, so this step is about connecting the contract rather than reinventing persistence.
If your app needs SSR-aware theme persistence, connect a custom storage adapter here and leave the framework-specific flow to the integration guide.
app/plugins/nuvex-ui.ts
app/plugins/nuvex-ui.ts
Control the DOM output
The runtime API does not only track state. It also writes the active theme to the DOM through a configurable attribute and updates color-scheme when possible.
app/plugins/nuvex-ui.ts
Emit theme tokens as CSS variables
Enable this output when the active runtime theme also needs to publish token values to CSS without adding another bridge layer in your app.
This option publishes theme tokens from the active runtime theme. It does not replace the decision of when a change belongs in tokens versus CSS overrides.
app/plugins/nuvex-ui.ts
assets/styles/app.css
Register themes at runtime
Use runtime registration when the app needs to add or remove named variants during execution without altering the built-in baseline contract.
light and dark are built into the library baseline. They cannot be re-registered or removed through this runtime contract.
components/ThemeRegistryDemo.vue <script setup>
App integration patterns
Close the page with a few real usage patterns that show how the runtime contract fits into application UI without extra infrastructure.
layouts/default.vue <script setup>
components/ThemeSelector.vue <script setup>
components/ThemePreferenceGate.vue <script setup>
Runtime mistakes to avoid
These are not generic programming mistakes. They come from using the theming contract in the wrong layer or with the wrong assumptions.
Solving a token problem with runtime state
If the real change is visual and stable, the next page is probably Design Tokens or CSS Variables, not another runtime branch.
Assuming any string works
setTheme only applies names that are already registered in the library runtime.
Trying to redefine built-ins in runtime
light and dark are part of the baseline contract and are not treated as disposable user-defined themes.
Duplicating the registry in app state
If availableThemes and getThemes() already expose the source of truth, avoid mirroring that list in another store without a real reason.
Recommended next steps
Continue with the page that matches your next decision about baseline behavior, visual customization, or adding a new theme variant.