Light
Solid
EN
中文

Theme Customization

AnyUI now supports theme customization, this function will provide a convenient way for you to modify the theme color set, achieve a visual effect that is more consistent with your core design and other components.

How to use

Theme customization is only available when you’re using .scss style files, all the .css files are pre-compiled with the preset default theme colors, they will no longer be allowed to be customized.

Override theme vars

Before modify the SCSS vars, you need to modify the imports of the styles.

  1. Create a custom theme style file, for example, you can create a anyui.scss in src/styles like this:
// Here's the override vars
// ....

// Import the basic style file
@use '@any-design/anyui/styles/index.scss' as *;

If you want to import styles on demand, you need to modify the @any-design/anyui/styles/index.scss to @any-design/anyui/styles/theme.scss.

  1. Import the custom file to your project entry, for example, a src/main.ts file:
import { createApp } from 'vue';
// other imports
// ...
import './styles/anyui.scss';

As you finished these steps, the imports should be ready, then you can override all the theme vars in src/styles/anyui.scss.

All the overrides should be defined before the original AnyUI style file import.

And be aware that you can only import and modify the variables in a SCSS file, if you import the AnyUI SCSS file in your project entry (like src/main.ts), your overrides will never work.

Theme variables

We provided bunch of variables for you to modify, including all the basic colors, and the colors generated after computed.

Global vars

Responsive styles

$anyui-enable-responsive-styles: boolean

Set $anyui-enable-responsive-styles to false can disable the generation of all responsive styles.

Layout

We have these variables for you to control the layout:

$main-font: 'Quicksand'; // the main font family which will be used for all text
$anim-duration: 200ms; // general duration for anims
$scroll-width: 8px; // custom scrollbar width

We recommend to modify it by CSS vars, all the global vars have a corresponding CSS var.

Colors

We have multiple SCSS maps about color definition, you can make your own theme through these maps.

Theme colors

For the light theme, the map named colors.

You can find all the default values below, and you can override any value in it with a pre-defined map named colors, if you want to override some color, then you can just define a same key with the value you like to the colors map, the map will be merged with the default one.

$default-colors: (
  primary: rgba(15, 111, 239, 90),
  secondary: rgba(17, 205, 239, 90),
  bg: #fbfbfc,
  bg-readonly: #f2f3f4,
  bg-disabled: #dadadc,
  text: #202426,
  text-secondary: #909293,
  text-disabled: #a0a1a4,
  text-placeholder: #aeaeae,
  text-btn: #fdfdfe,
  text-white: #fafbfd,
  icon-fill: #a6a8a9,
  scrollbar: #c0c2c3,
  success: rgb(96, 211, 50),
  warn: rgb(243, 189, 41),
  danger: rgb(231, 63, 51),
  info: rgb(47, 124, 224),
  border: #cecdd0,

  line: #eff2f3,
  shadow: #001220,
  shadow-w: #fff,
);

Also, because we’re using “merging” operation, you can define some other variables here, our theme system will also generate a corresponding dark color by our computing methods.

For modify dark colors only, you can define another color map named dark-colors, it will be merged to the final dark color map.

Static colors

Same as the theme colors, we have a color set map named static-colors, all the colors in this map WILL NOT change in dark mode, it will be consistent.

Here’s the definition:

$default-static-colors: (
  mask: rgba(0, 0, 0, 0.8),
);

Alpha list

We provide a bunch of extended theme colors with different alpha value. To generate these colors, we designed an alpha list.

If you want to generate a series of color variables of a theme color with different alpha values, you can define a map called alphas, and use the theme color name as key, with a list of alpha values as the paired value.

Here’s the default definition for reference:

$default-alphas: (
  primary: 100 85 80 75 70 60 40 30 20 18 12 10 8 6 4,
  secondary: 90 80 70 60 40 30 20,
  success: 80 60,
  warn: 80 60,
  danger: 80 60,
  error: 80 60,
  info: 80 60,
  shadow: 2 4 5 6 8 10 12 18 20 24 25 30 36 40,
  shadow-w: 10 20 24,
);

If you want to add some alpha value or generate colors for other theme colors, you can override it with a pre-defined map named alphas, it will be merged to the default settings and be proceeded with the computing methods.

Lightness adjustment

SCSS has an ability to adjust the lightness of colors, we provided a lightness adjustment definition map to make things way more convenient.

If you want to adjust the lightness of a theme color, you can define nested maps like this:

$default-lightness-adjustments: (
  primary: (
    l-6: 6%,
    d-4: -4%,
  ),
  bg: (
    bright: 4.5%,
    light: 2.5%,
    semi-light: 1.5%,
    alter: -0.625%,
    semi-dark: -1.5%,
    darker: -3%,
  ),
  border: (
    lighter: 6%,
    light: 4%,
    semi-light: 2%,
    semi-dark: -2.5%,
    dark: -4.75%,
    darker: -6%,
  ),
);

The final map name is lightness-adjustments, you can override the default values or add something your own to it with a pre-defined map with the same name as the final.

Dark Mode

Generally, dark mode should be associated with a CSS class or an attribute on the root element, for different web apps, the method to enable the dark mode might be different.

To make things more flexible, we provide SCSS vars named enable-prefer-query and dark-theme-selector.

$enable-prefer-query: true !default;
$dark-theme-selector: 'html[theme="dark"]' !default;

If the enable-prefer-query is true, the generated styles will be included with the @media (prefers-color-scheme: dark) query, you can disable it by overriding it to false.

For the dark-theme-selector, by default we will enable the dark mode of all AnyUI components when theme attribute on the html element equals dark, you can change it to anything you want, like in the VitePress, you can override it with .dark selector.

