Registration Configuration

In TechUI, theme files are independent JavaScript modules. To enable the system to recognize and use these themes, you need to explicitly import them during application startup (usually in main.js or App.vue).

Importing Themes

Default Behavior

If you do not explicitly import any theme files in your project, the TechUI core package will typically load the lightBlue (Light Blue) theme by default as a fallback to ensure the application can render correctly.

Manual Import

In actual development, it is recommended to explicitly declare the themes you need to use in the entry file.

// main.js

// Import light theme (Recommended/Required)
import "@techui/themes/lightBlue";

// Import dark theme (Optional)
import "@techui/themes/darkBlue";

// Import black theme (Optional)
import "@techui/themes/darkBlack";

When the import statement is executed, the theme file automatically calls the registration function internally to add its configuration to TechUI's global theme pool.

Single/Multi-Theme Strategy

TechUI's global service automatically detects the number of currently registered themes and adjusts the UI behavior accordingly:

• Single-theme mode: When only one theme is imported (e.g., only lightBlue is imported), the system locks the theme switching function. The global <TuiThemeToggle> component and the theme switching options in the control panel will be automatically hidden.
• Multi-theme mode: When two or more themes are imported, the system automatically activates the theme switching function. Users can switch freely between registered themes via the control panel or switching components.

Custom Registration

In addition to using official themes, you can also create and register custom themes. This requires using the tTheme.register method from the @techui/utils package.

Registration Function API

import { tTheme } from "@techui/utils";

tTheme.register({
  value: String,    // Theme unique identifier
  scheme: String,   // Color scheme type ('light' | 'dark')
  colors: Array,    // Array of representative theme colors (displayed in the switcher)
  data: Object      // Complete theme data structure
});

Registration Example

Create a file named myCustomTheme.js:

// myCustomTheme.js
import { tTheme } from "@techui/utils";
import { $c } from "@techui/colors";

// Define theme data
const themeData = {
  name: "myCustom",
  common: {
    bg: $c.wh,
    bd: $c.gyl3,
    // ... other configuration items
  },
  // ... complete structure for font, button, primary, etc.
};

// Execute registration
tTheme.register({
  value: "myCustom",      // Key: Name referenced in global configuration
  scheme: "light",        // Key: Tells the system this is a light color scheme theme
  colors: [$c.rel5, $c.bll5], // Preview color blocks displayed in the theme switching panel
  data: themeData
});

Enabling Custom Themes

After registration is complete, you need to specify the use of this theme in the global configuration $globalConfig, or switch to it via the control panel after importing.

// main.js
import "./path/to/myCustomTheme.js"; // Import file to trigger registration

// Modify default configuration (usually in TechUIInit or Provide configuration)
const globalConfig = {
  theme: "myCustom", // Set default theme to custom theme
  // ...
};

Notes

1. Uniqueness: The value field must be globally unique; otherwise, themes registered later will overwrite themes with the same name.
2. Integrity: The data object of a custom theme must follow TechUI's complete Schema structure (containing all necessary fields like common, font, primary, etc.), otherwise it may lead to missing component styles or errors.
3. Build Optimization: Theme files that are not imported will not be built into the final product by the build tool (Vite/Webpack), so importing multiple themes will increase the bundle size slightly (mainly JS data size, no extra CSS files).