---
name: unocss-configuration
description: Config file setup and all configuration options for UnoCSS
---

# UnoCSS Configuration

UnoCSS is configured via a dedicated config file in your project root.

## Config File

**Recommended:** Use a dedicated `uno.config.ts` file for best IDE support and HMR.

```ts
// uno.config.ts
import {
  defineConfig,
  presetAttributify,
  presetIcons,
  presetTypography,
  presetWebFonts,
  presetWind3,
  transformerDirectives,
  transformerVariantGroup,
} from 'unocss';

export default defineConfig({
  shortcuts: [
    // ...
  ],
  theme: {
    colors: {
      // ...
    },
  },
  presets: [
    presetWind3(),
    presetAttributify(),
    presetIcons(),
    presetTypography(),
    presetWebFonts({
      fonts: {
        // ...
      },
    }),
  ],
  transformers: [transformerDirectives(), transformerVariantGroup()],
});
```

UnoCSS automatically looks for `uno.config.{js,ts,mjs,mts}` or `unocss.config.{js,ts,mjs,mts}` in the project root.

## Key Configuration Options

### rules

Define CSS utility rules. Later entries have higher priority.

```ts
rules: [
  ['m-1', { margin: '0.25rem' }],
  [/^m-(\d+)$/, ([, d]) => ({ margin: `${d / 4}rem` })],
];
```

### shortcuts

Combine multiple rules into a single shorthand.

```ts
shortcuts: {
  'btn': 'py-2 px-4 font-semibold rounded-lg shadow-md',
}
```

### theme

Theme object for design tokens shared between rules.

```ts
theme: {
  colors: {
    brand: '#942192',
  },
  breakpoints: {
    sm: '640px',
    md: '768px',
  },
}
```

### presets

Predefined configurations bundling rules, variants, and themes.

```ts
presets: [presetWind3(), presetIcons()];
```

### transformers

Transform source code to support special syntax.

```ts
transformers: [transformerDirectives(), transformerVariantGroup()];
```

### variants

Preprocess selectors with ability to rewrite CSS output.

### extractors

Handle source files and extract utility class names.

### preflights

Inject raw CSS globally.

### layers

Control the order of CSS layers. Default is `0`.

```ts
layers: {
  'components': -1,
  'default': 1,
  'utilities': 2,
}
```

### safelist

Utilities that are always included in output.

```ts
safelist: ['p-1', 'p-2', 'p-3'];
```

### blocklist

Utilities that are always excluded.

```ts
blocklist: ['p-1', /^p-[2-4]$/];
```

### content

Configure where to extract utilities from.

```ts
content: {
  pipeline: {
    include: [/\.(vue|svelte|tsx|html)($|\?)/],
  },
  filesystem: ['src/**/*.php'],
}
```

### separators

Variant separator characters. Default: `[':', '-']`

### outputToCssLayers

Output UnoCSS layers as CSS Cascade Layers.

```ts
outputToCssLayers: true;
```

## Specifying Config File Location

```ts
// vite.config.ts
import UnoCSS from 'unocss/vite';

export default defineConfig({
  plugins: [
    UnoCSS({
      configFile: '../my-uno.config.ts',
    }),
  ],
});
```

<!--
Source references:
- https://unocss.dev/guide/config-file
- https://unocss.dev/config/
-->
