NutUI Theme Customization: Component‑Level Styling and Implementation Guide

NutUI, JD’s component library, supports H5 and multiple mini‑program platforms, but customizing thousands of theme variables for personalized skins can be labor‑intensive. To improve developer experience, the library introduces a theme‑customization feature that allows switching skins during development and editing component‑level styles.

The online configurator offers several ready‑made themes; developers can modify them in real time, download a custom_theme.sass file, and apply it to a project in about one minute, significantly reducing development cost.

Theme configuration is divided into global variables (e.g., primary colors, fonts) and component variables (e.g., button border radius). Developers can adjust both levels to meet diverse design requirements.

How to use:

1. Open the online configuration site, modify the preview, and download the configuration file.

2. Integrate the downloaded custom_theme.sass into the project (e.g., assets/styles/custom_theme.sass ) and adjust the build tool configuration.

Vite example:

// https://vitejs.dev/config/
export default defineConfig({
  // ...
  css: {
    preprocessorOptions: {
      scss: {
        // default JD APP 10.0 theme
        // @import "@nutui/nutui/dist/styles/variables.scss";
        // JD Tech theme
        // @import "@nutui/nutui/dist/styles/variables-jdt.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: {
                // default JD APP 10.0 theme
                // @import "@nutui/nutui/dist/styles/variables.scss";
                // JD Tech theme
                // @import "@nutui/nutui/dist/styles/variables-jdt.scss";
                data: `@import "./assets/styles/custom_theme.scss";@import "@nutui/nutui/dist/styles/variables.scss";`
            }
        }
    ]
}

Taro mini‑program example:

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')
    ],
    // default JD APP 10.0 theme
    // @import "@nutui/nutui-taro/dist/styles/variables.scss";
    // JD Tech theme
    // @import "@nutui/nutui-taro/dist/styles/variables-jdt.scss";
    data: `@import "@nutui/nutui-taro/dist/styles/variables.scss";`
  },
  // ...
};

The implementation consists of two parts: an internal design that exposes style variables (stored in variables.scss , variables-jdt.scss , etc.) and an online configurator that lets developers edit these variables visually. The SCSS files use the !default flag so that local overrides are respected.

Example of a global variable definition:

// --------base begin-------
// Primary color
$primary-color: #fa2c19 !default;
$primary-color-end: #fa6419 !default;
// Helper color
$help-color: #f5f5f5 !default;
// Title color
$title-color: #1a1a1a !default;
// ...
// Font sizes
$font-size-0: 10px !default;
$font-size-1: 12px !default;
$font-size-2: 14px !default;
$font-size-3: 16px !default;
$font-size-4: 18px !default;
$font-weight-bold: 400 !default;
// Button variables
$button-border-radius: 25px !default;
$button-border-width: 1px !default;
$button-default-bg-color: $white !default;
$button-default-border-color: rgba(204,204,204,1) !default;
$button-default-color: rgba(102,102,102,1) !default;

Component‑level SCSS files import these variables, e.g., .nut-button { height: $button-default-height; /* ... */ } . When the library is built as an npm package, the variable files are exposed so developers can replace them with custom values, achieving full theme customization.

The visual configurator parses the SCSS files, extracts variables into a data structure, displays them per component, and watches for changes to re‑compile Sass in the browser using the Sass.compile API. The resulting CSS is injected into an iframe for preview.

For downloading, the tool concatenates all modified variables into a Blob and triggers a file download named custom_theme.scss .

In summary, NutUI’s theme customization provides both simple color switching and powerful component‑level styling, allowing developers to extend the library beyond its original design, adapt to varied business scenarios, and improve development efficiency.