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-mantine mixins such as hover and smaller-than are 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:

yarn add @stylexjs/stylex
yarn add --dev @stylexjs/unplugin unplugin lightningcss

Add StyleX plugin to vite.config.mjs:

import stylex from '@stylexjs/unplugin';
import react from '@vitejs/plugin-react';
import { Features } from 'lightningcss';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    stylex.vite({
      lightningcssOptions: { exclude: Features.LightDark },
    }),
    react(),
  ],
});

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:

<link rel="stylesheet" href="/virtual:stylex.css" />
<script type="module" src="/@id/virtual:stylex:runtime"></script>

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:

import stylex from '@stylexjs/unplugin';
import react from '@vitejs/plugin-react';
import { Features } from 'lightningcss';
import { defineConfig } from 'vite';

const stylexPlugin = stylex.vite({
  lightningcssOptions: { exclude: Features.LightDark },
});

if (process.env.VITEST) {
  delete stylexPlugin.configureServer;
}

export default defineConfig({
  plugins: [stylexPlugin, react()],
  test: {
    globals: true,
    environment: 'jsdom',
    setupFiles: './vitest.setup.mjs',
  },
});

Styling components

Spread the result of stylex.props on any Mantine component to style its root element:

import * as stylex from '@stylexjs/stylex';
import { Button } from '@mantine/core';

const styles = stylex.create({
  button: {
    backgroundColor: {
      default: 'var(--mantine-color-pink-filled)',
      ':hover': 'var(--mantine-color-pink-filled-hover)',
    },
  },
});

function Demo() {
  return <Button {...stylex.props(styles.button)}>Button</Button>;
}

Styles API

To apply styles to inner elements, pass class names generated by StyleX to classNames prop:

import * as stylex from '@stylexjs/stylex';
import { TextInput } from '@mantine/core';

const styles = stylex.create({
  label: {
    color: 'var(--mantine-color-teal-filled)',
    fontWeight: 700,
  },

  input: {
    borderColor: 'var(--mantine-color-teal-filled)',
    borderWidth: 2,
  },
});

function Demo() {
  return (
    <TextInput
      label="Label"
      classNames={{
        label: stylex.props(styles.label).className,
        input: stylex.props(styles.input).className,
      }}
    />
  );
}

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:

import * as stylex from '@stylexjs/stylex';
import { Button } from '@mantine/core';

const styles = stylex.create({
  button: {
    '--button-bg': 'var(--mantine-color-pink-filled)',
    '--button-hover': 'var(--mantine-color-pink-filled-hover)',
    '--button-radius': '0px',
  },
});

function Demo() {
  return (
    <>
      <Button {...stylex.props(styles.button)}>Pink button</Button>
      <Button {...stylex.props(styles.button)} disabled>
        Disabled button
      </Button>
    </>
  );
}

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:

// tokens.stylex.ts
import * as stylex from '@stylexjs/stylex';

export const mantine = stylex.defineVars({
  primary: 'var(--mantine-primary-color-filled)',
  body: 'var(--mantine-color-body)',
  text: 'var(--mantine-color-text)',
  radius: 'var(--mantine-radius-md)',
  spacing: 'var(--mantine-spacing-md)',
});
// Demo.tsx
import * as stylex from '@stylexjs/stylex';
import { Card } from '@mantine/core';
import { mantine } from './tokens.stylex';

const styles = stylex.create({
  card: {
    backgroundColor: mantine.primary,
    padding: mantine.spacing,
    borderRadius: mantine.radius,
    color: 'white',
  },
});

function Demo() {
  return <Card {...stylex.props(styles.card)}>Card</Card>;
}

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:

import * as stylex from '@stylexjs/stylex';

const styles = stylex.create({
  box: {
    backgroundColor: 'light-dark(var(--mantine-color-yellow-1), var(--mantine-color-yellow-9))',
  },
});

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:

import * as stylex from '@stylexjs/stylex';

const styles = stylex.create({
  text: {
    fontSize: {
      default: 'var(--mantine-font-size-sm)',
      '@media (min-width: 48em)': 'var(--mantine-font-size-lg)',
    },
  },
});

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:

import * as stylex from '@stylexjs/stylex';
import { Button } from '@mantine/core';

const styles = stylex.create({
  button: (width: number) => ({ width }),
});

function Demo() {
  const { className, style } = stylex.props(styles.button(300));

  return (
    <Button className={className} style={[style, { height: 50 }]}>
      Button
    </Button>
  );
}

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.