# StyleX

# StyleX integration

[StyleX](https://stylexjs.com/) compiles styles written in TypeScript into atomic CSS at build time.
Use it to style Mantine components if you prefer TypeScript over [CSS Modules](https://alpha.mantine.dev/llms/styles-css-modules.md).

## 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](https://stylexjs.com/docs/learn/installation/) 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](https://alpha.mantine.dev/llms/guides-vite.md), then install StyleX and its bundler
plugin with its `unplugin` and `lightningcss` dependencies:

```bash
yarn add @stylexjs/stylex
```

```bash
npm install @stylexjs/stylex
```

```bash
yarn add @stylexjs/unplugin unplugin lightningcss
```

```bash
npm install @stylexjs/unplugin unplugin lightningcss
```

Add StyleX plugin to `vite.config.mjs`:

```js
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](https://alpha.mantine.dev/llms/guides-tanstack-start.md)), add the stylesheet
and the runtime script to the document `<head>` in development mode:

```html
<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](https://alpha.mantine.dev/llms/guides-vitest.md) 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:

```js
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:

```tsx
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](https://alpha.mantine.dev/llms/styles-styles-api.md) prop:

```tsx
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:

```tsx
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](https://alpha.mantine.dev/llms/styles-css-variables.md), do not duplicate
them in StyleX. Reference them directly, or use `stylex.defineVars` to create type-safe
references to the variables you use frequently:

```tsx
// 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)',
});
```

```tsx
// 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](#installation) section:

```tsx
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](https://alpha.mantine.dev/llms/styles-responsive.md) values in em units in StyleX media queries:

```tsx
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](https://alpha.mantine.dev/llms/styles-style.md) prop:

```tsx
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](https://alpha.mantine.dev/llms/styles-mantine-styles.md#css-layers) to learn more.
