Ecosystem · With TailwindCSS
With TailwindCSS
Use TailwindCSS and Semi more elegantly

Notice


This page will provide best practices for some issues encountered when using atomic style libraries such as TailwindCSS (supports both v3 and v4) with Semi.
These problems are often encountered when other component libraries are used with Tailwind, but Semi provides official solutions. It is recommended to follow the instructions in this article to configure the project correctly.
Note
Semi does not rely on any third-party style libraries and can run without installing Tailwind. If you do not use atomic libraries such as Tailwind, please close this page directly.

1. Solve the problem of style override priority

Problem performance

There is no effect or component library style exception when using some atomic classes in components.

Cause Analysis

When using Tailwind, Tailwind modifies the dom style through className, which also affects the Semi component library. At the same time, Tailwind enables Preflight by default to reset the browser's default style.
Projects with Preflight enabled usually do not need an additional reset-css. Adding another global reset does not resolve style priority conflicts. If you disable Preflight, choose a reset strategy appropriate for your project.
At this time, depending on the configuration of your project and the import of the entry, there are two possibilities:
  1. Tailwind is introduced before Semi style, and Semi has higher priority
  2. Semi style was introduced before Tailwind, and Tailwind has a higher priority.
If it is 1, it will appear that when Tailwind adds certain atomic classes, if the component style has defined a certain css attribute, the priority of the atomic class is lower than that of Semi, and the atomic class becomes invalid. For example, under the premise of 1, setting padding on the Button component will cause failure.
If it is 2, because Tailwind has a higher priority, its Preflight overwriting the browser's default style will also override Semi's style. For example, under the premise of 2, the background color of the light Button will be overwritten as transparent, causing the style to behave abnormally.

Solution

No matter which side of Tailwind or the component library has higher priority, problems will occur, so the solution lies in correctly handling the relationship between the priority of Preflight and the atomic classes required by users in the Tailwind style relative to the priority of the component library.
1. Enable Semi plugin (>= 2.59.0)
2. In the configuration file in the project
  • Webpack user: import Semi webpack plugin and enable cssLayer in the webpack.config.js
  • Rspack user: import Semi webpack plugin and enable cssLayer in the rspack.config.js
  • Vite users: install @douyinfe/semi-vite-plugin (>= 2.98.0) and enable cssLayer in your existing React project's Vite configuration. This plugin processes Semi styles; it does not replace Tailwind's own build configuration.
For Tailwind v4 with @tailwindcss/vite:
For Tailwind v3, retain your existing Tailwind PostCSS configuration. Do not install or use @tailwindcss/vite; configure Vite as follows:
For either Vite setup, continue with the next section to configure the layer order and entry CSS for your Tailwind version. If you also need a theme package, add theme and other options to the same semiTheming configuration; see Customize Theme.
For other build tools, refer to the principle below to wrap Semi CSS in a layer.
3. Modify Tailwind entry configuration
Choose your Tailwind version
The configuration methods for Tailwind v3 and v4 are different. Please choose the corresponding configuration method based on the version you are using.
Ensure the CSS layer order in production
The entry import order below preserves the final CSS order in most projects, but the production output and the browser's actual styles are the source of truth. The layer order declaration must take effect before any styles first declare those layers, so normal declarations follow the intended priority: Preflight below Semi, and Semi below utilities. Enabling `cssLayer`, or putting an import on the first source line alone, does not cover every production chunking and CSS extraction setup. Verify the result using the “Check the production output” section below.
Tailwind v4 Configuration:
Include Tailwind's default components layer before utilities in the initial order declaration. Otherwise, Tailwind's later declaration appends components after the known layers, allowing custom component styles in that layer to override utility classes.
  1. Create a CSS file (e.g., semi-layer.css) with the following content:
  1. Import this file at the very top of your project's JS entry file (e.g., main.tsx, App.tsx, or index.js), before all other import statements:
Important
In the source entry, import semi-layer.css before any CSS file containing @import "tailwindcss"; and before any Semi component imports, preferably on the first line. Also ensure that the layer order declaration precedes the relevant layer styles in the production output.

Tailwind v3 Configuration:
The CSS of Tailwind v3 entry is usually a file containing the following three lines
Modify it to (copy directly):
And import the above modified file at the top of the project's JS entry file (i.e. App.tsx or index.js). (Usually a Tailwind project has already processed the import of the above files, just put the import statement before all import statements)
4. Check the production output (applies to Tailwind v3 and v4)
After configuration, run the project's production build and preview its output. A working development server or a successful build alone is not sufficient verification:
  1. Inspect the order of <link rel="stylesheet"> / <style> elements in the generated HTML and the content order of their CSS files. Ensure that the complete layer order declaration precedes the first declaration of the relevant layers. This means cascade order in the document and stylesheets, not the order in which network requests finish.
  2. With manualChunks, shared dependency chunks, or other CSS extraction settings, Semi CSS may appear before the entry CSS. For example, if @layer semi { ... } appears before @layer theme, base, semi, components, utilities;, the latter cannot reorder the already registered semi layer, so Preflight may override Semi instead. Even when the build emits a single CSS file, check the declaration order inside it.
  3. In the production preview, check both default component styles and utility overrides. For example, verify the Button background and padding, and confirm that an explicitly applied padding utility still works.
If entry imports cannot guarantee the production order, declare the layer order in the HTML <head> before all other styles. Keep the existing Tailwind entry CSS and the Semi plugin's cssLayer configuration. For example, a Vite project using Tailwind v4 can add the following to index.html:
For Tailwind v3, replace the declaration inside the <style> element with:
If the project uses a strict Content Security Policy (CSP), authorize the inline style with an appropriate nonce/hash, or use a separate stylesheet guaranteed to load first, and verify the production output order again. Do not disable CSP for this declaration.
Compatible with lower version browsers
CSS Layer requires a browser version higher than Chromium 99 (compatibility table), if you The website requires a lower version browser to access and needs to add CSS Layer Polyfill. Please refer to this Polyfill's PostCSS plugin documentation

Principle

Through the CSS Layer feature, priority setting of styles from different sources is achieved.
The plugin wraps Semi's compiled component and theme styles in @layer semi { ... }. Tailwind's style layers are configured separately in the application.
In addition, we configured the priority order of various Layers:
The meaning of the above CSS is that base (including Preflight) has the lowest priority, followed by Semi. The atomic class styles set by the user (padding-[xxx], etc.) have the highest priority, which can solve the above problems.

2. Solve the problem of using Semi Token in Tailwind atomic class (optional)

Tailwind supports users to configure their own Token to implement themes. At the same time, Semi also provides its own theme solution and corresponding Token. If you want to use Semi Token directly in the project, for example, set the text color of a span to --semi-color-text-0 to automatically switch between light and dark colors to be consistent with the theme, you need to set the css color: var(--semi-color-text-0) separately, which is very inconvenient.
Semi provides Tailwind's theme configuration file, which is used to map Semi's Token to atomic Token. For the above requirements, you can directly set text-semi-color-text-0 for span.
Choose your Tailwind version
The theme configuration methods for Tailwind v3 and v4 are different. Please choose the corresponding configuration method based on the version you are using.
Tailwind v4 Configuration:
In your Tailwind entry CSS file (the file containing @import "tailwindcss";), add the @theme configuration:
After configuration, you can use atomic classes like text-semi-color-text-0, bg-semi-color-primary, rounded-semi-border-radius-small, etc.

Tailwind v3 Configuration:
Just configure the following content in the Tailwind configuration (i.e. tailwind.config.js):