主题定制

AnyUI 支持在构建阶段定制主题色。你可以替换主色、背景、文本、边框、阴影等基础色，让组件视觉更贴近自己的产品设计。

使用方式

主题定制只适用于 .scss 样式入口。发布包里的 .css 文件已经按默认主题预编译，不能再参与 SCSS 变量合并。

覆盖主题变量

在覆盖 SCSS 变量前，需要调整样式引入方式。

  1. 创建一个自定义主题样式文件，例如在 src/styles 中创建 anyui.scss：
// 在这里覆盖变量
// ....

// 再引入 AnyUI 基础样式
@use '@any-design/anyui/styles/index.scss' as *;

如果你希望按需引入样式，可以把 @any-design/anyui/styles/index.scss 换成 @any-design/anyui/styles/theme.scss。

  1. 在项目入口里引入这个自定义文件，例如 src/main.ts：
import { createApp } from 'vue';
// other imports
// ...
import './styles/anyui.scss';

完成后，就可以在 src/styles/anyui.scss 中覆盖主题变量。

所有覆盖都必须写在 AnyUI 原始样式 import 之前。如果你直接在项目入口（例如 src/main.ts）里引入 AnyUI 的 SCSS 文件，覆盖变量不会生效。

主题变量

AnyUI 提供了多组可配置变量，包含基础颜色与计算后的扩展颜色。

全局变量

响应式样式

$anyui-enable-responsive-styles: boolean

把 $anyui-enable-responsive-styles 设置为 false 可以关闭所有响应式样式生成。

布局

可以通过这些变量控制全局布局与动效：

$main-font: 'Quicksand'; // 所有文本使用的主字体
$anim-duration: 200ms; // 通用动画时长
$scroll-width: 8px; // 自定义滚动条宽度

我们更推荐通过 CSS 变量覆盖这些值；全局 SCSS 变量都会生成对应的 CSS 变量。

颜色

颜色定义基于多个 SCSS map。你可以通过覆盖这些 map 来生成自己的主题。

主题色

浅色主题的颜色 map 名为 colors。

默认值如下。如果要覆盖某个颜色，只需要定义同名 key，AnyUI 会把你的 map 与默认 map 合并。

$default-colors: (
  primary: rgba(15, 111, 239, 90),
  secondary: rgba(17, 205, 239, 90),
  bg: #fbfbfc,
  bg-readonly: #f2f3f4,
  bg-disabled: #dadadc,
  text: #202426,
  text-secondary: #909293,
  text-disabled: #a0a1a4,
  text-placeholder: #aeaeae,
  text-btn: #fdfdfe,
  text-white: #fafbfd,
  icon-fill: #a6a8a9,
  scrollbar: #c0c2c3,
  success: rgb(96, 211, 50),
  warn: rgb(243, 189, 41),
  danger: rgb(231, 63, 51),
  info: rgb(47, 124, 224),
  border: #cecdd0,

  line: #eff2f3,
  shadow: #001220,
  shadow-w: #fff,
);

由于合并逻辑会保留额外 key，你也可以在这里增加自己的颜色变量，主题系统会用相同的计算方式为它们生成暗色版本。

如果只想修改暗色模式的颜色，可以定义 dark-colors map。它会被合并到最终的暗色颜色表中。

静态颜色

静态颜色 map 名为 static-colors。这些颜色不会随暗色模式变化，会始终保持一致。

默认定义如下：

$default-static-colors: (
  mask: rgba(0, 0, 0, 0.8),
);

Alpha 列表

AnyUI 会为主题色生成一系列不同透明度的扩展变量。透明度列表由 alphas map 控制。

如果你想为某个主题色生成更多透明度变量，可以用主题色名称作为 key，并提供一组 alpha 值：

$default-alphas: (
  primary: 100 85 80 75 70 60 40 30 20 18 12 10 8 6 4,
  secondary: 90 80 70 60 40 30 20,
  success: 80 60,
  warn: 80 60,
  danger: 80 60,
  error: 80 60,
  info: 80 60,
  shadow: 2 4 5 6 8 10 12 18 20 24 25 30 36 40,
  shadow-w: 10 20 24,
);

定义同名 alphas map 后，AnyUI 会把它与默认值合并。

亮度调整

SCSS 可以调整颜色亮度。AnyUI 通过 lightness-adjustments map 让这件事更可控。

如果想调整某个主题色的亮度，可以定义嵌套 map：

$default-lightness-adjustments: (
  primary: (
    l-6: 6%,
    d-4: -4%,
  ),
  bg: (
    bright: 4.5%,
    light: 2.5%,
    semi-light: 1.5%,
    alter: -0.625%,
    semi-dark: -1.5%,
    darker: -3%,
  ),
  border: (
    lighter: 6%,
    light: 4%,
    semi-light: 2%,
    semi-dark: -2.5%,
    dark: -4.75%,
    darker: -6%,
  ),
);

最终 map 名为 lightness-adjustments。你可以覆盖默认项，也可以增加自己的亮度档位。

暗色模式

暗色模式通常绑定在根节点 class 或 attribute 上。为了适配不同项目，AnyUI 提供了两个 SCSS 变量：

$enable-prefer-query: true !default;
$dark-theme-selector: 'html[theme="dark"]' !default;

当 enable-prefer-query 为 true 时，生成的样式会包含 @media (prefers-color-scheme: dark)。如果你只想手动控制暗色模式，可以把它设为 false。

dark-theme-selector 默认使用 html[theme="dark"] 开启暗色主题。你可以把它改成项目需要的选择器，例如 VitePress 常见的 .dark。