StyleX integration
StyleX compiles styles written in TypeScript into atomic CSS at build time. Use it to style Mantine components if you prefer TypeScript over CSS Modules.
StyleX vs CSS Modules
Like CSS Modules, StyleX generates styles at build time and scopes class names to the component. Differences:
- StyleX styles are type-safe and are defined next to the component that uses them
- StyleX styles have higher specificity and always override Mantine styles, regardless of the order in which styles are loaded
postcss-preset-mantinemixins such ashoverandsmaller-thanare not available, so not all demos from the documentation can be copied as is- StyleX requires a compiler plugin for your bundler. This page covers Vite setup, see StyleX documentation for other bundlers and frameworks
StyleX and CSS Modules can be used in the same project.
Installation
Set up Mantine by following the Vite guide, then install StyleX and its bundler
plugin with its unplugin and lightningcss dependencies:
Add StyleX plugin to vite.config.mjs:
lightningcssOptions: { exclude: Features.LightDark } is required to use light-dark() in StyleX styles.
In development, StyleX plugin injects generated styles into index.html. If your framework renders
the HTML document itself (for example, TanStack Start), add the stylesheet
and the runtime script to the document <head> in development mode:
Vitest
StyleX styles must be compiled in tests, stylex.create throws when called at runtime.
If your Vitest configuration uses vite.config.mjs, StyleX plugin is already applied to test files.
StyleX plugin keeps the Vitest process running for several seconds after all tests are completed. To avoid the delay, remove the development server hook of the plugin when running tests:
Styling components
Spread the result of stylex.props on any Mantine component to style its root element:
Styles API
To apply styles to inner elements, pass class names generated by StyleX to classNames prop:
Do not pass StyleX class names with the attributes prop, Mantine class names override them.
Components CSS variables
StyleX styles also override styles that Mantine applies based on component state. For example,
if you set backgroundColor of a button, disabled buttons keep the same background color.
To keep state styles, override component CSS variables instead. They are listed on the Styles API
tab of each component page:
Theme tokens
All theme properties are exposed as CSS variables, do not duplicate
them in StyleX. Reference them directly, or use stylex.defineVars to create type-safe
references to the variables you use frequently:
Variables defined with stylex.defineVars must be exported from files with .stylex.ts extension.
Light and dark color schemes
Use light-dark() CSS function to define different values for light and dark color schemes.
It requires the lightningcssOptions configuration from the installation section:
Mantine CSS variables that depend on the color scheme, for example --mantine-color-body,
are updated automatically.
Responsive styles
Use theme breakpoints values in em units in StyleX media queries:
Dynamic styles
Dynamic styles are applied with the style property returned by stylex.props.
To combine them with your own style prop, pass an array to style prop:
CSS layers
If you enable useCSSLayers option in StyleX plugin, import @mantine/core/styles.layer.css
instead of @mantine/core/styles.css. Otherwise, Mantine styles override all StyleX styles.
See CSS layers to learn more.