Quickly Customize NutUI Themes and Component Styles for Any Project

Development Background

NutUI is a JD‑style component library that supports H5 and multiple mini‑program platforms. Teams often need to customize nearly a thousand theme variables, which creates a heavy workload for developers.

Design Goals

Provide a skinning solution that allows developers to switch theme skins during development and to override component‑level styles.

Efficiency Boost

An online site offers several preset themes. Developers can edit a theme in real time, download the generated SCSS file, and apply it to a project in about one minute, dramatically reducing development cost.

Component Granularity

Theme configuration is split into global variables and component‑specific variables, enabling fine‑tuned adjustments such as button border‑radius or font size.

Extension Capability

Custom theme packages can be contributed and bundled into the official npm package, benefiting a broader audience.

How Developers Use It

Step 1 – Online Configuration

Open the online configuration site, modify the preview, and download custom_theme.scss (or assets/styles/custom_theme.scss).

Step 2 – Local Project Integration

Vite example

export default defineConfig({
  css: {
    preprocessorOptions: {
      scss: {
        additionalData: `@import "./assets/styles/custom_theme.scss";@import "@nutui/nutui/dist/styles/variables.scss";`
      }
    }
  }
});

Webpack example

{
  test: /\.(sa|sc)ss$/,
  use: [
    {
      loader: 'sass-loader',
      options: {
        data: `@import "./assets/styles/custom_theme.scss";@import "@nutui/nutui/dist/styles/variables.scss";`
      }
    }
  ]
}

Taro mini‑program example (config/index.js)

const path = require('path');
const config = {
  deviceRatio: {640: 2.34/2,750: 1,828: 1.81/2,375: 2/1},
  sass: {
    resource: [path.resolve(__dirname,'..','src/assets/styles/custom_theme.scss')],
    data: `@import "@nutui/nutui-taro/dist/styles/variables.scss";`
  }
};

Implementation Principle Analysis

Internal Library Design

Theme variables are defined in the style folder (e.g., variables.scss, variables-jdt.scss) using the !default flag so that projects can override them. Example base variables:

// --------base begin-------
$primary-color: #fa2c19 !default;
$primary-color-end: #fa6419 !default;
$button-border-radius: 25px !default;
$button-border-width: 1px !default;
// ...

Component SCSS files reference these variables, such as height: $button-default-height; in button/index.scss. When the library is built into an npm package, the global variables.scss is exposed for developers to replace.

Visual Configuration Site

Source code: https://github.com/jdf2e/nutui/tree/theme/src/sites/doc/components/ThemeSetting

The site parses variables.scss with regular expressions to produce a data structure of variable names, keys, and raw values. Users edit values; the browser‑based Sass compiler recompiles the SCSS in real time. When editing stops, the updated variables are concatenated into a SCSS string and offered for download via a Blob stream.

Key workflow:

Extract variables from variables.scss and group them by component.

Render editable UI; on change, compile SCSS with Sass.compile.

Generate a downloadable file using a programmatically created Blob and a hidden link element.

Conclusion

The theme customization mechanism enables both global theme swaps and component‑level style overrides, allowing developers to reshape NutUI’s design language without modifying the library source.