Custom Themes

Use this page when the product needs another named theme such as ocean, brand-x, or campaign-dark. The goal is to add a new runtime option without breaking the built-in baseline that Nuvex UI already provides.

Back to Light and Dark ThemesOpen Runtime Theme API

What the framework already supports

  • Nuvex UI already includes light and dark. A custom theme adds another named option; it does not replace the built-in baseline.
  • Custom themes are registered through theme.themes at startup or through registerTheme at runtime.
  • If the product only needs to refine the existing light or dark appearance, stay in Design Tokens or CSS Variables instead of creating another theme name.

Define the theme object

A custom theme definition stays small: give it a stable name, an optional label, decide whether it behaves as dark, and provide only the runtime token overrides that make that theme distinct.

theme/ocean.ts

Register custom themes at startup

Startup registration is the normal path when the extra theme is part of the product shell from the beginning. Add it under theme.themes so it appears immediately in the registry and can participate in initial resolution.

Use startup registration for product-level themes you know in advance. Reach for runtime registration only when themes appear conditionally or are loaded later.

app/plugins/nuvex-ui.ts

Operate custom themes at runtime

Once a custom theme is registered, it behaves like any other theme in the runtime API. You can query it, activate it, list it, or remove it again when the product flow requires that.

This page focuses on the custom-theme lifecycle. If the next problem is toggles, persistence, or active-theme state from components, continue in Runtime Theme API.

components/ThemeSelector.vue <script setup>

Respect the built-in theme limits

The plugin registry is for additional themes, not for redefining light or dark. Built-in themes cannot be re-registered or unregistered through the custom theme path.

If you need to change how light or dark look, customize the baseline. If you need another named runtime branch, create a custom theme.

Recommended next steps

Continue with the page that matches the next real task after the custom theme exists in the registry.

Runtime Theme API

Go there if the next task is selecting, persisting, or reacting to the active custom theme from code.

Light and Dark Themes

Go back there if the product still fits the built-in model and this custom theme may be unnecessary.

Design Tokens

Continue there if the real change is still a build-time visual baseline decision.

CSS Variables

Continue there if the new theme needs scoped cascade adjustments after registration.