Switching Control

TechUI's theme switching is purely runtime-based. This means when a theme changes, the page does not need to be refreshed. The system leverages Vue's reactivity mechanism and the inheritance characteristics of CSS variables to instantly update all visual elements of the entire application, including DOM structures and Canvas charts.

Switching Methods

TechUI provides three dimensions of switching control capabilities, ranging from out-of-the-box UI components to low-level API calls.

Using the Toggle Component (TuiThemeToggle)

<TuiThemeToggle> is a dedicated lightweight button component, typically placed in navigation bars, login page corners, or the bottom of sidebars.

Basic Usage:

<template>
  <TuiThemeToggle />
  
  <TuiThemeToggle direction="v" />
</template>

Behavior Logic: When this component is clicked, it cycles through all registered themes.

Using the Control Panel

TechUI features a built-in global configuration panel, <TuiControlPanel>, which includes a more detailed theme selector. Users can visually see preview color blocks for each theme (defined by the colors field during registration) within this panel.

Invocation: The panel is typically shown or hidden by calling the global method controlPanelToggle().

import { inject } from 'vue';

const { controlPanelToggle } = inject('$global');

// Bind to a settings button
const openSettings = () => {
  controlPanelToggle();
};

Programming Control (API)

If you need to force a theme switch based on specific conditions (such as time or user preference configurations) within business logic, you can use the themeToggle function provided by the global service.

Function Signature: themeToggle(themeName: String, themeScheme: String)

Usage Example:

import { inject } from 'vue';

const { themeToggle } = inject('$global');

const switchToDark = () => {
  // Argument 1: The registered name of the theme (value)
  // Argument 2: The color scheme type ('light' or 'dark')
  themeToggle('darkBlue', 'dark');
};

Transition Animations: When switching themes via themeToggle, the system automatically triggers a View Transition. TechUI defaults to circular expansion or fade-in/fade-out effects to make the process smooth and technological rather than a jarring color jump.

Smart Strategies

Single/Multi-Theme Auto-Adaptation

TechUI UI components (including <TuiThemeToggle> and the theme modules in the control panel) possess intelligent awareness:

• Single Theme Mode: If only one theme file is imported in main.js, the system determines that switching is unnecessary. In this case, <TuiThemeToggle> is automatically hidden (rendered as a comment), and theme options in the control panel are also hidden.
• Multi-Theme Mode: Once two or more themes are imported, the relevant UI controls are displayed automatically.

This design allows developers to import multiple themes for debugging during development and simply comment out the import statements for production if only one theme is desired, without modifying any UI code.

Persistence

Theme states have persistence capabilities.

1. Automatic Saving: When a user switches themes, TechUI automatically saves the latest theme name (theme) and scheme (themeScheme) to the browser's local storage (LocalStorage or SessionStorage, depending on global configuration).
2. Automatic Recovery: When a user refreshes the page or visits next time, TuiProvider prioritizes reading the configuration from local storage during initialization and automatically applies the last selected theme to ensure user experience consistency.

FAQ

Q: Why is there no change after calling themeToggle?A: Please check the following two points:

1. Whether the passed themeName matches the value field registered in the theme file exactly (case-sensitive).
2. Whether the target theme file has been imported via import in main.js. Themes that are not imported will not be registered in the system.

Q: How can I turn off the transition animation during switching?A: You can set transition to false in the global configuration or temporarily modify the transition configuration before calling themeToggle. However, in most scenarios, keeping the animation provides a better user experience.