---
url: 'https://unocss.dev/extractors/arbitrary-variants.md'
---

# Arbitrary Variants Extractor

A more complex extractor to support arbitrary variants for utilities.

```html
<div class="[&>*]:m-1 [&[open]]:p-2"></div>
```

Will be captured with `[&>*]:m-1` and `[&[open]]:p-2` as variants.

This extractor is included in [`@unocss/preset-mini`](/presets/mini) as the default extractor. Normally you don't need to install this package manually.

## Installation

::: code-group

```bash [pnpm]
pnpm add -D @unocss/extractor-arbitrary-variants
```

```bash [yarn]
yarn add -D @unocss/extractor-arbitrary-variants
```

```bash [npm]
npm install -D @unocss/extractor-arbitrary-variants
```

```bash [bun]
bun add -D @unocss/extractor-arbitrary-variants
```

:::

```ts [uno.config.ts]
import extractorArbitrary from '@unocss/extractor-arbitrary-variants'
import { defineConfig } from 'unocss'

export default defineConfig({
  extractors: [
    extractorArbitrary(),
  ],
})
```

---

---
url: 'https://unocss.dev/transformers/attributify-jsx.md'
description: Support valueless attributify in JSX/TSX (@unocss/transformer-attributify-jsx)
---

# Attributify JSX transformer

Support [valueless attributify](/presets/attributify#valueless-attributify) in JSX/TSX: `@unocss/transformer-attributify-jsx`.

## Presentation

```jsx
export function Component() {
  return (
    <div text-red text-center text-5xl animate-bounce>
      unocss
    </div>
  )
}
```

Will be transformed to:

```jsx
export function Component() {
  return (
    <div text-red="" text-center="" text-5xl="" animate-bounce="">
      unocss
    </div>
  )
}
```

::: details Without this transformer, JSX treats valueless attributes as boolean attributes.

```jsx
export function Component() {
  return (
    <div text-red={true} text-center={true} text-5xl={true} animate-bounce={true}>
      unocss
    </div>
  )
}
```

:::

## Installation

::: code-group

```bash [pnpm]
pnpm add -D @unocss/transformer-attributify-jsx
```

```bash [yarn]
yarn add -D @unocss/transformer-attributify-jsx
```

```bash [npm]
npm install -D @unocss/transformer-attributify-jsx
```

```bash [bun]
bun add -D @unocss/transformer-attributify-jsx
```

:::

```ts{11} [uno.config.ts]
import { defineConfig, presetAttributify } from 'unocss'
import transformerAttributifyJsx from '@unocss/transformer-attributify-jsx'

export default defineConfig({
  // ...
  presets: [
    // ...
    presetAttributify(),
  ],
  transformers: [
    transformerAttributifyJsx(), // <--
  ],
})
```

::: tip
This preset is included in the `unocss` package, you can also import it from there:

```ts
import { transformerAttributifyJsx } from 'unocss'
```

:::

## Caveats

::: warning
The rules are almost the same as those of [Attributify preset](/presets/attributify), but there are several precautions.
:::

```html
<div translate-x-100% />
<!-- cannot end with `%` -->

<div translate-x-[100px] />
<!-- cannot contain `[` or `]` -->
```

Instead, you may want to use valued attributes instead:

```html
<div translate="x-100%" />

<div translate="x-[100px]" />
```

## Blocklist

This transformer will only transform attributes that are valid UnoCSS utilities.
You can also `blocklist` bypass some attributes from been transformed.

```js
transformerAttributifyJsx({
  blocklist: [/text-[a-zA-Z]*/, 'text-5xl']
})
```

```jsx
<div text-red text-center text-5xl animate-bounce>
  unocss
</div>
```

Will be compiled to:

```html
<div text-red text-center text-5xl animate-bounce="">unocss</div>
```

---

---
url: 'https://unocss.dev/presets/attributify.md'
description: The UnoCSS preset that enables the attributify mode for other presets.
---

# Attributify preset

This enables the [attributify mode](#attributify-mode) for other presets.

[Source Code](https://github.com/unocss/unocss/tree/main/packages-presets/preset-attributify)

## Installation

::: code-group

```bash [pnpm]
pnpm add -D @unocss/preset-attributify
```

```bash [yarn]
yarn add -D @unocss/preset-attributify
```

```bash [npm]
npm install -D @unocss/preset-attributify
```

```bash [bun]
bun add -D @unocss/preset-attributify
```

:::

```ts [uno.config.ts]
import presetAttributify from '@unocss/preset-attributify'

export default defineConfig({
  presets: [
    presetAttributify({ /* preset options */ }),
    // ...
  ],
})
```

::: tip
This preset is included in the `unocss` package, you can also import it from there:

```ts
import { presetAttributify } from 'unocss'
```

:::

## Attributify Mode

Imagine you have this button using Tailwind CSS's utilities. When the list gets longer, it becomes really hard to read and maintain.

```html
<button
  class="bg-blue-400 hover:bg-blue-500 text-sm text-white font-mono font-light py-2 px-4 rounded border-2 border-blue-200 dark:bg-blue-500 dark:hover:bg-blue-600"
>
  Button
</button>
```

With attributify mode, you can separate utilities into attributes:

```html
<button
  bg="blue-400 hover:blue-500 dark:blue-500 dark:hover:blue-600"
  text="sm white"
  font="mono light"
  p="y-2 x-4"
  border="2 rounded blue-200"
>
  Button
</button>
```

For example, `text-sm text-white` could be grouped into `text="sm white"` without duplicating the same prefix.

## Prefix self-referencing

For utilities like `flex`, `grid`, `border`, that have the utilities same as the prefix, a special `~` value is provided.

For example:

```html
<button class="border border-red">Button</button>
```

Can be written as:

```html
<button border="~ red">Button</button>
```

## Valueless attributify

In addition to Windi CSS's attributify mode, this preset also supports valueless attributes.

For example,

```html
<div class="m-2 rounded text-teal-400" />
```

now can be

```html
<div m-2 rounded text-teal-400 />
```

::: info
Note: If you are using JSX, `<div foo>` might be transformed to `<div foo={true}>` which will make the generated CSS from UnoCSS fail to match the attributes. To solve this, you might want to try [`transformer-attributify-jsx`](/transformers/attributify-jsx) along with this preset.
:::

## Properties conflicts

If the name of the attributes mode ever conflicts with the elements' or components' properties, you can add `un-` prefix to be specific to UnoCSS's attributify mode.

For example:

```html
<a text="red">This conflicts with links' `text` prop</a>
<!-- to -->
<a un-text="red">Text color to red</a>
```

Prefix is optional by default, if you want to enforce the usage of prefix, set

```ts
presetAttributify({
  prefix: 'un-',
  prefixedOnly: true, // <--
})
```

You can also disable the scanning for certain attributes by:

```ts
presetAttributify({
  ignoreAttributes: [
    'text'
    // ...
  ]
})
```

## TypeScript support (JSX/TSX)

Create `shims.d.ts` with the following content:

> By default, the type includes common attributes from `@unocss/preset-wind3`. If you need custom attributes, refer to the [type source](https://github.com/unocss/unocss/blob/main/packages-presets/preset-attributify/src/jsx.ts) to implement your own type.

### Vue

Since Volar 0.36, [it's now strict to unknown attributes](https://github.com/johnsoncodehk/volar/issues/1077#issuecomment-1145361472). To opt-out, you can add the following file to your project:

```ts [html.d.ts]
declare module '@vue/runtime-dom' {
  interface HTMLAttributes {
    [key: string]: any
  }
}
declare module '@vue/runtime-core' {
  interface AllowedComponentProps {
    [key: string]: any
  }
}
export {}
```

### React

```ts
import type { AttributifyAttributes } from '@unocss/preset-attributify'

declare module 'react' {
  interface HTMLAttributes<T> extends AttributifyAttributes {}
}
```

### Vue 3

```ts
import type { AttributifyAttributes } from '@unocss/preset-attributify'

declare module '@vue/runtime-dom' {
  interface HTMLAttributes extends AttributifyAttributes {}
}
```

### SolidJS

```ts
import type { AttributifyAttributes } from '@unocss/preset-attributify'

declare module 'solid-js' {
  namespace JSX {
    interface HTMLAttributes<T> extends AttributifyAttributes {}
  }
}
```

### Svelte & SvelteKit

```ts
declare namespace svelteHTML {
  import type { AttributifyAttributes } from '@unocss/preset-attributify'

  type HTMLAttributes = AttributifyAttributes
}
```

### Astro

```ts
import type { AttributifyAttributes } from '@unocss/preset-attributify'

declare global {
  namespace astroHTML.JSX {
    interface HTMLAttributes extends AttributifyAttributes { }
  }
}
```

### Preact

```ts
import type { AttributifyAttributes } from '@unocss/preset-attributify'

declare module 'preact' {
  namespace JSX {
    interface HTMLAttributes extends AttributifyAttributes {}
  }
}
```

### Marko

```ts
import type { AttributifyAttributes } from '@unocss/preset-attributify'

declare global {
  namespace Marko {
    interface HTMLAttributes extends AttributifyAttributes {}
  }
}
```

### Attributify with Prefix

```ts
import type { AttributifyNames } from '@unocss/preset-attributify'

type Prefix = 'uno:' // change it to your prefix

interface HTMLAttributes extends Partial<Record<AttributifyNames<Prefix>, string>> {}
```

## Options

### strict

* **type:** `boolean`
* **default:** `false`

Only generate CSS for attributify or class.

### prefix

* **type:** `string`
* **default:** `'un-'`

The prefix for attributify mode.

### prefixedOnly

* **type:** `boolean`
* **default:** `false`

Only match for prefixed attributes.

### nonValuedAttribute

* **type:** `boolean`
* **default:** `true`

Support matching non-valued attributes.

### ignoreAttributes

* **type:** `string[]`

A list of attributes to be ignored from extracting.

### trueToNonValued

* **type:** `boolean`
* **default:** `false`

Non-valued attributes will also match if the actual value represented in DOM is `true`. This option exists for supporting frameworks that encodes non-valued attributes as `true`. Enabling this option will break rules that ends with `true`.

## Credits

Initial idea by [@Tahul](https://github.com/Tahul) and [@antfu](https://github.com/antfu). Prior [implementation in Windi CSS](https://windicss.org/posts/v30.html#attributify-mode) by [@voorjaar](https://github.com/voorjaar).

---

---
url: 'https://unocss.dev/config/autocomplete.md'
---
# Autocomplete

Autocomplete can be customized for UnoCSS's intelligent suggestions in playground and the [VS Code extension](/integrations/vscode).

```ts
autocomplete: {
  templates: [
    // theme inferring
    'bg-$color/<opacity>',
    // short hands
    'text-<font-size>',
    // logic OR groups
    '(b|border)-(solid|dashed|dotted|double|hidden|none)',
    // constants
    'w-half',
  ],
  shorthands: {
    // equal to `opacity: "(0|10|20|30|40|50|60|70|90|100)"`
    'opacity': Array.from({ length: 11 }, (_, i) => i * 10),
    'font-size': '(xs|sm|base|lg|xl|2xl|3xl|4xl|5xl|6xl|7xl|8xl|9xl)',
    // override built-in short hands
    'num': '(0|1|2|3|4|5|6|7|8|9)',
  },
  extractors: [
      // ...extractors
  ],
}
```

* `templates` uses a simple DSL to specify the autocomplete suggestions.

* `shorthands` is a map of shorthand names to their templates. If it's a `Array`, it will be a logic OR group.

* `extractors` to pickup possible classes and transform class-name style suggestions to the correct format. For example, you could check how we implement the [attributify autocomplete extractor](https://github.com/unocss/unocss/blob/main/packages-presets/preset-attributify/src/autocomplete.ts)

* For additional help, please refer to [here](/tools/autocomplete).

---

---
url: 'https://unocss.dev/tools/autocomplete.md'
description: Autocomplete utilities for UnoCSS (@unocss/autocomplete).
---

# Autocomplete

Autocomplete utilities for UnoCSS: `@unocss/autocomplete`. This is embedded in the playground and the [VS Code extension](/integrations/vscode).

## Usage

### Static rules

Static rules like this will just work without any configuration.

```ts
rules: [
  ['flex', { display: 'flex' }]
]
```

### Dynamic rules

For dynamic rules, you can provide an extra `meta` object to the rule and specify the autocomplete template.

```ts
rules: [
  [
    /^m-(\d)$/,
    ([, d]) => ({ margin: `${d / 4}rem` }),
    { autocomplete: 'm-<num>' }, // <-- this
  ],
]
```

The template uses a simple DSL to specify the autocomplete suggestions. The syntax is:

* `(...|...)`: logic OR groups using `|` as the separator. It will be used as suggestions when some of the groups match.
* `<...>`: built-in shorthands. Currently supports `<num>`, `<percent>` and `<directions>`
* `$...`: theme inferring. For example `$colors` will list all the properties of the `colors` object of the theme.

## Examples

### Example 1

* **Template**: `(border|b)-(solid|dashed|dotted|double|hidden|none)`
* **Input**: `b-do`
* **Suggestions**: `b-dotted`, `b-double`

### Example 2

* **Template**: `m-<num>`
* **Input**: `m-`
* **Suggestions**: `m-1`, `m-2`, `m-3`…

### Example 3

* **Template**: `text-$colors`
* **Input**: `text-r`
* **Suggestions**: `text-red`, `text-rose`…

### Example 4

For multiple templates:

* **Template**: `['(border|b)-<num>', '(border|b)-<directions>-<num>']`
* **Input**: `b-`
* **Suggestions**: `b-x`, `b-y`, `b-1`, `b-2`…
* **Input**: `b-x-`
* **Suggestions**: `b-x-1`, `b-x-2`…

## License

* MIT License © 2021-PRESENT [Anthony Fu](https://github.com/antfu)

---

---
url: 'https://unocss.dev/presets/community.md'
---
# Community

We warmly welcome everyone to join and help build the [UnoCSS community](https://github.com/unocss-community). You can use and share UnoCSS-related resources in [Awesome UnoCSS](https://github.com/unocss-community/awesome-unocss).

---

---
url: 'https://unocss.dev/integrations/jetbrains.md'
---

# JetBrains IDEs Plugin

A community [plugin](https://github.com/re-ovo/unocss-intellij) that provides support for UnoCSS in JetBrains IDEs.

:::info
Note: This is a **community-maintained plugin, not reviewed or maintained by the UnoCSS team**. Please do your own research before using. If you have any issues with this plugin, please report it to [re-ovo/unocss-intellij](https://github.com/re-ovo/unocss-intellij).
:::

## Installation

[JetBrains Marketplace](https://plugins.jetbrains.com/plugin/22204-unocss)

## Features

* Auto-completion for UnoCSS classes
* Hover documentation for UnoCSS classes
* Code folding
* Color/Icon preview

## Bug Reports / Feature Requests

Report it at [Issue Tracker](https://github.com/re-ovo/unocss-intellij/issues)

---

---
url: 'https://unocss.dev/integrations/zed.md'
---

# Zed Extension

A community [extension](https://github.com/bajrangCoder/zed-unocss) that provides support for UnoCSS in Zed.

:::info
Note: This is a **community-maintained extension, not reviewed or maintained by the UnoCSS team**. Please do your own research before using. If you have any issues with this extension, please report it to [bajrangCoder/zed-unocss](https://github.com/bajrangCoder/zed-unocss).
:::

## Installation

From zed extension manager install the unocss extension, https://zed.dev/extensions/unocss

## Bug Reports / Feature Requests

Report it at [Issue Tracker](https://github.com/bajrangCoder/zed-unocss/issues)

---

---
url: 'https://unocss.dev/transformers/compile-class.md'
description: Compile group of classes into one class (@unocss/transformer-compile-class)
---

# Compile class transformer

Compile group of classes into one class. Inspired by the [compilation mode](https://windicss.org/posts/modes.html#compilation-mode) of Windi CSS and [issue #948](https://github.com/unocss/unocss/issues/948) by [@UltraCakeBakery](https://github.com/UltraCakeBakery).

## Installation

::: code-group

```bash [pnpm]
pnpm add -D @unocss/transformer-compile-class
```

```bash [yarn]
yarn add -D @unocss/transformer-compile-class
```

```bash [npm]
npm install -D @unocss/transformer-compile-class
```

```bash [bun]
bun add -D @unocss/transformer-compile-class
```

:::

```ts [uno.config.ts]
import transformerCompileClass from '@unocss/transformer-compile-class'
import { defineConfig } from 'unocss'

export default defineConfig({
  // ...
  transformers: [
    transformerCompileClass(),
  ],
})
```

::: tip
This preset is included in the `unocss` package, you can also import it from there:

```ts
import { transformerCompileClass } from 'unocss'
```

:::

## Usage

Add `:uno:` at the beginning of the class strings to mark them for compilation.

For example:

```html
<div class=":uno: text-center sm:text-left">
  <div class=":uno: text-sm font-bold hover:text-red" />
</div>
```

Will be compiled to:

```html
<div class="uno-qlmcrp">
  <div class="uno-0qw2gr" />
</div>
```

```css
.uno-qlmcrp {
  text-align: center;
}
.uno-0qw2gr {
  font-size: 0.875rem;
  line-height: 1.25rem;
  font-weight: 700;
}
.uno-0qw2gr:hover {
  --un-text-opacity: 1;
  color: rgb(248 113 113 / var(--un-text-opacity));
}
@media (min-width: 640px) {
  .uno-qlmcrp {
    text-align: left;
  }
}
```

## Options

You can config the trigger string and prefix for compile class with the options. Refer to [the types](https://github.com/unocss/unocss/blob/main/packages-presets/transformer-compile-class/src/index.ts#L4) for details.

## Tooling

### ESLint

There is an eslint rule for enforcing the class compile transformer across the whole project: [@unocss/enforce-class-compile](https://unocss.dev/integrations/eslint#unocss-enforce-class-compile)

**Usage:**

```json
{
  "plugins": ["@unocss"],
  "rules": {
    "@unocss/enforce-class-compile": "warn"
  }
}
```

## License

* MIT License © 2021-PRESENT [Anthony Fu](https://github.com/antfu)

---

---
url: 'https://unocss.dev/guide/config-file.md'
---
# Config File

We **highly recommend to use a dedicated `uno.config.ts` file** to configure your UnoCSS, in order to get the best experience with IDEs and other integrations.

A full featured config file looks like this:

```ts twoslash [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(),
  ],
})
```

Compared to the inline configuration inside your `vite.config.ts` or other tools configurations, the dedicated config file will work better with [IDEs](/integrations/vscode) and integrations, with other tools like the [ESLint plugin](/integrations/eslint), in addition making HMR work better.

By default, UnoCSS will automatically look for `uno.config.{js,ts,mjs,mts}` or `unocss.config.{js,ts,mjs,mts}` in the root directory of your project. You can also specify the config file manually, for example in Vite:

```ts [vite.config.ts]
import UnoCSS from 'unocss/vite'
import { defineConfig } from 'vite'

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

For the full list of supported configuration options, please refer to the [Configurations reference](/config/).

---

---
url: 'https://unocss.dev/config.md'
description: Configurations are what make UnoCSS powerful.
---

# Configuring UnoCSS

## Configuration

Configurations are what make UnoCSS powerful.

* [Rules](/config/rules) - Define atomic CSS utilities
* [Shortcuts](/config/shortcuts) - Combine multiple rules into a single shorthand.
* [Theme](/config/theme) - Define theme variables.
* [Variants](/config/variants) - Apply custom conventions to rules.
* [Extractors](/config/extractors) - Define where and how the usage of utilities are extracted.
* [Preflights](/config/preflights) - Define global raw CSS.
* [Layers](/config/layers) - Define the order of each utilities layer.
* [Presets](/config/presets) - Predefined configurations for common use cases.
* [Transformers](/config/transformers) - Code transformers to user sources code to support conventions.
* [Autocomplete](/config/autocomplete) - Define customized autocomplete suggestions.

## Options

### rules

* **Type:** `Rule<Theme>[]`

Rules to generate CSS utilities. Later entries have higher priority.

### shortcuts

* **Type:** `UserShortcuts<Theme>`

Similar to Windi CSS's shortcuts, allows you to create new utilities by combining existing ones. Later entries have higher priority.

### theme

* **Type:** `Theme`

Theme object for shared configuration between rules.

### extendTheme

* **Type:** `Arrayable<ThemeExtender<Theme>>`
  Custom functions mutate the theme object.

It's also possible to return a new theme object to completely replace the original one.

### variants

* **Type:** `Variant<Theme>[]`

Variants that preprocess the selectors, having the ability to rewrite the CSS object.

### extractors

* **Type:** `Extractor[]`

Extractors to handle the source file and output possible classes/selectors. Can be language-aware.

### preflights

* **Type:** `Preflight<Theme>[]`

Raw CSS injections.

### layers

* **Type:** `Record<string, number>`

Layer orders. Default to 0.

### outputToCssLayers

* **Type:** `boolean | UseCssLayersOptions`
* **Default:** `false`

Outputs the layers to CSS Cascade Layers.

#### cssLayerName

* **Type:** `(internalLayer: string) => string | undefined | null`

Specifies the name of the CSS layer the internal layer should be output to (can be a sublayer e.g. "mylayer.mysublayer").

If `undefined` is return, the internal layer name wil be used as the CSS layer name.
If `null` is return, the internal layer will not be output to a CSS layer.

#### allLayers

* **Type:** `boolean`

Force output all css layers, even if they are not used.

For example:

```css
@layer theme, preflights, [unused-layer], default;
```

### sortLayers

* **Type:** `(layers: string[]) => string[]`

Custom function to sort layers.

### presets

* **Type:** `(PresetOrFactory<Theme> | PresetOrFactory<Theme>[])[]`

Predefined configurations for common use cases.

### transformers

* **Type:** `SourceCodeTransformer[]`

Custom transformers to the source code.

### blocklist

* **Type:** `BlocklistRule[]`

Rules to exclude the selectors for your design system (to narrow down the possibilities). Combining `warnExcluded` options can also help you identify wrong usages.

### safelist

* **Type:** `string[]`

Utilities that are always included.

### preprocess

* **Type:** `Arrayable<Preprocessor>`

Preprocess the incoming utilities, return falsy value to exclude.

### postprocess

* **Type:** `Arrayable<Postprocessor>`

Postprocess the generate utils object.

### separators

* **Type:** `Arrayable<string>`
* **Default:** `[':', '-']`

Variant separator.

### extractorDefault

* **Type:** `Extractor | null | false`
* **Default:** `import('@unocss/core').defaultExtractor`

Default extractor that are always applied. By default it split the source code by whitespace and quotes.

It maybe be replaced by preset or user config, only one default extractor can be presented, later one will override the previous one.

Pass `null` or `false` to disable the default extractor.

### autocomplete

Additional options for auto complete.

#### templates

* **Type:** `Arrayable<AutoCompleteFunction | AutoCompleteTemplate>`

Custom functions / templates to provide autocomplete suggestions.

#### extractors

* **Type:** `Arrayable<AutoCompleteExtractor>`

Custom extractors to pickup possible classes and transform class-name style suggestions to the correct format.

#### shorthands

* **Type:** `Record<string, string | string[]>`

Custom shorthands to provide autocomplete suggestions. if values is an array, it will be joined with `|` and wrapped with `()`.

### content

Options for sources to be extracted as utilities usages.

Supported sources:

* `filesystem` - extract from file system
* `inline` - extract from plain inline text
* `pipeline` - extract from build tools' transformation pipeline, such as Vite and Webpack

The usage extracted from each source will be **merged** together.

#### filesystem

* **Type:** `string[]`
* **Default:** `[]`

Glob patterns to extract from the file system, in addition to other content sources. `node_modules` are ignored by default, but unocss will scan from it when you specify the path includes `node_modules`.

In dev mode, the files will be watched and trigger HMR.

#### inline

* **Type:** `string | { code: string; id?: string } | (() => Awaitable<string | { code: string; id?: string }>)) []`

Inline text to be extracted.

#### pipeline

Filters to determine whether to extract certain modules from the build tools' transformation pipeline.

Currently only works for Vite and Webpack integration.

Set `false` to disable.

##### include

* **Type:** `FilterPattern`
* **Default:** `[/\.(vue|svelte|[jt]sx|vine.ts|mdx?|astro|elm|php|phtml|html)($|\?)/]`

Patterns that filter the files being extracted. Supports regular expressions and `picomatch` glob patterns.

By default, `.ts` and `.js` files are NOT extracted.

##### exclude

* **Type:** `FilterPattern`
* **Default:** `[/\.(css|postcss|sass|scss|less|stylus|styl)($|\?)/]`

Patterns that filter the files NOT being extracted. Supports regular expressions and `picomatch` glob patterns.

By default, `node_modules` and `dist` are also extracted.

### configResolved

* **Type:** `(config: ResolvedConfig) => void`

Hook to modify the resolved config.

First presets runs first and the user config.

### configFile

* **Type:** `string | false`

Load from configs files.

Set `false` to disable.

### configDeps

* **Type:** `string[]`

List of files that will also trigger config reloads.

### cli

UnoCSS CLI options.

#### entry

* **Type:** `Arrayable<CliEntryItem>`

UnoCSS cli entry points.

##### patterns

* **Type:** `string[]`

Glob patterns to extract from the file system.

##### outFile

* **Type:** `string`

Output file path.

### shortcutsLayer

* **Type:** `string`
* **Default:** `'shortcuts'`

Layout name of shortcuts.

### envMode

* **Type:** `'dev' | 'build'`
* **Default:** `'build'`

Environment mode.

### details

* **Type:** `boolean`

Expose internal details for debugging / inspecting.

### warn

* **Type:** `boolean`
* **Default:** `true`

Emit warning when matched selectors are presented in blocklist.

---

---
url: 'https://unocss.dev/tools/core.md'
description: >-
  The core engine of UnoCSS without any presets. It can be used as the engine of
  your own atomic CSS framework.
---

# Core

The core engine of UnoCSS without any presets: `@unocss/core`. It can be used as the engine of your own atomic CSS framework.

## Installation

::: code-group

```bash [pnpm]
pnpm add -D @unocss/core
```

```bash [yarn]
yarn add -D @unocss/core
```

```bash [npm]
npm install -D @unocss/core
```

```bash [bun]
bun add -D @unocss/core
```

:::

## Usage

```ts
import { createGenerator } from '@unocss/core'

const generator = await createGenerator(
  { /* user options */ },
  { /* default options */ }
)

const { css } = await generator.generate(code)
```

## License

* MIT License © 2021-PRESENT [Anthony Fu](https://github.com/antfu)

---

---
url: 'https://unocss.dev/transformers/directives.md'
description: >-
  UnoCSS transformer for @apply, @screen and theme() directives
  (@unocss/transformer-directives)
---

# Directives transformer

UnoCSS transformer for `@apply`, `@screen` and `theme()` directives: `@unocss/transformer-directives`.

## Installation

::: code-group

```bash [pnpm]
pnpm add -D @unocss/transformer-directives
```

```bash [yarn]
yarn add -D @unocss/transformer-directives
```

```bash [npm]
npm install -D @unocss/transformer-directives
```

```bash [bun]
bun add -D @unocss/transformer-directives
```

:::

```ts [uno.config.ts]
import transformerDirectives from '@unocss/transformer-directives'
import { defineConfig } from 'unocss'

export default defineConfig({
  // ...
  transformers: [
    transformerDirectives(),
  ],
})
```

::: tip
This preset is included in the `unocss` package, you can also import it from there:

```ts
import { transformerDirectives } from 'unocss'
```

:::

## Usage

### `@apply`

```css
.custom-div {
  @apply text-center my-0 font-medium;
}
```

Will be transformed to:

```css
.custom-div {
  margin-top: 0rem;
  margin-bottom: 0rem;
  text-align: center;
  font-weight: 500;
}
```

#### `--at-apply`

To be compatible with vanilla CSS, you can use CSS custom properties to replace the `@apply` directive:

```css
.custom-div {
  --at-apply: text-center my-0 font-medium;
}
```

This feature is enabled by default with a few aliases, that you can configure or disable via:

```js
transformerDirectives({
  // the defaults
  applyVariable: ['--at-apply', '--uno-apply', '--uno'],
  // or disable with:
  // applyVariable: false
})
```

#### Adding quotes

To use rules with `:`, you will have to quote the whole value:

```css
.custom-div {
  --at-apply: 'hover:text-red hover:font-bold';
  /* or */
  @apply 'hover:text-red hover:font-bold';
}
```

Using quotes after `@apply` is optional, to meet the behavior of some formatters.

### `@screen`

The `@screen` directive that allows you to create media queries that reference your breakpoints by name comes from [`theme.breakpoints`](/config/theme).

```css
.grid {
  --uno: grid grid-cols-2;
}
@screen xs {
  .grid {
    --uno: grid-cols-1;
  }
}
@screen sm {
  .grid {
    --uno: grid-cols-3;
  }
}
/* ... */
...;
```

Will be transformed to:

```css
.grid {
  display: grid;
  grid-template-columns: repeat(2, minmax(0, 1fr));
}
@media (min-width: 320px) {
  .grid {
    grid-template-columns: repeat(1, minmax(0, 1fr));
  }
}
@media (min-width: 640px) {
  .grid {
    grid-template-columns: repeat(3, minmax(0, 1fr));
  }
}
/* ... */
```

#### Breakpoint variant support

`@screen` also supports `lt`、`at` variants:

#### `@screen lt-`

```css
.grid {
  --uno: grid grid-cols-2;
}
@screen lt-xs {
  .grid {
    --uno: grid-cols-1;
  }
}
@screen lt-sm {
  .grid {
    --uno: grid-cols-3;
  }
}
/* ... */
```

Will be transformed to:

```css
.grid {
  display: grid;
  grid-template-columns: repeat(2, minmax(0, 1fr));
}
@media (max-width: 319.9px) {
  .grid {
    grid-template-columns: repeat(1, minmax(0, 1fr));
  }
}
@media (max-width: 639.9px) {
  .grid {
    grid-template-columns: repeat(3, minmax(0, 1fr));
  }
}
/* ... */
```

#### `@screen at-`

```css
.grid {
  --uno: grid grid-cols-2;
}
@screen at-xs {
  .grid {
    --uno: grid-cols-1;
  }
}
@screen at-xl {
  .grid {
    --uno: grid-cols-3;
  }
}
@screen at-xxl {
  .grid {
    --uno: grid-cols-4;
  }
}
/* ... */
```

Will be transformed to:

```css
.grid {
  display: grid;
  grid-template-columns: repeat(2, minmax(0, 1fr));
}
@media (min-width: 320px) and (max-width: 639.9px) {
  .grid {
    grid-template-columns: repeat(1, minmax(0, 1fr));
  }
}
@media (min-width: 1280px) and (max-width: 1535.9px) {
  .grid {
    grid-template-columns: repeat(3, minmax(0, 1fr));
  }
}
@media (min-width: 1536px) {
  .grid {
    grid-template-columns: repeat(4, minmax(0, 1fr));
  }
}
/* ... */
```

### `theme()`

Use the `theme()` function to access your theme config values using dot notation.

```css
.btn-blue {
  background-color: theme('colors.blue.500');
}
```

Will be compiled to:

```css
.btn-blue {
  background-color: #3b82f6;
}
```

### `icon()`

Use the `icon()` function to convert the icon utility to a specific svg icon.

::: warning
`icon()` depends on `@unocss/preset-icons` and will use the configuration, make sure you have added this preset.
:::

```css
.icon {
  background-image: icon('i-carbon-sun');
}
```

Will be compiled to:

```css
.icon {
  background-image: url("data:image/svg+xml;utf8,%3Csvg viewBox='0 0 32 32' width='1em' height='1em' xmlns='http://www.w3.org/2000/svg' %3E%3Cpath fill='currentColor' d='M16 12.005a4 4 0 1 1-4 4a4.005 4.005 0 0 1 4-4m0-2a6 6 0 1 0 6 6a6 6 0 0 0-6-6M5.394 6.813L6.81 5.399l3.505 3.506L8.9 10.319zM2 15.005h5v2H2zm3.394 10.193L8.9 21.692l1.414 1.414l-3.505 3.506zM15 25.005h2v5h-2zm6.687-1.9l1.414-1.414l3.506 3.506l-1.414 1.414zm3.313-8.1h5v2h-5zm-3.313-6.101l3.506-3.506l1.414 1.414l-3.506 3.506zM15 2.005h2v5h-2z'/%3E%3C/svg%3E");
}
```

Cause the icon uses `currentColor` as the fill color by default, if you want to customize the color of the icon, you can use `icon('icon name', 'custom color')`.

```css
.icon {
  background-image: icon('i-carbon-moon', '#fff');
  background-image: icon('i-carbon-moon', 'theme("colors.red.500")'); /* use theme color */
}
```

Will be compiled to:

```css
.icon {
  background-image: url("data:image/svg+xml;utf8,%3Csvg viewBox='0 0 32 32' width='1em' height='1em' xmlns='http://www.w3.org/2000/svg' %3E%3Cpath fill='%23fff' d='M13.503 5.414a15.076 15.076 0 0 0 11.593 18.194a11.1 11.1 0 0 1-7.975 3.39c-.138 0-.278.005-.418 0a11.094 11.094 0 0 1-3.2-21.584M14.98 3a1 1 0 0 0-.175.016a13.096 13.096 0 0 0 1.825 25.981c.164.006.328 0 .49 0a13.07 13.07 0 0 0 10.703-5.555a1.01 1.01 0 0 0-.783-1.565A13.08 13.08 0 0 1 15.89 4.38A1.015 1.015 0 0 0 14.98 3'/%3E%3C/svg%3E");
  background-image: url("data:image/svg+xml;utf8,%3Csvg viewBox='0 0 32 32' width='1em' height='1em' xmlns='http://www.w3.org/2000/svg' %3E%3Cpath fill='%23ef4444' d='M13.503 5.414a15.076 15.076 0 0 0 11.593 18.194a11.1 11.1 0 0 1-7.975 3.39c-.138 0-.278.005-.418 0a11.094 11.094 0 0 1-3.2-21.584M14.98 3a1 1 0 0 0-.175.016a13.096 13.096 0 0 0 1.825 25.981c.164.006.328 0 .49 0a13.07 13.07 0 0 0 10.703-5.555a1.01 1.01 0 0 0-.783-1.565A13.08 13.08 0 0 1 15.89 4.38A1.015 1.015 0 0 0 14.98 3'/%3E%3C/svg%3E");
}
```

## License

* MIT License © 2022-PRESENT [hannoeru](https://github.com/hannoeru)

---

---
url: 'https://unocss.dev/guide/extracting.md'
---

# Extracting

UnoCSS works by searching for utilities usage in your codebase and generating the corresponding CSS on-demand. We call this process **extracting**.

## Content Sources

UnoCSS supports extracting utilities usages from multiple sources:

* [Pipeline](#extracting-from-build-tools-pipeline) - Extract right from your build tools pipeline
* [Filesystem](#extracting-from-filesystem) - Extract from your filesystem by reading and watching files
* [Inline](#extracting-from-inline-text) - Extract from inline plain text

Usages of utilities that come from different sources will be merged together and generate the final CSS.

### Extracting from Build Tools Pipeline

This is supported in the [Vite](/integrations/vite) and [Webpack](/integrations/webpack) integrations.

UnoCSS will read the content that goes through your build tools pipeline and extract the utilities usages from it. This is the most efficient and accurate way to extract, as we only extract the usages that are actually used in your app, smartly, with no additional file I/O made during the extraction.

By default, UnoCSS will extract the utilities usage from files in your build pipeline with extensions `.jsx`, `.tsx`, `.vue`, `.md`, `.html`, `.svelte`, `.astro`, `.marko`, and then generate the appropriate CSS on demand. `.js` and `.ts` files are **NOT included by default**.

To configure them, you can update your `uno.config.ts`:

```ts [uno.config.ts]
export default defineConfig({
  content: {
    pipeline: {
      include: [
        // the default
        /\.(vue|svelte|[jt]sx|vine.ts|mdx?|astro|elm|php|phtml|marko|html)($|\?)/,
        // include js/ts files
        'src/**/*.{js,ts}',
      ],
      // exclude files
      // exclude: []
    },
  },
})
```

You can also add `@unocss-include` magic comment, on a per-file basis, anywhere in the file that you want UnoCSS to scan. If you need to scan `*.js` or `*.ts` files, add them in the configuration to include all js/ts files as scan targets.

```ts
// ./some-utils.js

// since `.js` files are not included by default,
// the following comment tells UnoCSS to force scan this file.
// @unocss-include
export const classes = {
  active: 'bg-primary text-white',
  inactive: 'bg-gray-200 text-gray-500',
}
```

Similarly, you can also add `@unocss-ignore` to bypass the scanning and transforming for the whole file.

If you want the UnoCSS to skip a block of code without being extracted in any extracting files, you can use `@unocss-skip-start` and `@unocss-skip-end` in pairs. Note that it must be used **in pairs** to be effective.

```html
<p class="text-green text-xl">Green Large</p>

<!-- @unocss-skip-start -->
<!-- `text-red` will not be extracted -->
<p class="text-red">Red</p>
<!-- @unocss-skip-end -->
```

### Extracting from Filesystem

In cases that you are using integrations that do not have access to the build tools pipeline (for example, the [PostCSS](/integrations/postcss) plugin), or you are integrating with backend frameworks such that the code does not go through the pipeline, you can manually specify the files to be extracted.

```ts [uno.config.ts]
export default defineConfig({
  content: {
    filesystem: [
      'src/**/*.php',
      'public/*.html',
    ],
  },
})
```

The files matched will be read directly from the filesystem and watched for changes at dev mode.

### Extracting from Inline Text

Additionally, you can also extract utility usages from inline text that you might retrieve from elsewhere.

You may also pass an async function to return the content. But note that the function will only be called once at build time.

```ts [uno.config.ts]
export default defineConfig({
  content: {
    inline: [
      // plain text
      '<div class="p-4 text-red">Some text</div>',
      // async getter
      async () => {
        const response = await fetch('https://example.com')
        return response.text()
      },
    ],
  },
})
```

## Limitations

Since UnoCSS works **at build time**, it means that only statically presented utilities will be generated and shipped to your app. Utilities that are used dynamically or fetched from external resources at runtime might **NOT** be detected or applied.

### Safelist

Sometimes you might want to use dynamic concatenations like:

```html
<div class="p-${size}"></div>
<!-- this won't work! -->
```

Due to the fact that UnoCSS works in build time using static extraction, at compile time it can't possibly know all the combinations of the utilities then. For that, you can configure the `safelist` option.

```ts [uno.config.ts]
safelist: 'p-1 p-2 p-3 p-4'.split(' ')
```

The corresponding CSS will always be generated:

```css
.p-1 { padding: 0.25rem; }
.p-2 { padding: 0.5rem; }
.p-3 { padding: 0.75rem; }
.p-4 { padding: 1rem; }
```

Or more flexible:

```ts [uno.config.ts]
safelist: [
  ...Array.from({ length: 4 }, (_, i) => `p-${i + 1}`),
]
```

If you are seeking a true dynamic generation at runtime, you may want to check out the [@unocss/runtime](/integrations/runtime) package.

### Static List Combinations

Another way to work around the limitation of dynamically constructed utilities is that you can use an object that lists all the combinations **statically**. For example, if you want to have this:

```html
<div class="text-${color} border-${color}"></div>
<!-- this won't work! -->
```

You can create an object that lists all the combinations (assuming you know any possible values of `color` you want to use)

```ts
// Since they are static, UnoCSS will be able to extract them at build time
const classes = {
  red: 'text-red border-red',
  green: 'text-green border-green',
  blue: 'text-blue border-blue',
}
```

And then use it in your template:

```html
<div class="${classes[color]}"></div>
```

### Blocklist

Similar to `safelist`, you can also configure `blocklist` to exclude some utilities from being generated. This is useful for preventing extraction false positives.

But the blocklist is far more powerful than a simple exclusion list. In large-scale projects with many contributors, UnoCSS's flexibility — where the same visual result can be achieved with multiple utility syntaxes — becomes a liability. Different developers might write `border`, `border-1`, or `b` for the same CSS output, resulting in duplicate rules in the generated stylesheet, inconsistent code during reviews, and a growing CSS bundle. The blocklist lets you **enforce a single canonical syntax** across the entire codebase by blocking verbose or non-standard alternatives and pointing developers to the preferred form. Combined with `@unocss/eslint-plugin`, it acts as an automated style guide that restricts utilities to design system tokens, enforces the shortest aliases, and prevents arbitrary values — keeping CSS output minimal and the codebase consistent at scale.

#### Matcher Types

The `blocklist` accepts three matcher types:

**String** — exact match:

```ts [uno.config.ts]
blocklist: [
  'p-1', // blocks p-1 exactly
  'tab', // blocks tab exactly
]
```

**RegExp** — pattern match (uses `.test()`):

```ts [uno.config.ts]
blocklist: [
  /^p-[2-4]$/, // blocks p-2, p-3, p-4
  /^border$/, // blocks "border" but not "border-2"
]
```

**Function** — custom logic, returns truthy to block:

```ts [uno.config.ts]
blocklist: [
  s => s.endsWith('px'), // block all px-suffixed classes
  s => s.split('-').length > 4, // block deeply nested utilities
]
```

#### Messages

Each matcher can optionally be wrapped in a tuple containing a `message` that explains why the utility is blocked. The message can be a static string or a callback that receives the matched selector:

```ts [uno.config.ts]
blocklist: [
  // static message
  [/^border$/, { message: 'use shorter "b"' }],

  // dynamic message — receives the blocked selector
  [/^border(?:-[btrlxy])?$/, {
    // e.g. "border-y" → 'use shorter "b-y"'
    message: v => `use shorter "${v.replace(/^border/, 'b')}"`
  }],
]
```

When used with `@unocss/eslint-plugin`, the message appears in lint output:

```shell
"border" is in blocklist: use shorter "b"
```

Without the ESLint plugin, blocked utilities are silently excluded from CSS generation with no feedback to the developer.
**It is recommended to use `@unocss/eslint-plugin` alongside blocklist rules** to surface actionable messages during development.

#### Variant Awareness

The blocklist checks selectors **both before and after variant stripping**.
A rule blocking `p-1` will also block `hover:p-1`, `md:p-1`, `dark:p-1`, etc.
You don't need to account for variant prefixes in your blocklist patterns.

#### Merging Behavior

Blocklist arrays from all presets and the user config are **merged** — they accumulate and never override each other.
A utility blocked by any preset or the user config will remain blocked.

#### Type Reference

```ts
type BlocklistValue = string | RegExp | ((selector: string) => boolean | null | undefined)
type BlocklistRule = BlocklistValue | [BlocklistValue, BlocklistMeta]

interface BlocklistMeta {
  /**
   * Custom message to show why this selector is blocked.
   */
  message?: string | ((selector: string) => string)
}
```

### Blocklist Patterns

Below are common patterns for using the blocklist effectively.

#### Enforcing Shorter Aliases

When UnoCSS supports multiple syntaxes for the same CSS output, you can block the verbose form and suggest the shorter one:

```ts [uno.config.ts]
blocklist: [
  // "border" → "b", "border-t" → "b-t"
  [/^border(?:-[btrlxy])?$/, {
    message: v => `use shorter "${v.replace(/^border/, 'b')}"`
  }],

  // "opacity-50" → "op-50"
  // "backdrop-opacity-50" → "backdrop-op-50"
  [/^(?:backdrop-)?opacity-(.+)$/, {
    message: v => `use shorter "${v.replace(/opacity-/, 'op-')}"`
  }],

  // "whitespace-nowrap" → "ws-nowrap"
  [/^whitespace-.+$/, {
    message: v => `use shorter "${v.replace(/^whitespace-/, 'ws-')}"`
  }],

  // simple static aliases work well for one-to-one replacements
  [/^flex-grow$/, { message: 'use shorter "grow"' }],
  [/^flex-shrink$/, { message: 'use shorter "shrink"' }],
  [/^inline-block$/, { message: 'use shorter "i-block"' }], // you can point to your custom shortcuts as well
]
```

#### Restricting to Design System Tokens

You can dynamically build blocklist patterns from your design system config to ensure only valid tokens are used.
Use a negative lookahead to permit valid values while blocking everything else:

```ts [uno.config.ts]
import { theme } from './my-design-system'

// Helper to join object keys into a regex alternation
const keys = (obj: Record<string, any>) => Object.keys(obj).join('|')

blocklist: [
  // Only allow font families defined in the design system
  [new RegExp(`^font-(?!(?:${keys(theme.fontFamily)}|\\$)$).+$`), {
    message: `use design system font families: ${Object.keys(theme.fontFamily).join(', ')}`
  }],

  // Only allow shadow values from the design system
  [new RegExp(`^shadow-(?!(?:${keys(theme.boxShadow)}|\\$)).+$`), {
    message: `only design system shadow values are allowed.`
  }],
]
```

::: tip
The `\\$` in the negative lookahead allows CSS variable references (e.g., `font-$myVar`) to pass through, since those are resolved at runtime and can't be statically validated.
:::

#### Converting Raw Units to Scale Values

If your project uses the UnoCSS default spacing scale (where 1 unit = 0.25rem = 4px), you can block raw `px` and `rem` values and suggest the scale equivalent:

```ts [uno.config.ts]
blocklist: [
  // "mt-16px" → "mt-4"
  // "p-[8px]" → "p-2"
  // "w-2rem" → "w-8"
  [/^.+-\[?[\d.]+(?:px|rem)\]?$/, {
    message: (s) => {
      // since message() only receives the matched selector string, not the regex
      // we have to match it again to extract capture groups from the blocklist matcher
      const m = s.match(/\[?(?<v>[\d.]+)(?<u>px|rem)\]?$/)!
      const { v, u } = m.groups!
      const scale = u === 'rem' ? +v * 4 : +v / 4
      return `use spacing scale value: ${s.slice(0, -m[0].length)}${scale}`
    }
  }],
]
```

#### Removing Unnecessary Brackets

UnoCSS arbitrary value brackets `[...]` are often unnecessary when the value is already valid without them:

```ts [uno.config.ts]
blocklist: [
  // "w-[50%]" → "w-50%"
  [/^(w|h|min-[wh]|max-[wh]|top|right|bottom|left)-\[\d+%\]$/, {
    message: (v) => {
      const value = v.match(/\[(\d+%)\]/)?.[1] || ''
      return `use shorter ${v.replace(/-\[\d+%\]/, `-${value}`)}`
    }
  }],

  // "outline-[#ff0000]" → "outline-#ff0000"
  [/^[a-z-]+-\[#[0-9a-fA-F]{3,6}\]$/, {
    message: v => `use shorter ${v.replace(/\[#/, '#').replace(/\]/, '')}`
  }],
]
```

#### Enforcing Conventions

Block patterns that violate project-specific architectural decisions:

```ts [uno.config.ts]
blocklist: [
  // Prevent redundant breakpoint — if "sm" equals 0, it's always active
  // in mobile-first responsive design and should not be specified
  [/^sm:/, {
    message: v => `sm: breakpoint is redundant, use "${v.replace(/^sm:/, '')}"`
  }],

  // Force separate utility classes instead of slash opacity notation.
  // Separate utilities have a higher chance of reuse than slashed combinations,
  // which helps reduce the resulting CSS bundle size
  // "bg-red-500/50" → "bg-red-500 bg-op-50"
  [/^(c|bg)-.+\/\d+$/, {
    message: 'use separate opacity class instead of slash notation (e.g., "bg-red bg-op-50").'
  }],

  // Decompose shorthands into reusable individual properties.
  // Same principle — separate utilities reduce CSS bundle size
  // "size-4" → "w-4 h-4"
  [/^size-(.+)$/, {
    message: (v) => {
      const size = v.match(/^size-(.+)$/)?.[1]
      return `use "w-${size} h-${size}" for independent control`
    }
  }],
]
```

---

---
url: 'https://unocss.dev/config/extractors.md'
---
# Extractors

Extractors are used to extract the usage of utilities from your source code.

```ts [uno.config.ts]
import { defineConfig } from 'unocss'

export default defineConfig({
  extractors: [
    // your extractors
  ],
})
```

By default [extractorSplit](https://github.com/unocss/unocss/blob/main/packages-engine/core/src/extractors/split.ts) will always be applied, which splits the source code into tokens and directly feed to the engine.

To override the default extractors, you can use `extractorDefault` option.

```ts [uno.config.ts]
import { defineConfig } from 'unocss'

export default defineConfig({
  extractors: [
    // your extractors
  ],
  // disable the default extractor
  extractorDefault: false,
  // override the default extractor with your own
  extractorDefault: myExtractor,
})
```

For example, please check the implementation of [pug extractor](https://github.com/unocss/unocss/blob/main/packages-presets/extractor-pug/src/index.ts) or the [attributify extractor](https://github.com/unocss/unocss/blob/main/packages-presets/preset-attributify/src/extractor.ts).

---

---
url: 'https://unocss.dev/guide.md'
description: Getting started with UnoCSS
---

# What is UnoCSS?

UnoCSS is the instant atomic CSS engine, that is designed to be flexible and extensible. The core is un-opinionated and all the CSS utilities are provided via presets.

For example, you could define your custom CSS utilities, by providing rules in your local [config file](/guide/config-file).

```ts [uno.config.ts]
import { defineConfig } from 'unocss'

export default defineConfig({
  rules: [
    ['m-1', { margin: '1px' }],
  ],
})
```

This will add a new CSS utility `m-1` to your project. Since UnoCSS is on-demand, it won't do anything until you use it in your codebase. So say we have a component like this:

```html
<div class="m-1">Hello</div>
```

`m-1` will be detected and the following CSS will be generated:

```css
.m-1 { margin: 1px; }
```

To make it more flexible, you can make your rule dynamic by changing the first argument on the rule (we call it matcher) to a `RegExp`, and the body to a function, for example:

```diff [uno.config.ts]
export default defineConfig({
  rules: [
-    ['m-1', { margin: '1px' }],
+    [/^m-([\.\d]+)$/, ([_, num]) => ({ margin: `${num}px` })],
  ],
})
```

By doing this, now you can have arbitrary margin utilities, like `m-1`, `m-100` or `m-52.43`. And again, UnoCSS only generates them whenever you use them.

```html
<div class="m-1">Hello</div>
<div class="m-7.5">World</div>
```

```css
.m-1 { margin: 1px; }
.m-7.5 { margin: 7.5px; }
```

## Presets

Once you made a few rules, you can extract them into a preset, and share it with others. For example, you can create a preset for your company's design system, and share it with your team.

```ts [my-preset.ts]
import { Preset } from 'unocss'

export const myPreset: Preset = {
  name: 'my-preset',
  rules: [
    [/^m-([.\d]+)$/, ([_, num]) => ({ margin: `${num}px` })],
    [/^p-([.\d]+)$/, ([_, num]) => ({ padding: `${num}px` })],
  ],
  variants: [/* ... */],
  shortcuts: [/* ... */],
  // ...
}
```

```ts [uno.config.ts]
import { defineConfig } from 'unocss'
import { myPreset } from './my-preset'

export default defineConfig({
  presets: [
    myPreset, // your own preset
  ],
})
```

So similarly, we provided a few [official presets](/presets/) for you to start using right away, and you can also find many interesting [community presets](/presets/community).

## Play

You can try UnoCSS in your browser, in the Playground. Or look up utilities from the default presets in the Interactive Docs.

## Integrations

UnoCSS comes with integrations for various frameworks / tools:

## Examples

Source code for all the examples can be found in the [/examples](https://github.com/unocss/unocss/tree/main/examples) directory.

---

---
url: 'https://unocss.dev/presets/icons.md'
description: Use any icon with Pure CSS for UnoCSS (@unocss/preset-icons).
---

# Icons preset

Use any icon with Pure CSS for UnoCSS.

[Source Code](https://github.com/unocss/unocss/tree/main/packages-presets/preset-icons)

::: tip
Recommended reading: [Icons in Pure CSS](https://antfu.me/posts/icons-in-pure-css)
:::

Follow the following conventions to use the icons

* `<prefix><collection>-<icon>`
* `<prefix><collection>:<icon>`

For example:

```html
<!-- A basic anchor icon from Phosphor icons -->
<div class="i-ph-anchor-simple-thin" />
<!-- An orange alarm from Material Design Icons -->
<div class="i-mdi-alarm text-orange-400" />
<!-- A large Vue logo -->
<div class="i-logos-vue text-3xl" />
<!-- Sun in light mode, Moon in dark mode, from Carbon -->
<button class="i-carbon-sun dark:i-carbon-moon" />
<!-- Twemoji of laugh, turns to tear on hovering -->
<div class="i-twemoji-grinning-face-with-smiling-eyes hover:i-twemoji-face-with-tears-of-joy" />
```

Check [all available icons](https://icones.js.org/).

## Install

::: code-group

```bash [pnpm]
pnpm add -D @unocss/preset-icons @iconify-json/[the-collection-you-want]
```

```bash [yarn]
yarn add -D @unocss/preset-icons @iconify-json/[the-collection-you-want]
```

```bash [npm]
npm install -D @unocss/preset-icons @iconify-json/[the-collection-you-want]
```

```bash [bun]
bun add -D @unocss/preset-icons @iconify-json/[the-collection-you-want]
```

:::

We use [Iconify](https://iconify.design) as our data source of icons. You need to install the corresponding icon-set in `devDependencies` by following the `@iconify-json/*` pattern. For example, `@iconify-json/mdi` for [Material Design Icons](https://materialdesignicons.com/), `@iconify-json/tabler` for [Tabler](https://tabler-icons.io/). You can refer to [Icônes](https://icones.js.org/) or [Iconify](https://icon-sets.iconify.design/) for all the collections available.

```ts [uno.config.ts]
import presetIcons from '@unocss/preset-icons'
import { defineConfig } from 'unocss'

export default defineConfig({
  presets: [
    presetIcons({ /* options */ }),
    // ...other presets
  ],
})
```

::: tip
This preset is included in the `unocss` package, you can also import it from there:

```ts
import { presetIcons } from 'unocss'
```

:::

::: info
You can also use this preset alone as a complement to your existing UI frameworks to have pure CSS icons!
:::

If you prefer to install all the icon sets available on Iconify at once (~130MB):

::: code-group

```bash [pnpm]
pnpm add -D @iconify/json
```

```bash [yarn]
yarn add -D @iconify/json
```

```bash [npm]
npm install -D @iconify/json
```

```bash [bun]
bun add -D @iconify/json
```

:::

### Extra Properties

You can provide the extra CSS properties to control the default behavior of the icons. The following is an example of making icons inlined by default:

```ts
presetIcons({
  extraProperties: {
    'display': 'inline-block',
    'vertical-align': 'middle',
    // ...
  },
})
```

## Modes Overriding

By default, this preset will choose the rendering modes automatically for each icon based on the icons' characteristics. You can read more in this [blog post](https://antfu.me/posts/icons-in-pure-css). In some cases, you may want to explicitly set the rendering modes for each icon.

* `?bg` for `background-img` - renders the icon as a background image
* `?mask` for `mask` - renders the icon as a mask image

For example, `vscode-icons:file-type-light-pnpm`, an icon with colors (the `svg` doesn't contain `currentColor`) that will be rendered as a background image. Use `vscode-icons:file-type-light-pnpm?mask` to render it as a mask image and bypass it's colors.

```html
<div class="w-full flex items-center justify-center gap-x-4 text-4xl p-2 mt-4">
  <div class="i-vscode-icons:file-type-light-pnpm" />
  <div class="i-vscode-icons:file-type-light-pnpm?mask text-red-300" />
</div>
```

## Configuring collections and icons resolvers

You can provide collections via `@iconify-json/[the-collection-you-want]`, `@iconify/json` or using your custom ones using `collections` option on your `UnoCSS` configuration.

### Browser

To load `iconify` collections you should use `@iconify-json/[the-collection-you-want]` and not `@iconify/json` since the `json` file is huge.

#### Bundler

When using bundlers, you can provide the collections using `dynamic imports` so they will be bundler as async chunk and loaded on demand.

```ts
import presetIcons from '@unocss/preset-icons/browser'

export default defineConfig({
  presets: [
    presetIcons({
      collections: {
        carbon: () => import('@iconify-json/carbon/icons.json').then(i => i.default),
        mdi: () => import('@iconify-json/mdi/icons.json').then(i => i.default),
        logos: () => import('@iconify-json/logos/icons.json').then(i => i.default),
      }
    })
  ]
})
```

#### CDN

Or if you prefer to fetch them from CDN, you can specify the `cdn` option since `v0.32.10`. We recommend [esm.sh](https://esm.sh/) as the CDN provider.

```ts
presetIcons({
  cdn: 'https://esm.sh/'
})
```

#### Customization

You can also provide your own custom collections using [CustomIconLoader](https://github.com/iconify/iconify/blob/master/packages/utils/src/loader/types.ts#L17) or [InlineCollection](https://github.com/iconify/iconify/blob/master/packages/utils/src/loader/types.ts#L86), for example using `InlineCollection`:

```ts
presetIcons({
  collections: {
    custom: {
      circle: '<svg viewBox="0 0 120 120"><circle cx="60" cy="60" r="50"></circle></svg>',
      /* ... */
    },
    carbon: () => import('@iconify-json/carbon/icons.json').then(i => i.default as any),
    /* ... */
  }
})
```

And then, you can use it on your html: `<span class="i-custom:circle"></span>`

### Node.js

In `Node.js` the preset will search for the installed iconify dataset automatically, so you don't need to register the `iconify` collections.

You can also provide your own custom collections using also [CustomIconLoader](https://github.com/iconify/iconify/blob/master/packages/utils/src/loader/types.ts#L24) or [InlineCollection](https://github.com/iconify/iconify/blob/master/packages/utils/src/loader/types.ts#L100).

#### FileSystemIconLoader

Additionally, you can also use [FileSystemIconLoader](https://github.com/iconify/iconify/blob/master/packages/utils/src/loader/node-loaders.ts#L9) to load your custom icons from your file system. You will need to install `@iconify/utils` package as `dev dependency`.

```ts [unocss.config.ts]
import fs from 'node:fs/promises'
// loader helpers
import { FileSystemIconLoader } from '@iconify/utils/lib/loader/node-loaders'
import { defineConfig, presetIcons } from 'unocss'

export default defineConfig({
  presets: [
    presetIcons({
      collections: {
        // key as the collection name
        'my-icons': {
          account: '<svg><!-- ... --></svg>',
          // load your custom icon lazily
          settings: () => fs.readFile('./path/to/my-icon.svg', 'utf-8'),
          /* ... */
        },
        'my-other-icons': async (iconName) => {
          // your custom loader here. Do whatever you want.
          // for example, fetch from a remote server:
          return await fetch(`https://example.com/icons/${iconName}.svg`).then(res => res.text())
        },
        // a helper to load icons from the file system
        // files under `./assets/icons` with `.svg` extension will be loaded as it's file name
        // you can also provide a transform callback to change each icon (optional)
        'my-yet-other-icons': FileSystemIconLoader(
          './assets/icons',
          svg => svg.replace(/#fff/, 'currentColor')
        )
      }
    })
  ]
})
```

#### ExternalPackageIconLoader

From `@iconify/utils v2.1.20` you can use other packages to load icons from others authors using the new [createExternalPackageIconLoader](https://github.com/iconify/iconify/blob/main/packages/utils/src/loader/external-pkg.ts#L13) helper.

::: warning WARNING
External packages must include `icons.json` file with the `icons` data in `IconifyJSON` format, which can be exported with Iconify Tools. Check [Exporting icon set as JSON package](https://iconify.design/docs/libraries/tools/export/json-package.html) for more details.
:::

For example, you can use `an-awesome-collection` or `@my-awesome-collections/some-collection` to load your custom or third party icons:

```ts [unocss.config.ts]
import { createExternalPackageIconLoader } from '@iconify/utils/lib/loader/external-pkg'
import { defineConfig, presetIcons } from 'unocss'

export default defineConfig({
  presets: [
    presetIcons({
      collections: createExternalPackageIconLoader('an-awesome-collection')
    })
  ]
})
```

You can also combine it with other custom icon loaders, for example:

```ts [unocss.config.ts]
import { createExternalPackageIconLoader } from '@iconify/utils/lib/loader/external-pkg'
import { defineConfig, presetIcons } from 'unocss'
import { FileSystemIconLoader } from 'unplugin-icons/loaders'

export default defineConfig({
  presets: [
    presetIcons({
      collections: {
        ...createExternalPackageIconLoader('other-awesome-collection'),
        ...createExternalPackageIconLoader('@my-awesome-collections/some-collection'),
        ...createExternalPackageIconLoader('@my-awesome-collections/some-other-collection'),
        'my-yet-other-icons': FileSystemIconLoader(
          './assets/icons',
          svg => svg.replace(/^<svg /, '<svg fill="currentColor" ')
        )
      }
    })
  ]
})
```

## Icon Customizations

You can customize all icons using `customizations` configuration option.

Available customizations functions:

* `transform`: transform raw `svg`, will be only applied when using `custom` icon collection (`iconify` collections excluded).
* `customize`: change default icon customizations values.
* `iconCustomizer`: change default icon customizations values.

For each loaded icon, the customizations will be applied in this order:

* apply `transform` to raw `svg`, if provided and using custom icon collection
* apply `customize` with default customizations, if provided
* apply `iconCustomizer` with `customize` customizations, if provided

### Global Custom Icon Transformation

When loading your custom icons, you can transform them, for example adding `fill` attribute with `currentColor`:

```ts
presetIcons({
  customizations: {
    transform(svg) {
      return svg.replace(/#fff/, 'currentColor')
    }
  }
})
```

From version `0.30.8` the `transform` provides the `collection` and `icon` names:

```ts
presetIcons({
  customizations: {
    transform(svg, collection, icon) {
      // do not apply fill to this icons on this collection
      if (collection === 'custom' && icon === 'my-icon')
        return svg
      return svg.replace(/#fff/, 'currentColor')
    }
  }
})
```

### Global Icon Customization

When loading any icon you can customize common properties to all of them, for example configuring the same size:

```ts
presetIcons({
  customizations: {
    customize(props) {
      props.width = '2em'
      props.height = '2em'
      return props
    }
  }
})
```

### Icon/Collection Customization

You can customize each icon using `iconCustomizer` configuration option.

The `iconCustomizer` will take precedence over configuration.

The `iconCustomizer` will be applied to any collection, that is, for each icon from `custom` loader, `inlined` on `custom collections` or from `@iconify`.

For example, you can configure `iconCustomizer` to change all icons for a collection or individual icons on a collection:

```ts
presetIcons({
  customizations: {
    iconCustomizer(collection, icon, props) {
      // customize all icons in this collection
      if (collection === 'my-other-icons') {
        props.width = '4em'
        props.height = '4em'
      }
      // customize this icon in this collection
      if (collection === 'my-icons' && icon === 'account') {
        props.width = '6em'
        props.height = '6em'
      }
      // customize this @iconify icon in this collection
      if (collection === 'mdi' && icon === 'account') {
        props.width = '2em'
        props.height = '2em'
      }
    }
  }
})
```

## Directives

You can use the `icon()` directive in your CSS to get the metadata of the icon.

```css
.icon {
  background-image: icon('i-carbon-sun');
}
```

::: warning
`icon()` depends on `@unocss/preset-icons` and will use the configuration, make sure you have added this preset.
:::

More about `icon()` directive, check [Directives](/transformers/directives#icon).

## Options

### scale

* Type: `number`
* Default: `1`

Scale related to the current font size (1em).

### mode

* Type: `'mask' | 'bg' | 'auto'`
* Default: `'auto'`
* See: https://antfu.me/posts/icons-in-pure-css

Mode of generated CSS icons.

:::tip

* `mask` - use background color and the `mask` property for monochrome icons
* `bg` - use background image for the icons, colors are static
* `auto` - smartly decide mode between `mask` and `bg` per icon based on its style

:::

### prefix

* Type: `string | string[]`
* Default: `'i-'`

Class prefix for matching icon rules.

### extraProperties

* Type: `Record<string, string>`
* Default: `{}`

Extra CSS properties applied to the generated CSS.

### warn

* Type: `boolean`
* Default: `false`

Emit warning when missing icons are matched.

### iconifyCollectionsNames

* Type: `string[]`
* Default: `undefined`

Additional `@iconify-json` collections to use. This option should be used when there are new `@iconify-json` collections not listed in the default icons preset collection names.

### collections

* Type: `Record<string, (() => Awaitable<IconifyJSON>) | undefined | CustomIconLoader | InlineCollection>`
* Default: `undefined`

In Node.js environment, the preset will search for the installed iconify dataset automatically. When using in the browser, this options is provided to provide dataset with custom loading mechanism.

### layer

* Type: `string`
* Default: `'icons'`

Rule layer.

### customizations

* Type: `Omit<IconCustomizations, 'additionalProps' | 'trimCustomSvg'>`
* Default: `undefined`

Custom icon customizations.

### autoInstall

* Type: `boolean`
* Default: `false`

Auto install icon sources package when the usages is detected.

:::warning
Only on `node` environment, on `browser` this option will be ignored.
:::

### unit

* Type: `string`
* Default: `'em'`

Custom icon unit.

### cdn

* Type: `string`
* Default: `undefined`

Load icons from CDN. Should starts with `https://` and ends with `/`.

Recommends:

* `https://esm.sh/`
* `https://cdn.skypack.dev/`

### customFetch

* Type: `(url: string) => Promise<any>`
* Default: `undefined`

Preset used [`ofetch`](https://github.com/unjs/ofetch) as the default fetcher, you can also custom fetch function to provide the icon data.

### processor

* Type: `(cssObject: CSSObject, meta: Required<IconMeta>) => void`
* Default: `undefined`

```ts
interface IconMeta {
  collection: string
  icon: string
  svg: string
  mode?: IconsOptions['mode']
}
```

Processor for the CSS object before stringify. See [example](https://github.com/unocss/unocss/blob/7d83789b0dee8c72c401db24263ea429086de95d/test/preset-icons.test.ts#L66-L82).

## Advanced Custom Icon Set Cleanup

When using this preset with your custom icons, consider using a cleanup process similar to that done by [Iconify](https://iconify.design/) for any icons sets. All the tools you need are available in [Iconify Tools](https://iconify.design/docs/libraries/tools/).

You can check this repo, using this preset on a `Vue 3` project: [@iconify/tools/@iconify-demo/unocss](https://github.com/iconify/tools/tree/main/%40iconify-demo/unocss).

Read [Cleaning up icons](https://iconify.design/docs/articles/cleaning-up-icons/) article from [Iconify](https://iconify.design/) for more details.

## Accessibility Concerns

When using icons, it's important to take all your potential users into account. Some of them might be using screen readers, and they will need an alternative text to understand what an icon means. You can use the `aria-label` attribute to provide a description of the icon:

```html
<a href="/profile" aria-label="Profile" class="i-ph:user-duotone"></a>
```

If the icon is purely decorative and doesn't need a text alternative, you can use `aria-hidden="true"` to hide it from screen readers:

```html
<a href="/profile">
  <span aria-hidden="true" class="i-ph:user-duotone"></span>
  My Profile
</a>
```

There are many other techniques to provide hint text for screen-readers, for instance, [Wind3 preset](./wind3) includes [sr-only](/interactive/?s=sr-only) to hide elements visually but keep them accessible to screen readers.

You can find some good resources on the web about icons accessibility, and CSS icons behave like icon fonts, so you can use the same techniques as you would with icon fonts.

## Credits

* This preset is inspired from [this issue](https://github.com/antfu/unplugin-icons/issues/88) created by [@husayt](https://github.com/husayt).
* Based on the work of [this PR](https://github.com/antfu/unplugin-icons/pull/90) by [@userquin](https://github.com/userquin).

---

---
url: 'https://unocss.dev/tools/inspector.md'
description: The inspector UI for UnoCSS (@unocss/inspector).
---

# Inspector

The inspector UI for UnoCSS: `@unocss/inspector`.
Ships with `unocss` and `@unocss/vite`.

## Usage

Visit localhost:5173/\_\_unocss in your Vite dev server to see the inspector.

The inspector allows you to inspect the generated CSS rules and the applied classes for each file. It also provided a REPL to test your utilities based on your current configuration.

---

---
url: 'https://unocss.dev/integrations.md'
---
# Integrations

## Frameworks / Tools

UnoCSS comes with integrations for various frameworks / tools:

## Examples

Source code for all the examples can be found in the [/examples](https://github.com/unocss/unocss/tree/main/examples) directory.

---

---
url: 'https://unocss.dev/config/layers.md'
description: UnoCSS allows you to define the layers as you want.
---

# Layers

The order of CSS will affect their priorities. While the engine will [retain the order of rules](/config/rules#ordering), sometimes you may want to group some utilities to have explicit control of their order.

## Usage

Unlike Tailwind CSS which offers three fixed layers (`base`, `components`, `utilities`), UnoCSS allows you to define the layers as you want. To set the layer, you can pass the metadata as the third item of your rules:

```ts
rules: [
  [/^m-(\d)$/, ([, d]) => ({ margin: `${d / 4}rem` }), { layer: 'utilities' }],
  // when you omit the layer, it will be `default`
  ['btn', { padding: '4px' }],
]
```

This will generate:

```css
/* layer: default */
.btn { padding: 4px; }
/* layer: utilities */
.m-2 { margin: 0.5rem; }
```

Layer also can be set on each preflight:

```ts
preflights: [
  {
    layer: 'my-layer',
    getCSS: async () => (await fetch('my-style.css')).text(),
  },
]
```

## Ordering

You can control the order of layers by:

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

Layers without specified order will be sorted alphabetically.

When you want to have your custom CSS between layers, you can update your entry module:

```ts
// 'uno:[layer-name].css'
import 'uno:components.css'

// layers that are not 'components' and 'utilities' will fallback to here
import 'uno.css'

// your own CSS
import './my-custom.css'

// "utilities" layer will have the highest priority
import 'uno:utilities.css'
```

## CSS Cascade Layers

You can output CSS Cascade Layers by:

```ts
outputToCssLayers: true
```

You can change the CSS Layer names with:

```ts
outputToCssLayers: {
  cssLayerName: (layer) => {
    // The default layer will be output to the "utilities" CSS layer.
    if (layer === 'default')
      return 'utilities'

    // The shortcuts layer will be output to the "shortcuts" sublayer the of "utilities" CSS layer.
    if (layer === 'shortcuts')
      return 'utilities.shortcuts'

    // All other layers will just use their name as the CSS layer name.
  }
}
```

## Output All CSS Layers

UnoCSS outputs all used CSS layers by default. If you want to force output all defined CSS layers, you can set the `allLayers` option:

```ts
outputToCssLayers: {
  allLayers: true,
}
```

It will output all defined CSS layers, even if they are not used.

```css
@layer theme, preflights, unused-layer, default;

/* generated CSS */
```

## Layers using variants

Layers can be created using variants.

`uno-layer-<name>:` can be used to create a UnoCSS layer.

```html
<p class="uno-layer-my-layer:text-xl">text</p>
```

```css
/* layer: my-layer */
.uno-layer-my-layer\:text-xl{ font-size:1.25rem; line-height:1.75rem; }
```

`layer-<name>:` can be used to create a CSS @layer.

```html
<p class="layer-my-layer:text-xl">text</p>
```

```css
/* layer: default */
@layer my-layer{ .layer-my-layer\:text-xl{ font-size:1.25rem; line-height:1.75rem; } }
```

---

---
url: 'https://unocss.dev/presets/legacy-compat.md'
description: Collections of legacy compatibility utilities.
---

# Legacy Compat Preset

Collections of legacy compatibility utilities.

This preset does not include any rules, it's applying postprocess to the generated CSS from other presets.

By default none of the options are enabled, you need to opt-in each of them explicitly.

[Source Code](https://github.com/unocss/unocss/tree/main/packages-presets/preset-legacy-compat)

## Installation

::: code-group

```bash [pnpm]
pnpm add -D @unocss/preset-legacy-compat
```

```bash [yarn]
yarn add -D @unocss/preset-legacy-compat
```

```bash [npm]
npm install -D @unocss/preset-legacy-compat
```

```bash [bun]
bun add -D @unocss/preset-legacy-compat
```

:::

```ts [uno.config.ts]
import presetLegacyCompat from '@unocss/preset-legacy-compat'
import { defineConfig } from 'unocss'

export default defineConfig({
  presets: [
    // ...other presets
    presetLegacyCompat({
      // options
      commaStyleColorFunction: true,
      legacyColorSpace: true
    }),
  ],
})
```

## Options

### `commaStyleColorFunction`

* **Type:** `boolean`
* **Default:** `false`

Convert color functions (`rgb()` and `hsl()`) from space-separated to comma-separated, for better compatibility with legacy browsers. Bring back the old behavior before UnoCSS v0.57.0 that was changed to space-separated in [#3221](https://github.com/unocss/unocss/pull/3221) to align with Tailwind CSS.

For examples:

* `rgb(255 0 0)` -> `rgb(255, 0, 0)`
* `rgb(255 0 0 / 50%)` -> `rgba(255, 0, 0, 50%)`
* `hsl(0 100% 50% / 50%)` -> `hsla(0, 100%, 50%, 50%)`

### `legacyColorSpace`

* **Type:** `boolean`
* **Default:** `false`

Removes color space keywords such as `in oklch` and `in oklab` from the generated styles. This is useful for ensuring compatibility with legacy browsers that do not support these modern color spaces.

To enable this feature, set the `legacyColorSpace` option to `true`.

---

---
url: 'https://unocss.dev/extractors/mdc.md'
description: MDC extractor for UnoCSS (@unocss/extractor-mdc)
---

# MDC Extractor

Support extracting classes from [MDC (Markdown Components)](https://content.nuxtjs.org/guide/writing/mdc) syntax.

## Installation

::: code-group

```bash [pnpm]
pnpm add -D @unocss/extractor-mdc
```

```bash [yarn]
yarn add -D @unocss/extractor-mdc
```

```bash [npm]
npm install -D @unocss/extractor-mdc
```

```bash [bun]
bun add -D @unocss/extractor-mdc
```

:::

```ts [uno.config.ts]
import extractorMdc from '@unocss/extractor-mdc'
import { defineConfig } from 'unocss'

export default defineConfig({
  extractors: [
    extractorMdc(),
  ],
})
```

It will apply the extraction on `.md` `.mdc` and `.markdown` files, to extract inline props usage of classes. For example

```md
# Title{.text-2xl.font-bold}

Hello [World]{.text-blue-500}

![image](/image.png){.w-32.h-32}
```

The `text-2xl`, `font-bold`, `text-blue-500`, `w-32`, `h-32` classes will be extracted.

---

---
url: 'https://unocss.dev/presets/mini.md'
description: The minimal preset for UnoCSS (@unocss/preset-mini).
---

# Mini preset

The basic preset for UnoCSS, with only the most essential utilities.

[Source Code](https://github.com/unocss/unocss/tree/main/packages-presets/preset-mini)

## Installation

::: code-group

```bash [pnpm]
pnpm add -D @unocss/preset-mini
```

```bash [yarn]
yarn add -D @unocss/preset-mini
```

```bash [npm]
npm install -D @unocss/preset-mini
```

```bash [bun]
bun add -D @unocss/preset-mini
```

:::

```ts [uno.config.ts]
import presetMini from '@unocss/preset-mini'
import { defineConfig } from 'unocss'

export default defineConfig({
  presets: [
    presetMini(),
    // ...other presets
  ],
})
```

::: tip
This preset is included in the `unocss` package, you can also import it from there:

```ts
import { presetMini } from 'unocss'
```

:::

## Rules

This preset is a subset of [`@unocss/preset-wind3`](/presets/wind3), containing only the most essential utilities aligned with CSS's properties, but excludes opinioned or complicated utilities introduced in Tailwind CSS (`container`, `animation`, `gradient` etc.). This can be a good starting point for your own custom preset on top of familiar utilities from Tailwind CSS or Windi CSS.

## Features

### Dark mode

By default, this preset generates class-based dark mode with `dark:` variant.

```html
<div class="dark:bg-red:10" />
```

will generate:

```css
.dark .dark\:bg-red\:10 {
  background-color: rgb(248 113 113 / 0.1);
}
```

#### Media query based dark mode

To instead use media query based dark mode globally you can change the config for the `dark:` variant:

```ts
presetMini({
  dark: 'media'
})
```

Now

```html
<div class="dark:bg-red:10" />
```

will generate:

```css
@media (prefers-color-scheme: dark) {
  .dark\:bg-red\:10 {
    background-color: rgb(248 113 113 / 0.1);
  }
}
```

### CSS @layer

[CSS's native @layer](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer) is supported with variant `layer-xx:`

```html
<div class="layer-foo:p4" />
<div class="layer-bar:m4" />
```

will generate:

```css
@layer foo {
  .layer-foo\:p4 {
    padding: 1rem;
  }
}
@layer bar {
  .layer-bar\:m4 {
    margin: 1rem;
  }
}
```

### Theme

You can fully customize your theme property in your config, and UnoCSS will eventually deeply merge it to the default theme.

:::warning
`breakpoints` property isn't deeply merged, but overridden, see [Breakpoints](/config/theme#breakpoints).
:::

```ts
presetMini({
  theme: {
    // ...
    colors: {
      veryCool: '#0000ff', // class="text-very-cool"
      brand: {
        primary: 'hsl(var(--hue, 217) 78% 51%)', // class="bg-brand-primary"
      }
    },
  }
})
```

## Options

### dark

* **Type:** `class | media | DarkModeSelectors`
* **Default:** `class`

The dark mode options. It can be either `class`, `media`, or a custom selector object(`DarkModeSelectors`).

```ts
interface DarkModeSelectors {
  /**
   * Selector for light variant.
   *
   * @default '.light'
   */
  light?: string

  /**
   * Selector for dark variant.
   *
   * @default '.dark'
   */
  dark?: string
}
```

### attributifyPseudo

* **Type:** `Boolean`
* **Default:** `false`

Generate pseudo selector as `[group=""]` instead of `.group`.

### variablePrefix

* **Type:** `string`
* **Default:** `un-`

Prefix for CSS custom properties.

### prefix

* **Type:** `string | string[]`
* **Default:** `undefined`

Utils prefix.

### preflight

* **Type:** `boolean` | `on-demand`
* **Default:** `true`

Generate preflight css. It can be:

* `true`: always generate preflight.
* `false`: no preflight.
* `on-demand`: only generate preflight for used utilities.

---

---
url: 'https://unocss.dev/integrations/next.md'
description: Getting started with UnoCSS and Next.js.
---

# Next.js

Getting Started with UnoCSS and Next.js. Check the [example](https://github.com/unocss/unocss/tree/main/examples/next).

## Setup

### Installation

::: code-group

```bash [pnpm]
pnpm add -D unocss @unocss/postcss @unocss/reset
```

```bash [yarn]
yarn add -D unocss @unocss/postcss @unocss/reset
```

```bash [npm]
npm install -D unocss @unocss/postcss @unocss/reset
```

```bash [bun]
bun add -D unocss @unocss/postcss @unocss/reset
```

:::

### Configuration

Create `uno.config.ts` or `uno.config.js` at the root of your project.

::: code-group

```ts [uno.config.ts]
import {
  defineConfig,
  presetAttributify,
  presetIcons,
  presetWebFonts,
  presetWind3
} from 'unocss'

export default defineConfig({
  presets: [
    presetWind3(),
    // ...
  ],
})
```

```js [uno.config.js]
import {
  defineConfig,
  presetAttributify,
  presetIcons,
  presetWebFonts,
  presetWind3
} from 'unocss'

export default defineConfig({
  presets: [
    presetWind3(),
    // ...
  ],
})
```

:::

Create `postcss.config.mjs` at the root of your project.

```js [postcss.config.mjs]
export default {
  plugins: {
    '@unocss/postcss': {
      content: ['./app/**/*.{html,js,ts,jsx,tsx}'],
    },
  },
}
```

### Import stylesheets

Add `@unocss all;` in `globals.css`.

```css [globals.css]
@unocss all;

/* ... */
```

Then import `@unocss/reset/tailwind.css` in your layout file.

::: code-group

```tsx [layout.tsx]
import type { Metadata } from 'next'
import { Geist, Geist_Mono } from 'next/font/google'
import '@unocss/reset/tailwind.css'
import './globals.css'

const geistSans = Geist({
  variable: '--font-geist-sans',
  subsets: ['latin'],
})

const geistMono = Geist_Mono({
  variable: '--font-geist-mono',
  subsets: ['latin'],
})

export const metadata: Metadata = {
  title: 'Create Next App',
  description: 'Generated by create next app',
}

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode
}>) {
  return (
    <html lang="en">
      <body
        className={`${geistSans.variable} ${geistMono.variable} antialiased`}
      >
        {children}
      </body>
    </html>
  )
}
```

```js [layout.js]
import { Geist, Geist_Mono } from 'next/font/google'
import '@unocss/reset/tailwind.css'
import './globals.css'

const geistSans = Geist({
  variable: '--font-geist-sans',
  subsets: ['latin'],
})

const geistMono = Geist_Mono({
  variable: '--font-geist-mono',
  subsets: ['latin'],
})

export const metadata = {
  title: 'Create Next App',
  description: 'Generated by create next app',
}

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body className={`${geistSans.variable} ${geistMono.variable}`}>
        {children}
      </body>
    </html>
  )
}
```

:::

## Usage

Style your components with unocss!

::: code-group

```tsx [page.tsx]
export default function Home() {
  return (
    <main className="py-20 px-12 text-center flex flex-col items-center gap-20px">
      <span className="text-blue text-5xl text-hover:red cursor-default">Nextjs</span>
      <div className="i-carbon-car inline-block text-4xl" />
      <button className="btn w-10rem">Button</button>
    </main>
  )
}
```

```js [page.js]
export default function Home() {
  return (
    <main className="py-20 px-12 text-center flex flex-col items-center gap-20px">
      <span className="text-blue text-5xl text-hover:red cursor-default">Nextjs</span>
      <div className="i-carbon-car inline-block text-4xl" />
      <button className="btn w-10rem">Button</button>
    </main>
  )
}
```

:::

## License

* MIT License © 2021-PRESENT [Anthony Fu](https://github.com/antfu)

---

---
url: 'https://unocss.dev/presets.md'
---
# Official Packages

## Presets

| Package                                            | Description                                  |
| -------------------------------------------------- | -------------------------------------------- |
| [@unocss/preset-mini](/presets/mini)               | The minimal but essential rules and variants |
| [@unocss/preset-wind3](/presets/wind3)             | Tailwind CSS / Windi CSS compact preset      |
| [@unocss/preset-wind4](/presets/wind4)             | Tailwind4 CSS compact preset                 |
| [@unocss/preset-attributify](/presets/attributify) | Enables Attributify Mode for other rules     |
| [@unocss/preset-tagify](/presets/tagify)           | Enables Tagify Mode for other rules          |
| [@unocss/preset-icons](/presets/icons)             | Pure CSS Icons solution powered by Iconify   |
| [@unocss/preset-web-fonts](/presets/web-fonts)     | Web fonts (Google Fonts, etc.) support       |
| [@unocss/preset-typography](/presets/typography)   | The typography preset                        |
| [@unocss/preset-rem-to-px](/presets/rem-to-px)     | Converts rem to px for utils                 |

### Deprecated

| Package                   | Description                                 | Reason                                                            |
| ------------------------- | ------------------------------------------- | ----------------------------------------------------------------- |
| ~~`@unocss/preset-wind`~~ | ~~Tailwind CSS / Windi CSS compact preset~~ | This package is deprecated and renamed to `@unocss/preset-wind3`. |
| ~~`@unocss/preset-uno`~~  | ~~The default preset~~                      | This package is deprecated and renamed to `@unocss/preset-wind3`. |

## Transformers

| Package                                                              | Description                                       |
| -------------------------------------------------------------------- | ------------------------------------------------- |
| [@unocss/transformer-variant-group](/transformers/variant-group)     | Transformer for Windi CSS's variant group feature |
| [@unocss/transformer-directives](/transformers/directives)           | Transformer for CSS directives like `@apply`      |
| [@unocss/transformer-compile-class](/transformers/compile-class)     | Compile group of classes into one class           |
| [@unocss/transformer-attributify-jsx](/transformers/attributify-jsx) | Support valueless attributify in JSX/TSX          |

## Extractors

| Package                                                                | Description                                           |
| ---------------------------------------------------------------------- | ----------------------------------------------------- |
| [@unocss/extractor-pug](/extractors/pug)                               | Extractor for Pug                                     |
| [@unocss/extractor-svelte](/extractors/svelte)                         | Extractor for Svelte                                  |
| [@unocss/extractor-arbitrary-variants](/extractors/arbitrary-variants) | Extractor to support arbitrary variants for utilities |

## Community

We warmly welcome everyone to join and help build the [UnoCSS community](https://github.com/unocss-community). You can use and share UnoCSS-related resources in [Awesome UnoCSS](https://github.com/unocss-community/awesome-unocss).

---

---
url: 'https://unocss.dev/guide/packages.md'
description: 'UnoCSS Packages: available packages and what''s included and enabled in unocss.'
---

# Packages

UnoCSS is a monorepo that contains multiple packages. This page lists all the packages and what's included in `unocss` package:

| Package                                                              | Description                                       | Included in `unocss` | Enabled |
| -------------------------------------------------------------------- | ------------------------------------------------- | -------------------- | ------- |
| [@unocss/core](/tools/core)                                          | The core library without preset                   | ✅                   | -       |
| [@unocss/cli](/integrations/cli)                                     | Command line interface for UnoCSS                 | ✅                   | -       |
| [@unocss/preset-mini](/presets/mini)                                 | The minimal but essential rules and variants      | ✅                   | ✅      |
| [@unocss/preset-wind3](/presets/wind3)                               | Tailwind CSS / Windi CSS compact preset           | ✅                   | ✅      |
| [@unocss/preset-wind4](/presets/wind4)                               | Tailwind4 CSS compact preset                      | ✅                   | ✅      |
| [@unocss/preset-attributify](/presets/attributify)                   | Enables Attributify Mode for other rules          | ✅                   | No      |
| [@unocss/preset-tagify](/presets/tagify)                             | Enables Tagify Mode for other rules               | ✅                   | No      |
| [@unocss/preset-icons](/presets/icons)                               | Pure CSS Icons solution powered by Iconify        | ✅                   | No      |
| [@unocss/preset-web-fonts](/presets/web-fonts)                       | Web fonts (Google Fonts, etc.) support            | ✅                   | No      |
| [@unocss/preset-typography](/presets/typography)                     | The typography preset                             | ✅                   | No      |
| [@unocss/preset-rem-to-px](/presets/rem-to-px)                       | Coverts rem to px for utils                       | No                   | No      |
| [@unocss/preset-legacy-compat](/presets/legacy-compat)               | Collections of legacy compatibility utilities     | No                   | No      |
| [@unocss/transformer-variant-group](/transformers/variant-group)     | Transformer for Windi CSS's variant group feature | ✅                   | No      |
| [@unocss/transformer-directives](/transformers/directives)           | Transformer for CSS directives like `@apply`      | ✅                   | No      |
| [@unocss/transformer-compile-class](/transformers/compile-class)     | Compile group of classes into one class           | ✅                   | No      |
| [@unocss/transformer-attributify-jsx](/transformers/attributify-jsx) | Support valueless attributify in JSX/TSX          | ✅                   | No      |
| [@unocss/extractor-pug](/extractors/pug)                             | Extractor for Pug                                 | No                   | -       |
| [@unocss/extractor-svelte](/extractors/svelte)                       | Extractor for Svelte                              | No                   | -       |
| [@unocss/autocomplete](/tools/autocomplete)                          | Utils for autocomplete                            | No                   | -       |
| [@unocss/config](/guide/config-file)                                 | Configuration file loader                         | ✅                   | -       |
| [@unocss/reset](/guide/style-reset)                                  | Collection of common CSS resets                   | ✅                   | No      |
| [@unocss/vite](/integrations/vite)                                   | The Vite plugins                                  | ✅                   | -       |
| [@unocss/inspector](/tools/inspector)                                | The inspector UI for UnoCSS                       | ✅                   | -       |
| [@unocss/astro](/integrations/astro)                                 | The Astro integration                             | ✅                   | -       |
| [@unocss/webpack](/integrations/webpack)                             | The Webpack plugin                                | No                   | -       |
| [@unocss/nuxt](/integrations/nuxt)                                   | The Nuxt Module                                   | No                   | -       |
| [@unocss/svelte-scoped](/integrations/svelte-scoped)                 | Svelte Scoped Vite plugin + Preprocessor          | No                   | -       |
| [@unocss/next](/integrations/next)                                   | The Next.js plugin                                | No                   | -       |
| [@unocss/runtime](/integrations/runtime)                             | CSS-in-JS Runtime for UnoCSS                      | No                   | -       |
| [@unocss/eslint-plugin](/integrations/eslint)                        | ESLint plugin                                     | No                   | -       |
| [@unocss/eslint-config](/integrations/eslint)                        | ESLint config                                     | No                   | -       |
| [@unocss/postcss](/integrations/postcss)                             | The PostCSS plugin                                | No                   | -       |
| [VS Code Extension](/integrations/vscode)                            | UnoCSS for VS Code                                | -                    | -       |

---

---
url: 'https://unocss.dev/config/preflights.md'
description: >-
  You can inject raw CSS as preflights from the configuration. The resolved
  theme is available to customize the CSS.
---

# Preflights

You can inject raw CSS as preflights from the configuration. The resolved `theme` is available to customize the CSS.

```ts
preflights: [
  {
    getCSS: ({ theme }) => `
      * {
        color: ${theme.colors.gray?.[700] ?? '#333'};
        padding: 0;
        margin: 0;
      }
    `,
  },
]
```

---

---
url: 'https://unocss.dev/config/presets.md'
---
# Presets

Presets are partial configurations that will be merged into the main configuration.

When authoring a preset, we usually export a constructor function that you could ask for some preset-specific options. For example:

```ts [my-preset.ts]
import { definePreset, Preset } from 'unocss'

export default definePreset((options?: MyPresetOptions) => {
  return {
    name: 'my-preset',
    rules: [
      // ...
    ],
    variants: [
      // ...
    ],
    // it supports most of the configuration you could have in the root config
  }
})
```

Then the user can use it like this:

```ts [uno.config.ts]
import { defineConfig } from 'unocss'
import myPreset from './my-preset'

export default defineConfig({
  presets: [
    myPreset({ /* preset options */ }),
  ],
})
```

You can check [official presets](/presets/) and [community presets](/presets/community) for more examples.

---

---
url: 'https://unocss.dev/guide/presets.md'
description: >-
  Presets are the heart of UnoCSS. They let you make your own custom framework
  in minutes.
---

# Presets

Presets are the heart of UnoCSS. They let you make your own custom framework in minutes.

## Using presets

To set presets to your project:

```ts twoslash [uno.config.ts]
import { defineConfig, presetAttributify, presetWind3 } from 'unocss'

export default defineConfig({
  presets: [
    presetAttributify({ /* preset options */}),
    presetWind3(),
    // ...custom presets
  ],
})
```

When the `presets` option is specified, the default preset will be ignored.

To disable the default preset, you can set `presets` to an empty array:

```ts twoslash [uno.config.ts]
import { defineConfig } from 'unocss'

export default defineConfig({
  presets: [], // disable default preset
  rules: [
    // your custom rules
  ],
})
```

You can check [official presets](/presets/) and [community presets](/presets/community) for more.

## Creating presets

To see how you can create your own custom preset, see [Config: presets](/config/presets).

---

---
url: 'https://unocss.dev/extractors/pug.md'
description: Pug extractor for UnoCSS (@unocss/extractor-pug)
---

# Pug Extractor

Support extracting classes from Pug template.

## Installation

::: code-group

```bash [pnpm]
pnpm add -D @unocss/extractor-pug
```

```bash [yarn]
yarn add -D @unocss/extractor-pug
```

```bash [npm]
npm install -D @unocss/extractor-pug
```

```bash [bun]
bun add -D @unocss/extractor-pug
```

:::

```ts [uno.config.ts]
import extractorPug from '@unocss/extractor-pug'
import { defineConfig } from 'unocss'

export default defineConfig({
  extractors: [
    extractorPug(),
  ],
})
```

---

---
url: 'https://unocss.dev/presets/rem-to-px.md'
description: Converts rem to px for utils (@unocss/preset-rem-to-px).
---

# Rem to px preset

Converts rem to px for all utilities.

[Source Code](https://github.com/unocss/unocss/tree/main/packages-presets/preset-rem-to-px)

## Installation

::: code-group

```bash [pnpm]
pnpm add -D @unocss/preset-rem-to-px
```

```bash [yarn]
yarn add -D @unocss/preset-rem-to-px
```

```bash [npm]
npm install -D @unocss/preset-rem-to-px
```

```bash [bun]
bun add -D @unocss/preset-rem-to-px
```

:::

```ts [uno.config.ts]
import presetRemToPx from '@unocss/preset-rem-to-px'
import { defineConfig } from 'unocss'

export default defineConfig({
  presets: [
    presetRemToPx(),
    // ...other presets
  ],
})
```

## Usage

```html
<div class="m-2"></div>
```

::: code-group

```css [Without]
.m-2 {
  margin: 0.5rem;
}
```

```css [With]
.m-2 {
  margin: 8px;
}
```

:::

## Options

### baseFontSize

* **Type:** `number`
* **Default:** `16`

The base font size to convert rem to px (`1rem = n px`).

---

---
url: 'https://unocss.dev/config/rules.md'
description: Writing custom rules for UnoCSS is super easy.
---

# Rules

Rules define utility classes and the resulting CSS. UnoCSS has many built-in rules but also allows for easily adding custom rules.

## Static rules

With this example:

```ts
rules: [
  ['m-1', { margin: '0.25rem' }],
]
```

The following CSS will be generated whenever `m-1` is detected in users' codebase:

```css
.m-1 {
  margin: 0.25rem;
}
```

> **Note**: The body syntax follows CSS property syntax, eg. `font-weight` instead of `fontWeight`. If there is a hyphen `-` in the property name it should be quoted.
>
> ```ts
> rules: [
>   ['font-bold', { 'font-weight': 700 }],
> ]
> ```

## Dynamic rules

To make it smarter, change the matcher to a `RegExp` and the body to a function:

```ts
rules: [
  [/^m-(\d+)$/, ([, d]) => ({ margin: `${d / 4}rem` })],
  // You can get rich context information from the second argument, such as `theme`, `symbols`, etc.
  [/^p-(\d+)$/, (match, ctx) => ({ padding: `${match[1] / 4}rem` })],
]
```

The first argument of the body function is the `RegExp` match result that can be destructured to get the matched groups.

For example, with the following usage:

```html
<div class="m-100">
  <button class="m-3">
    <icon class="p-5" />
    My Button
  </button>
</div>
```

the corresponding CSS will be generated:

```css
.m-100 { margin: 25rem; }
.m-3 { margin: 0.75rem; }
.p-5 { padding: 1.25rem; }
```

Congratulations! Now you've got your own powerful atomic CSS utilities. Enjoy!

## CSS Rules Fallback

In cases you might want to leverage CSS rules fallback to use new CSS features while also able to fallback to support old browsers, you can optionally return a 2D-array as the CSS representation for rules with the same keys. For example:

```ts
rules: [
  [/^h-(\d+)dvh$/, ([_, d]) => {
    return [
      ['height', `${d}vh`],
      ['height', `${d}dvh`],
    ]
  }],
]
```

Which will make `h-100dvh` generates:

```css
.h-100dvh { height: 100vh; height: 100dvh; }
```

## Special symbols

Since v0.61, UnoCSS supports special symbols to define additional meta information for your generated CSS. You can access the symbols from the `symbols` object from `@unocss/core` or the second argument of the dynamic rule matcher function.

For example:

::: code-group

```ts [Static Rules]
import { symbols } from '@unocss/core'

rules: [
  ['grid', {
    [symbols.parent]: '@supports (display: grid)',
    display: 'grid',
  }],
]
```

```ts [Dynamic Rules]
rules: [
  [/^grid$/, ([, d], { symbols }) => {
    return {
      [symbols.parent]: '@supports (display: grid)',
      display: 'grid',
    }
  }],
]
```

:::

Will generate:

```css
@supports (display: grid) {
  .grid {
    display: grid;
  }
}
```

:::tip
If you know exactly how a rule is generated, we recommend using **static rules** to improve UnoCSS performance.
:::

### Available symbols

| Symbols                    | Description                                                                                                |
| -------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `symbols.parent`           | The parent wrapper of the generated CSS rule (e.g., `@supports`, `@media`, etc.)                           |
| `symbols.selector`         | A function to modify the selector of the generated CSS rule (see example below)                            |
| `symbols.layer`            | Sets the UnoCSS layer of the generated CSS rule (can be string, function, or regex match)                  |
| `symbols.variants`         | An array of variant handlers applied to the current CSS object                                             |
| `symbols.shortcutsNoMerge` | Boolean to disable merging of the current rule in shortcuts                                                |
| `symbols.noMerge`          | Boolean to disable merging of the current rule                                                             |
| `symbols.sort`             | Number to overwrite sorting order of the current CSS object                                                |
| `symbols.body`             | Fully control the body of the generated CSS rule (see [#4889](https://github.com/unocss/unocss/pull/4889)) |

## Multi-selector rules

Since v0.61, UnoCSS supports multi-selector via [JavaScript Generator functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Generator). And generates *multiple* CSS rules from a *single* rule.

For example:

::: code-group

```ts [Static Rules]
rules: [
  ['button-red', [
    { background: 'red' },
    {
      [symbols.selector]: selector => `${selector}:hover`,
      // https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/color-mix
      background: `color-mix(in srgb, red 90%, black)`
    },
  ]],
]
```

```ts [Dynamic Rules]
rules: [
  [/^button-(.*)$/, function* ([, color], { symbols }) {
    yield {
      background: color
    }
    yield {
      [symbols.selector]: selector => `${selector}:hover`,
      // https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/color-mix
      background: `color-mix(in srgb, ${color} 90%, black)`
    }
  }],
]
```

:::

Will generate multiple CSS rules:

```css
.button-red {
  background: red;
}
.button-red:hover {
  background: color-mix(in srgb, red 90%, black);
}
```

## Fully controlled rules

::: tip
This is an advanced feature, in most situtations it won't be needed.
:::

When you really need some advanced rules that aren't covered by the combination of [Dynamic Rules](#dynamic-rules) and [Variants](/config/variants), UnoCSS also provides a way to give you full control to generate the CSS.

It allows you to return a string from the dynamic rule's body function which will be **directly** passed to the generated CSS (this also means you need to take care of things like CSS escaping, variant applying, CSS constructing, and so on).

```ts [uno.config.ts]
import { defineConfig, toEscapedSelector as e } from 'unocss'

export default defineConfig({
  rules: [
    [/^custom-(.+)$/, ([, name], { rawSelector, currentSelector, variantHandlers, theme }) => {
      // discard mismatched rules
      if (name.includes('something'))
        return

      // if you want, you can disable the variants for this rule
      if (variantHandlers.length)
        return
      const selector = e(rawSelector)
      // return a string instead of an object
      return `
${selector} {
  font-size: ${theme.fontSize.sm};
}
/* you can have multiple rules */
${selector}::after {
  content: 'after';
}
.foo > ${selector} {
  color: red;
}
/* or media queries */
@media (min-width: ${theme.breakpoints.sm}) {
  ${selector} {
    font-size: ${theme.fontSize.sm};
  }
}
`
    }],
  ],
})
```

::: warning
The above method can fully control the generated CSS, but it cannot be extended through `variants`, losing the flexibility brought by its variant.

e.g. `hover:custom-xxx` -> The `hover` variant won't work.
:::

So if you want to fully customize the output while still enjoying the convenience of variants, you can consider using `symbols.body` to achieve this.

::: code-group

```ts [Static Rules]
import { symbols } from '@unocss/core'

rules: [
  ['custom-red', {
    // symbols.body doesn't need `{}` wrapping the styles
    [symbols.body]: `
      font-size: 1rem;
      &::after {
        content: 'after';
      }
      & > .bar {
        color: red;
      }
    `,
    [symbols.selector]: selector => `:is(${selector})`,
  }]
]
```

```ts [Dynamic Rules]
rules: [
  [/^custom-(.+)$/, ([_, c], { symbols }) => {
    return {
      [symbols.body]: `
        font-size: 1rem;
        &::after {
          content: 'after';
        }
        & > .bar {
          color: ${c};
        }
      `,
      [symbols.selector]: selector => `:is(${selector})`,
    }
  }]
]
```

:::

Will generate fully CSS rules from `hover:custom-red`:

```css
:is(.hover\:custom-red):hover {
  font-size: 1rem;
  &::after {
    content: 'after';
  }
  & > .bar {
    color: red;
  }
}
```

## Ordering

UnoCSS respects the order of the rules you defined in the generated CSS. Latter ones come with higher priority.

When using dynamic rules, it may match multiple tokens. By default, the output of those matched under a single dynamic rule will be sorted alphabetically within the group.

## Rules merging

By default, UnoCSS will merge CSS rules with the same body to minimize the CSS size.

For example, `<div class="m-2 hover:m2">` will generate:

```css
.hover\:m2:hover,
.m-2 {
  margin: 0.5rem;
}
```

Instead of two separate rules:

```css
.hover\:m2:hover {
  margin: 0.5rem;
}
.m-2 {
  margin: 0.5rem;
}
```

---

---
url: 'https://unocss.dev/config/safelist.md'
---
# Safelist

Safelist is an important option in UnoCSS configuration that allows you to specify a set of utility classes that should always be included in the generated CSS, regardless of whether these classes are detected in your source code.

## Basic Usage

### String Array

The simplest usage is to provide a string array containing the class names you want to preserve:

```ts
// uno.config.ts
export default defineConfig({
  safelist: [
    'p-1',
    'p-2',
    'p-3',
    'text-center',
    'bg-red-500'
  ]
})
```

### Function Form

Safelist can also contain functions that are called during build time and can dynamically return class names:

```ts
// uno.config.ts
export default defineConfig({
  safelist: [
    // Static class names
    'p-1',
    'p-2',
    // Dynamic function
    context => ['m-1', 'm-2', 'm-3'],
    (context) => {
      // Generate class names based on theme
      const colors = Object.keys(context.theme.colors || {})
      return colors.map(color => `bg-${color}-500`)
    }
  ]
})
```

### Mixed Usage

You can mix strings and functions in the same safelist configuration:

```ts
// uno.config.ts
export default defineConfig({
  safelist: [
    // Static class names
    'prose',
    'bg-orange-300',
    // Dynamic generation
    () => ['flex', 'grid', 'block'],
    // Conditional dynamic generation
    (context) => {
      if (process.env.NODE_ENV === 'development') {
        return ['debug-border', 'debug-grid']
      }
      return []
    }
  ]
})
```

## Return Value Types

Safelist functions can return the following types of values:

* `Arrayable<string>` - String or string array

```ts
safelist: [
  // Return string array
  () => ['class1', 'class2', 'class3'],

  // Return single string
  () => 'single-class',

  // Return nested array (will be flattened)
  () => [['nested1', 'nested2'], 'normal3']
]
```

## Practical Use Cases

### Dynamically Generated Class Names

When you have dynamically generated class names that might not be detected by static analysis:

```ts
safelist: [
  // Dynamic color classes
  () => {
    const dynamicColors = ['primary', 'secondary', 'accent']
    return dynamicColors.flatMap(color => [
      `bg-${color}`,
      `text-${color}`,
      `border-${color}`
    ])
  },

  // Dynamic size classes
  () => {
    return Array.from({ length: 12 }, (_, i) => `gap-${i + 1}`)
  }
]
```

### Third-party Component Library Support

Provide necessary class names for third-party component libraries:

```ts
safelist: [
  // Reserved class names for component library
  'prose',
  'prose-sm',
  'prose-lg',

  // Dynamically generate component variants
  () => {
    const variants = ['primary', 'secondary', 'danger', 'success']
    const sizes = ['sm', 'md', 'lg']

    return variants.flatMap(variant =>
      sizes.map(size => `btn-${variant}-${size}`)
    )
  }
]
```

## Relationship with Other Configurations

### Difference from blocklist

* **safelist**: Ensures specified class names are always included
* **blocklist**: Ensures specified class names are always excluded

```ts
export default defineConfig({
  safelist: ['always-include'],
  blocklist: ['never-include']
})
```

### Relationship with Generation Options

When generating CSS, you can control whether to include safelist through `GenerateOptions`:

```ts
const { css } = await uno.generate('', {
  safelist: true // Include class names from safelist
})
```

---

---
url: 'https://unocss.dev/config/shortcuts.md'
description: >-
  The shortcuts functionality that UnoCSS provides is similar to Windi CSS's
  one.
---

# Shortcuts

Shortcuts let you combine multiple rules into a single shorthand, inspired by [Windi CSS's](https://windicss.org/features/shortcuts.html).

## Usage

```ts
shortcuts: {
  // shortcuts to multiple utilities
  'btn': 'py-2 px-4 font-semibold rounded-lg shadow-md',
  'btn-green': 'text-white bg-green-500 hover:bg-green-700',
  // single utility alias
  'red': 'text-red-100',
}
```

In addition to the plain mapping, UnoCSS also allows you to define dynamic shortcuts.

Similar to [Rules](/config/rules), a dynamic shortcut is the combination of a matcher `RegExp` and a handler function.

```ts
shortcuts: [
  // you could still have object style
  {
    btn: 'py-2 px-4 font-semibold rounded-lg shadow-md',
  },
  // dynamic shortcuts
  [/^btn-(.*)$/, ([, c]) => `bg-${c}-400 text-${c}-100 py-2 px-4 rounded-lg`],
]
```

With this, we could use `btn-green` and `btn-red` to generate the following CSS:

```css
.btn-green {
  padding-top: 0.5rem;
  padding-bottom: 0.5rem;
  padding-left: 1rem;
  padding-right: 1rem;
  --un-bg-opacity: 1;
  background-color: rgb(74 222 128 / var(--un-bg-opacity));
  border-radius: 0.5rem;
  --un-text-opacity: 1;
  color: rgb(220 252 231 / var(--un-text-opacity));
}
.btn-red {
  padding-top: 0.5rem;
  padding-bottom: 0.5rem;
  padding-left: 1rem;
  padding-right: 1rem;
  --un-bg-opacity: 1;
  background-color: rgb(248 113 113 / var(--un-bg-opacity));
  border-radius: 0.5rem;
  --un-text-opacity: 1;
  color: rgb(254 226 226 / var(--un-text-opacity));
}
```

---

---
url: 'https://unocss.dev/guide/style-reset.md'
description: >-
  UnoCSS does not provide style resetting or preflight by default for maximum
  flexibility and does not populate your global CSS.
---

# Browser Style Reset

UnoCSS does not provide style resetting or preflight by default so not to populate your global CSS and also for maximum flexibility. If you use UnoCSS along with other CSS frameworks, they probably already do the resetting for you. If you use UnoCSS alone, you can use resetting libraries like [Normalize.css](https://github.com/csstools/normalize.css).

We also provide a small collection for you to grab them quickly:

## Installation

::: code-group

```bash [pnpm]
pnpm add @unocss/reset
```

```bash [yarn]
yarn add @unocss/reset
```

```bash [npm]
npm install @unocss/reset
```

```bash [bun]
bun add @unocss/reset
```

:::

## Usage

You can add one of the following reset stylesheets to your `main.js`.

### Normalize.css

Source: https://github.com/csstools/normalize.css

```ts
import '@unocss/reset/normalize.css'
```

### sanitize.css

Source: https://github.com/csstools/sanitize.css

```ts
import '@unocss/reset/sanitize/sanitize.css'
import '@unocss/reset/sanitize/assets.css'
```

### Eric Meyer

Source: https://meyerweb.com/eric/tools/css/reset/index.html

```ts
import '@unocss/reset/eric-meyer.css'
```

### Tailwind

Based on older [Preflight](https://github.com/tailwindlabs/tailwindcss/blob/v3.4.18/src/css/preflight.css), with select recent changes

```ts
import '@unocss/reset/tailwind.css'
```

### Tailwind v4

Based on [Preflight](https://github.com/tailwindlabs/tailwindcss/blob/main/packages/tailwindcss/preflight.css)

```ts
import '@unocss/reset/tailwind-v4.css'
```

### Tailwind compat

```ts
import '@unocss/reset/tailwind-compat.css'
```

This reset is based on [Tailwind reset](#tailwind), minus the background color override for buttons to avoid conflicts with UI frameworks. See [linked issue](https://github.com/unocss/unocss/issues/2127).

::: code-group

```css [Before]
button,
[type='button'],
[type='reset'],
[type='submit'] {
  -webkit-appearance: button; /* 1 */
  background-color: transparent; /* 2 */
  background-image: none; /* 2 */
}
```

```css [After]
button,
[type='button'],
[type='reset'],
[type='submit'] {
  -webkit-appearance: button; /* 1 */
  /*background-color: transparent; !* 2 *!*/
  background-image: none; /* 2 */
}
```

:::

---

---
url: 'https://unocss.dev/extractors/svelte.md'
---

# Svelte Extractor

Supports extracting classes from `class:` directive.

```svelte
<div class:text-orange-400={foo} />
```

Will be extracted as `text-orange-400` and generates:

```css
.text-orange-400 {
  color: #f6993f;
}
```

## Installation

::: code-group

```bash [pnpm]
pnpm add -D @unocss/extractor-svelte
```

```bash [yarn]
yarn add -D @unocss/extractor-svelte
```

```bash [npm]
npm install -D @unocss/extractor-svelte
```

```bash [bun]
bun add -D @unocss/extractor-svelte
```

:::

```ts [uno.config.ts]
import extractorSvelte from '@unocss/extractor-svelte'
import { defineConfig } from 'unocss'

export default defineConfig({
  extractors: [
    extractorSvelte(),
  ],
})
```

---

---
url: 'https://unocss.dev/presets/tagify.md'
description: Tagify Mode for UnoCSS (@unocss/preset-tagify).
---

# Tagify preset

This enables the [tagify mode](#tagify-mode) for other presets.

[Source Code](https://github.com/unocss/unocss/tree/main/packages-presets/preset-tagify)

## Installation

::: code-group

```bash [pnpm]
pnpm add -D @unocss/preset-tagify
```

```bash [yarn]
yarn add -D @unocss/preset-tagify
```

```bash [npm]
npm install -D @unocss/preset-tagify
```

```bash [bun]
bun add -D @unocss/preset-tagify
```

:::

```ts [uno.config.ts]
import presetTagify from '@unocss/preset-tagify'
import { defineConfig } from 'unocss'

export default defineConfig({
  presets: [
    presetTagify({ /* options */ }),
    // ...other presets
  ],
})
```

## Tagify mode

This preset can come in handy when you only need to apply a single unocss rule to an element.

```html
<span class="text-red"> red text </span>
<div class="flex">flexbox</div>
I'm feeling <span class="i-line-md-emoji-grin"></span> today!
```

With tagify mode, you can embed CSS styles into HTML tags:

```html
<text-red> red text </text-red>
<flex> flexbox </flex>
I'm feeling <i-line-md-emoji-grin /> today!
```

The HTML above works exactly as you would expect.

## With prefix

```js
presetTagify({
  prefix: 'un-'
})
```

```html
<!-- this will be matched -->
<un-flex> </un-flex>
<!-- this will not be matched -->
<flex> </flex>
```

## Extra properties

You can inject extra properties to the matched rules:

```js
presetTagify({
  // adds display: inline-block to matched icons
  extraProperties: matched => matched.startsWith('i-')
    ? { display: 'inline-block' }
    : { }
})
```

```js
presetTagify({
  // extraProperties can also be a plain object
  extraProperties: { display: 'block' }
})
```

## Options

### prefix

* **Type:** `string`

The prefix to use for the tagify variant.

### excludedTags

* **Type:** `(string | RegExp)[]`
* **Default:** `['b', /^h\d+$/, 'table']`

Tags excluded from processing.

### extraProperties

* **Type:** `Record<string, string> | ((matched: string) => Partial<Record<string, string>>)`

Extra CSS properties to apply to matched rules.

### defaultExtractor

* **Type:** `boolean`
* **Default:** `true`

Enable default extractor.

---

---
url: 'https://unocss.dev/config/theme.md'
description: >-
  UnoCSS also supports the theming system that you might be familiar with in
  Tailwind CSS / Windi CSS.
---

# Theme

UnoCSS also supports the theming system that you might be familiar with in Tailwind CSS / Windi CSS. At the user level, you can specify the `theme` property in your config, and it will be deep-merged to the default theme.

## Usage

```ts
theme: {
  // ...
  colors: {
    veryCool: '#0000ff', // class="text-very-cool"
    brand: {
      primary: 'hsl(var(--hue, 217) 78% 51%)', //class="bg-brand-primary"
      DEFAULT: '#942192' //class="bg-brand"
    },
  },
}
```

::: tip
During the parsing process, `theme` will always exist in `context`.
:::

### Usage in `rules`

To consume the theme in rules:

```ts
rules: [
  [/^text-(.*)$/, ([, c], { theme }) => {
    if (theme.colors[c])
      return { color: theme.colors[c] }
  }],
]
```

### Usage in `variants`

To consume the theme in variants:

```ts
variants: [
  {
    name: 'variant-name',
    match(matcher, { theme }) {
      // ...
    },
  },
]
```

### Usage in `shortcuts`

To consume the theme in dynamic shortcuts:

```ts
shortcuts: [
  [/^badge-(.*)$/, ([, c], { theme }) => {
    if (Object.keys(theme.colors).includes(c))
      return `bg-${c}4:10 text-${c}5 rounded`
  }],
]
```

## Breakpoints

::: warning
When a custom `breakpoints` object is provided the default will be overridden instead of merging.
:::

With the following example, you will be able to only use the `sm:` and `md:` breakpoint variants:

```ts
theme: {
  // ...
  breakpoints: {
    sm: '320px',
    md: '640px',
  },
}
```

::: tip
In `presetWind4` the key was changed changed to `breakpoint`.

For the `presetWind4` theme docs see https://unocss.dev/presets/wind4#theme.
:::

If you want to inherit the `original` theme breakpoints, you can use the `extendTheme`:

```ts
extendTheme: (theme) => {
  return {
    ...theme,
    breakpoints: {
      ...theme.breakpoints,
      sm: '320px',
      md: '640px',
    },
  }
}
```

::: info
`verticalBreakpoints` is same as `breakpoints` but for vertical layout.
:::

In addition we will sort screen points by size (same unit). For screen points in different units, in order to avoid errors, please use unified units in the configuration.

```ts
theme: {
  // ...
  breakpoints: {
    sm: '320px',
    // Because uno does not support comparison sorting of different unit sizes, please convert to the same unit.
    // md: '40rem',
    md: `${40 * 16}px`,
    lg: '960px',
  },
}
```

## ExtendTheme

`ExtendTheme` allows you to edit the **deeply merged theme** to get the complete theme object.

Custom functions mutate the theme object.

```ts
extendTheme: (theme) => {
  theme.colors.veryCool = '#0000ff' // class="text-very-cool"
  theme.colors.brand = {
    primary: 'hsl(var(--hue, 217) 78% 51%)', // class="bg-brand-primary"
  }
}
```

It's also possible to return a new theme object to completely replace the original one.

```ts
extendTheme: (theme) => {
  return {
    ...theme,
    colors: {
      ...theme.colors,
      veryCool: '#0000ff', // class="text-very-cool"
      brand: {
        primary: 'hsl(var(--hue, 217) 78% 51%)', // class="bg-brand-primary"
      },
    },
  }
}
```

---

---
url: 'https://unocss.dev/config/transformers.md'
---
# Transformers

Provides a unified interface to transform source code in order to support conventions.

```ts [my-transformer.ts]
import { SourceCodeTransformer } from 'unocss'
import { createFilter } from 'unplugin-utils'

export default function myTransformers(options: MyOptions = {}): SourceCodeTransformer {
  return {
    name: 'my-transformer',
    enforce: 'pre', // enforce before other transformers
    idFilter(id) {
      // only transform .tsx and .jsx files
      return id.match(/\.[tj]sx$/)
    },
    async transform(code, id, { uno }) {
      // code is a MagicString instance
      code.appendRight(0, '/* my transformer */')
    },
  }
}
```

You can check [official transformers](/presets/#transformers) for more examples.

---

---
url: 'https://unocss.dev/presets/typography.md'
description: Typography classes for UnoCSS (@unocss/preset-typography).
---

# Typography preset

Provides a set of prose classes you can use to add typographic defaults to vanilla HTML.

[Source Code](https://github.com/unocss/unocss/tree/main/packages-presets/preset-typography)

## Installation

::: code-group

```bash [pnpm]
pnpm add -D @unocss/preset-typography
```

```bash [yarn]
yarn add -D @unocss/preset-typography
```

```bash [npm]
npm install -D @unocss/preset-typography
```

```bash [bun]
bun add -D @unocss/preset-typography
```

:::

::: tip
This preset is included in the `unocss` package, you can also import it from there:

```ts
import presetTypography from '@unocss/preset-typography'
// or
import { presetTypography } from 'unocss'
```

:::

## Usage

```ts [uno.config.ts]
import {
  defineConfig,
  presetAttributify,
  presetTypography,
  presetWind3 // or presetWind4
} from 'unocss'

export default defineConfig({
  presets: [
    presetWind3(), // required!
    presetAttributify(), // required when using attributify mode
    presetTypography(),
  ],
})
```

::: code-group

```html [Classes]
<article class="text-base prose dark:prose-invert xl:text-xl">
  {{ markdown }}
  <p class="not-prose">Some text</p>
</article>
```

```html [Attributes]
<article text-base prose="~ dark:invert" xl="text-xl">
  {{ markdown }}
  <p class="not-prose">Some text</p>
</article>
```

:::

::: warning
Notice: `not-prose` can only be used as a class, not as an attribute.
:::

## Highlights

### Any size

Apply different typography sizes with built-in size variants: `prose-sm`, `prose-base`, `prose-lg`, `prose-xl`, and `prose-2xl`. The default `prose` class uses the base size, and you can override it with specific size utilities.

```html
<!-- Different sizes -->
<article class="prose prose-sm">Small typography</article>
<article class="prose prose-base">Base typography (default)</article>
<article class="prose prose-lg">Large typography</article>
<article class="prose prose-xl">Extra large typography</article>
<article class="prose prose-2xl">2X large typography</article>
```

You can also combine size utilities with responsive variants:

```html
<!-- Responsive typography sizes -->
<article class="prose prose-sm md:prose-base lg:prose-lg xl:prose-xl">
  Responsive typography that scales with screen size
</article>

<!-- Use with other utilities -->
<article class="prose prose-lg prose-gray dark:prose-invert">Large typography with color and dark mode</article>
```

### Any color

Apply any color with `prose-${colorName}` utilities provided by `presetWind3/4`. Their colors come from the theme's `colors` key, and it's recommended that these colors have a range from `50` to `950` for proper gradation. Therefore, `presetWind3/4` is **required**

And the default color for `prose` is `prose-gray`. The prose color utilities will apply to various typographic elements such as headings, links, blockquotes, and code blocks.

```html
<!-- Different color themes -->
<article class="prose prose-gray">Gray themed typography</article>
<article class="prose prose-blue">Blue themed typography</article>
<article class="prose prose-green">Green themed typography</article>
<article class="prose prose-purple">Purple themed typography</article>
```

| Natural Colors                                                                   | Accent Colors                                                    |
| -------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| These have different color scheduling ranges, affecting global typography usage. | These only change the link color and do not affect other colors. |
| `prose-slate`                                                                    | `prose-rose`                                                     |
| `prose-slate`                                                                    | `prose-red`                                                      |
| `prose-gray`                                                                     | `prose-orange`                                                   |
| `prose-zinc`                                                                     | `prose-amber`                                                    |
| `prose-neutral`                                                                  | `prose-yellow`                                                   |
| `prose-stone`                                                                    | `prose-lime`                                                     |
|                                                                                  | `prose-green`                                                    |
|                                                                                  | `prose-emerald`                                                  |
|                                                                                  | `prose-teal`                                                     |
|                                                                                  | `prose-cyan`                                                     |
|                                                                                  | `prose-sky`                                                      |
|                                                                                  | `prose-blue`                                                     |
|                                                                                  | `prose-indigo`                                                   |
|                                                                                  | `prose-violet`                                                   |
|                                                                                  | `prose-purple`                                                   |
|                                                                                  | `prose-fuchsia`                                                  |
|                                                                                  | `prose-pink`                                                     |
|                                                                                  | `prose-rose`                                                     |

You can combine colors with sizes and responsive variants:

```html
<!-- Responsive color changes -->
<article class="prose prose-gray md:prose-blue lg:prose-green">
  Typography that changes color at different breakpoints
</article>

<!-- Color with size and dark mode -->
<article class="prose prose-lg prose-slate dark:prose-invert">
  Large typography with slate color and dark mode support
</article>
```

### Dark mode with a single utility

Apply typographic dark mode with `prose-invert` (background color needs to be
handled by users). For instance, `prose dark:prose-invert` will use the
inverted colors in the dark mode.

### Your very own style

Styles of elements not within `prose` will stay the same. No style resetting
just like UnoCSS.

### Undo with `not` utility

Apply `not-prose` to the elements to undo the typographic styles. For
instance, `<table class="not-prose">` will skip the styles by this preset for
the `table` element **(NOTE: `not` utility is only usable in class since it is
only used in CSS** **selector & not scanned by UnoCSS)**.

### Compatibility options

This preset uses some pseudo-classes which are not widely supported, but you
can disable them. ([#2064](https://github.com/unocss/unocss/pull/2064))

* If you enable `noColonNot` or `noColonWhere`, `not-prose` will be unavailable.
* If you enable `noColonIs`, attributify mode will have a wrong behavior.

## Options

This preset provides comprehensive configuration options for customizing typography styles, colors, sizes, and behavior.

:::tip
The CSS declarations passed to `cssExtend` will

* **override** the built-in styles if the values are conflicting, else
* **be merged** deeply with built-in styles.
  :::

### selectorName

* **Type:** `string`
* **Default:** `prose`

The class name to use the typographic utilities. To undo the styles to the elements, use it like `not-${selectorName}` which is by default `not-prose`.

:::tip
`not` utility is only available in class.
:::

### cssExtend

* **Type:** `Record<string, CSSObject> | ((theme: T) => Record<string, CSSObject>)`
* **Default:** `undefined`

Extend or override CSS selectors with CSS declaration block. Can be either a static object or a function that receives the theme and returns CSS selectors.

### important

* **Type:** `boolean | string`
* **Default:** `false`

Control whether prose utilities should be marked with `!important`. When set to `true`, all prose styles will have `!important` added. When set to a string, it will be used as a CSS selector scope.

### colorScheme

* **Type:** `TypographyColorScheme`
* **Default:** See below

Color scheme for typography elements. Each key represents a typographic element with values in the format `[light, dark]` => `[color, invert-color]`.

**Default color scheme:**

```json
{
  "body": [700, 300],
  "headings": [900, "white"],
  "lead": [600, 400],
  "links": [900, "white"],
  "bold": [900, "white"],
  "counters": [500, 400],
  "bullets": [300, 600],
  "hr": [200, 700],
  "quotes": [900, 100],
  "quote-borders": [200, 700],
  "captions": [500, 400],
  "kbd": [900, "white"],
  "kbd-shadows": [900, "white"],
  "code": [900, "white"],
  "pre-code": [200, 300],
  "pre-bg": [800, "rgb(0 0 0 / 50%)"],
  "th-borders": [300, 600],
  "td-borders": [200, 700]
}
```

### sizeScheme

* **Type:** `TypographySizeScheme`
* **Default:** `undefined`

Size scheme for typography elements. Allows you to customize the CSS styles of various typographic elements for different sizes. Similar to `cssExtend`, but applies granular overlays to different text sizes.

**Example:**

```json
{
  "sm": {
    "h1": { "font-size": "1.5rem" },
    "p": { "font-size": "0.875rem" }
  },
  "base": {
    "h1": { "font-size": "2rem" },
    "p": { "font-size": "1rem" }
  },
  "lg": {
    "h1": { "font-size": "2.5rem" },
    "p": { "font-size": "1.125rem" }
  }
}
```

### cssVarPrefix

* **Type:** `string`
* **Default:** `--un-prose`

Prefix for generated CSS custom properties (CSS variables). This allows you to customize the naming of CSS variables used internally by the preset.

### compatibility

* **Type:** `TypographyCompatibilityOptions`
* **Default:** `undefined`

See [Compatibility options](#compatibility-options).
:::warning
Notice that it will affect some features.
:::

```ts
interface TypographyCompatibilityOptions {
  noColonWhere?: boolean
  noColonIs?: boolean
  noColonNot?: boolean
}
```

## Example

```ts [uno.config.ts]
import { presetTypography } from '@unocss/preset-typography'
import { defineConfig, presetAttributify, presetWind3 } from 'unocss'

export default defineConfig({
  presets: [
    presetAttributify(), // required if using attributify mode
    presetWind3(), // required
    presetTypography({
      selectorName: 'markdown', // now use like `markdown markdown-gray`, `not-markdown`
      // cssExtend is an object with CSS selector as key and
      // CSS declaration block as value like writing normal CSS.
      cssExtend: {
        'code': {
          color: '#8b5cf6',
        },
        'a:hover': {
          color: '#f43f5e',
        },
        'a:visited': {
          color: '#14b8a6',
        },
      },
    }),
  ],
})
```

## Acknowledgement

* [Tailwind CSS Typography](https://github.com/tailwindlabs/tailwindcss-typography)
* [Windi CSS Typography](https://github.com/windicss/windicss/tree/main/src/plugin/typography)

---

---
url: 'https://unocss.dev/integrations/astro.md'
description: The UnoCSS integration for Astro (@unocss/astro).
---

# Astro Integration

The UnoCSS integration for [Astro](https://astro.build/): `@unocss/astro`. Check the [example](https://github.com/unocss/unocss/tree/main/examples/astro).

## Installation

::: code-group

```bash [pnpm]
pnpm add -D unocss @unocss/astro
```

```bash [yarn]
yarn add -D unocss @unocss/astro
```

```bash [npm]
npm install -D unocss @unocss/astro
```

```bash [bun]
bun add -D unocss @unocss/astro
```

:::

```ts [astro.config.ts]
import { defineConfig } from 'astro/config'
import UnoCSS from 'unocss/astro'

export default defineConfig({
  integrations: [
    UnoCSS(),
  ],
})
```

Create a `uno.config.ts` file:

```ts [uno.config.ts]
import { defineConfig } from 'unocss'

export default defineConfig({
  // ...UnoCSS options
})
```

### Style Reset

By default, [browser style reset](/guide/style-reset) will not be injected. To enable it, install the `@unocss/reset` package:

::: code-group

```bash [pnpm]
pnpm add -D @unocss/reset
```

```bash [yarn]
yarn add -D @unocss/reset
```

```bash [npm]
npm install -D @unocss/reset
```

```bash [bun]
bun add -D @unocss/reset
```

:::

And update your `astro.config.ts`:

```ts [astro.config.ts]
import { defineConfig } from 'astro/config'
import UnoCSS from 'unocss/astro'

export default defineConfig({
  integrations: [
    UnoCSS({
      injectReset: true // or a path to the reset file
    }),
  ],
})
```

### Usage without presets

This plugin does not come with any default presets.

::: code-group

```bash [pnpm]
pnpm add -D @unocss/astro
```

```bash [yarn]
yarn add -D @unocss/astro
```

```bash [npm]
npm install -D @unocss/astro
```

```bash [bun]
bun add -D @unocss/astro
```

:::

```ts [astro.config.mjs]
import UnoCSS from '@unocss/astro'

export default {
  integrations: [
    UnoCSS(),
  ],
}
```

For more details, please refer to the [Vite plugin](/integrations/vite).

::: info
If you are building a meta framework on top of UnoCSS, see [this file](https://github.com/unocss/unocss/blob/main/packages-presets/unocss/src/astro.ts) for an example on how to bind the default presets.
:::

## Notes

[`client:only`](https://docs.astro.build/en/reference/directives-reference/#clientonly) components must be placed in [`components`](https://docs.astro.build/en/core-concepts/project-structure/#srccomponents) folder or added to UnoCSS's `content` config in order to be processed.

---

---
url: 'https://unocss.dev/integrations/runtime.md'
description: CSS-in-JS runtime of UnoCSS (@unocss/runtime).
---

# Runtime

UnoCSS runtime provide a CDN build that runs the UnoCSS right in the browser. It will detect the DOM changes and generate the styles on the fly.

## Usage

Add the following line to your `index.html`:

```html [index.html]
<script src="https://cdn.jsdelivr.net/npm/@unocss/runtime"></script>
```

The runtime may be configured by defining the configuration before loading the runtime:

```html
<!-- define unocss options... -->
<script>
  window.__unocss = {
    rules: [
      // custom rules...
    ],
    presets: [
      // custom presets...
    ],
    // ...
  }
</script>
<!-- ... and then load the runtime -->
<script src="https://cdn.jsdelivr.net/npm/@unocss/runtime"></script>
```

By default, the [Wind3 preset](/presets/wind3) is be applied.

The runtime does not come with preflights, if you want to have style resets, you can either add your own, or use one from [Reset package](/guide/style-reset).

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@unocss/reset/normalize.min.css" />
<!-- or -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@unocss/reset/tailwind.min.css" />
```

## Builds

Several builds are available for different use cases.

### Uno (default)

With `@unocss/preset-wind3` preset:

```html
<script src="https://cdn.jsdelivr.net/npm/@unocss/runtime/uno.global.js"></script>
```

### Attributify

With `@unocss/preset-wind3` and `@unocss/preset-attributify` presets:

```html
<script src="https://cdn.jsdelivr.net/npm/@unocss/runtime/attributify.global.js"></script>
```

### Mini

With `@unocss/preset-mini` and `@unocss/preset-attributify` preset:

```html
<script src="https://cdn.jsdelivr.net/npm/@unocss/runtime/mini.global.js"></script>
```

### Core

If you need to mix and match presets, you can load only the core runtime and assign the presets manually. All the [official presets](/presets/#presets) from UnoCSS are available. Load the one you need before initializing the core runtime.

```html
<script src="https://cdn.jsdelivr.net/npm/@unocss/runtime/preset-icons.global.js"></script>
<script>
  window.__unocss = {
    presets: [
      () =>
        window.__unocss_runtime.presets.presetIcons({
          scale: 1.2,
          cdn: 'https://esm.sh/',
        }),
    ],
  }
</script>
<script src="https://cdn.jsdelivr.net/npm/@unocss/runtime/core.global.js"></script>
```

## Bundler Usage

```bash
npm i @unocss/runtime
```

```ts
import initUnocssRuntime from '@unocss/runtime'

initUnocssRuntime({ /* options */ })
```

A UnoCSS config can be provided using the `defaults` property:

```ts
import initUnocssRuntime from '@unocss/runtime'
import config from './uno.config'

initUnocssRuntime({ defaults: config })
```

Presets can be imported from `esm.sh`:

```ts
import { defineConfig } from '@unocss/runtime'
import presetIcons from 'https://esm.sh/@unocss/preset-icons/browser'
import presetWind3 from 'https://esm.sh/@unocss/preset-wind3'

export default defineConfig({
  presets: [presetWind3(), presetIcons({ cdn: 'https://esm.sh/' })],
})
```

## Preventing FOUC

Since UnoCSS runs after the DOM is ready, there can be a "flash of unstyled content" (FOUC) which may leads the user to see the page as unstyled.

Use `un-cloak` attribute with CSS rules such as `[un-cloak] { display: none }` to hide the unstyled element until UnoCSS applies the styles for it.

::: code-group

```css
[un-cloak] {
  display: none;
}
```

```html
<div class="text-blue-500" un-cloak>This text will only be visible in blue color.</div>
```

:::

---

---
url: 'https://unocss.dev/integrations/cli.md'
description: The CLI for UnoCSS (@unocss/cli).
---

# CLI

The command line interface for UnoCSS: `@unocss/cli`.

* 🍱 Extract utilities from scoped files
* 👀 [Watch mode](#development) included
* 🔌 Supports custom configurations via [`uno.config.ts`](#configurations)
* ⚙️ Various [options](#options) to customize the output
* 🚀 Supports multiple [entry patterns](#usage)

## Installation

This package is shipped with the `unocss` package:

::: code-group

```bash [pnpm]
pnpm add -D unocss
```

```bash [yarn]
yarn add -D unocss
```

```bash [npm]
npm install -D unocss
```

```bash [bun]
bun add -D unocss
```

:::

You can also install the standalone package:

::: code-group

```bash [pnpm]
pnpm add -D @unocss/cli
```

```bash [yarn]
yarn add -D @unocss/cli
```

```bash [npm]
npm install -D @unocss/cli
```

```bash [bun]
bun add -D @unocss/cli
```

:::

::: info
If you are not able to find the binary (e.g. with `pnpm` and only `unocss` is installed), you'll need to explicit install `@unocss/cli` standalone package.
:::

## Usage

You can also pass multiple glob patterns to `@unocss/cli`:

```bash
unocss "site/snippets/**/*.php" "site/templates/**/*.php"
```

Example package configuration:

::: info
Make sure to add escaped quotes to your npm script glob patterns.
:::

```json [package.json]
{
  "scripts": {
    "dev": "unocss \"site/{snippets,templates}/**/*.php\" --watch",
    "build": "unocss \"site/{snippets,templates}/**/*.php\""
  },
  "devDependencies": {
    "@unocss/cli": "latest"
  }
}
```

### Development

Add the `--watch` (or `-w`) flag to enable watching for file changes:

```bash
unocss "site/{snippets,templates}/**/*.php" --watch
```

### Production

```bash
unocss "site/{snippets,templates}/**/*.php"
```

The final `uno.css` will be generated to the current directory by default.

## Built-in features

### Configurations

Create a `uno.config.js` or `uno.config.ts` configuration file the root-level of your project to customize UnoCSS.

::: tip
To achieve more granular configuration management, we recommend using a configuration file. It also supports different levels of packaging and rewriting for scanned files.
:::

```ts [uno.config.ts]
import { defineConfig } from 'unocss'

export default defineConfig({
  cli: {
    entry: {}, // CliEntryItem | CliEntryItem[]
  },
  // ...
})

interface CliEntryItem {
  /**
   * Glob patterns to match files
   */
  patterns: string[]
  /**
   * The output filename for the generated UnoCSS file
   */
  outFile: string
  /**
   * Whether to rewrite the transformed utilities.
   *
   * - For css: if rewrite is true, it will not generate a new file, but directly modify the original file content.
   * - For other files: if rewrite is true, it replaces the original file with the transformed content.
   *
   * @default false
   */
  rewrite?: boolean

  /**
   * Whether to output CSS files scanned from patterns to outFile
   *
   * - false: Do not output CSS files
   * - true: Transform and output scanned CSS file contents to outFile
   * - 'multi': Output each CSS file separately with filename format `${originFile}-[hash]`
   * - 'single': Merge multiple CSS files into one output file named `outFile-merged.css`
   *
   * @default true
   */
  splitCss?: boolean | 'multi' | 'single'
}
```

### Rewrite Source Files

Use the `--rewrite` flag to update your source files with transformed utilities. This is useful when you want to apply transformers (like [Variant Groups](/transformers/variant-group) or [Compile Class](/transformers/compile-class)) directly to your code.

```bash
unocss "src/**/*.vue" --rewrite
```

### CSS Splitting

When CSS files are included in the defined patterns, use the `--split-css` flag to control the output of CSS.

* false: Do not output CSS files
* true: Transform and output scanned CSS file contents to outFile
* 'multi': Output each CSS file separately with filename format `${originFile}-[hash]`
* 'single': Merge multiple CSS files into one output file named `outFile-merged.css`

```bash
unocss "src/**/*.vue" --split-css true|false|multi|single
```

### Default Preset

If no `uno.config.ts` file is found, the CLI will use a default preset. You can specify which version of the default preset to use with the `--preset` flag.

* `wind4`: Use the `preset-wind4`.
* `wind3`: Use the `preset-wind3`.

```bash
unocss "src/**/*.vue" --preset wind3|wind4
```

> Note: This option is ignored if a configuration file is present.

::: warning
Starting from version `v66.6.0`, `@unocss/cli` no longer provides a default preset. Users need to explicitly specify the `--preset` option or configure the preset in the configuration file.
:::

For a list of options, head over to the [UnoCSS configurations](/config/) docs.

## Options

| Options                     |                                                                                                                |
| --------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `-v, --version`             | Display the current version of UnoCSS                                                                          |
| `-c, --config [file]`       | Config file                                                                                                    |
| `-o, --out-file <file>`     | The output filename for the generated UnoCSS file. Defaults to `uno.css` in the current working directory      |
| `--stdout`                  | Write the generated UnoCSS file to STDOUT. Will cause the `--watch` and `--out-file` being ignored             |
| `-w, --watch`               | Indicates if the files found by the glob pattern should be watched                                             |
| `--preflights`              | Enable preflight styles                                                                                        |
| `--rewrite`                 | Update source files with transformed utilities                                                                 |
| `--write-transformed`       | Update source files with transformed utilities (deprecated, use `--rewrite`)                                   |
| `-m, --minify`              | Minify generated CSS                                                                                           |
| `--debug`                   | Enable debug mode                                                                                              |
| `--split-css [mode]`        | Whether to output CSS files scanned from patterns to outFile. Options: `true`, `false`, `multi`, `single`      |
| `--preset [default-preset]` | Switch `wind3` or `wind4` preset as default. If you have configured `uno.config`, this option will be ignored. |
| `-h, --help`                | Display available CLI options                                                                                  |

---

---
url: 'https://unocss.dev/integrations/eslint.md'
description: ESLint config for UnoCSS (@unocss/eslint-config).
---

# ESLint Config

ESLint config for UnoCSS: `@unocss/eslint-config`.

## Installation

::: code-group

```bash [pnpm]
pnpm add -D @unocss/eslint-config
```

```bash [yarn]
yarn add -D @unocss/eslint-config
```

```bash [npm]
npm install -D @unocss/eslint-config
```

```bash [bun]
bun add -D @unocss/eslint-config
```

:::

In [Flat Config Style](https://eslint.org/docs/latest/use/configure/configuration-files-new):

```js [eslint.config.js]
import unocss from '@unocss/eslint-config/flat'

export default [
  unocss,
  // other configs
]
```

In legacy `.eslintrc` style:

```json [.eslintrc]
{
  "extends": [
    "@unocss"
  ]
}
```

## Rules

* `@unocss/order` - Enforce a specific order for class selectors.
* `@unocss/order-attributify` - Enforce a specific order for attributify selectors.
* `@unocss/blocklist` - Disallow specific class selectors \[Optional].
* `@unocss/enforce-class-compile` - Enforce class compile \[Optional].

### Rule options

#### `@unocss/order`

* `unoFunctions` (string\[]) - mark function calls of matched names to enforce this rule. These are plain names, not patterns, case insensitive. Default: `['clsx', 'classnames']`.
* `unoVariables` (string\[]) - mark variable declarations of matched names to enforce this rule. These are regex patterns with flags `i`. Default: `['^cls', 'classNames?$']`. for example will match variable names `clsButton` and `buttonClassNames`.

### Optional rules

These rules are not enabled by default. To enable it, add the following to your `.eslintrc`:

```json [.eslintrc]
{
  "extends": [
    "@unocss"
  ],
  "rules": {
    "@unocss/<rule-name>": "warn", // or "error",
    "@unocss/<another-rule-name>": ["warn" /* or "error" */, { /* options */ }]
  }
}
```

#### `@unocss/blocklist`

Throw warning or error when using utilities listed in `blocklist` get matched.

You can customize messages for blocked rules to make them more informative and context-specific by using the `message` property of the meta object:

```ts [unocss.config.ts]
export default defineConfig({
  blocklist: [
    ['bg-red-500', { message: 'Use bg-red-600 instead' }],
    [/-auto$/, { message: s => `Use ${s.replace(/-auto$/, '-a')} instead` }], // -> "my-auto" is in blocklist: Use "my-a" instead
  ],
})
```

#### `@unocss/enforce-class-compile` :wrench:

*This rule is designed to work in combination with [compile class transformer](https://unocss.dev/transformers/compile-class).*

Throw warning or error when class attribute or directive doesn't start with `:uno:`.

:wrench: automatically adds prefix `:uno:` to all class attributes and directives.

Options:

* `prefix` (string) - can be used in combination with [custom prefix](https://github.com/unocss/unocss/blob/main/packages-presets/transformer-compile-class/src/index.ts#L34). Default: `:uno:`
* `enableFix` (boolean) - can be used for gradual migration when `false`. Default: `true`

**Note**: currently only Vue supported. *Contribute a PR* if you want this in JSX. If you're looking for this in Svelte, you might be looking for [`svelte-scoped`](https://unocss.dev/integrations/svelte-scoped) mode.

## Prior Arts

Thanks to [eslint-plugin-unocss](https://github.com/devunt/eslint-plugin-unocss) by [@devunt](https://github.com/devunt).

---

---
url: 'https://unocss.dev/integrations/lsp.md'
---

# LSP Support for UnoCSS

UnoCSS Language Server provides IDE-like support for UnoCSS in any editor that supports LSP (Neovim, VS Code, Emacs, etc).

:::info
Note: This is a **community-maintained language server, not officially maintained by the UnoCSS team**. Use at your own discretion. Report issues at [xna00/unocss-language-server](https://github.com/xna00/unocss-language-server).
:::

## Installation

```bash
npm install -g unocss-language-server
```

## Features

* Auto-completion for UnoCSS utilities
* Hover documentation with CSS previews

## Usage

Start the language server with:

```bash
unocss-language-server --stdio
```

Configure your editor’s LSP client to connect to it.

## Bug Reports / Feature Requests

Report it at [Issue Tracker](https://github.com/xna00/unocss-language-server/issues)

---

---
url: 'https://unocss.dev/integrations/nuxt.md'
description: Nuxt module for UnoCSS.
---

# Nuxt Module

The Nuxt module for UnoCSS.

## Installation

::: code-group

```bash [pnpm]
pnpm add -D unocss @unocss/nuxt
```

```bash [yarn]
yarn add -D unocss @unocss/nuxt
```

```bash [npm]
npm install -D unocss @unocss/nuxt
```

```bash [bun]
bun add -D unocss @unocss/nuxt
```

:::

Add `@unocss/nuxt` to your Nuxt config file:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: [
    '@unocss/nuxt',
  ],
})
```

Create a `uno.config.ts` file:

```ts [uno.config.ts]
import { defineConfig } from 'unocss'

export default defineConfig({
  // ...UnoCSS options
})
```

The `uno.css` entry will be automatically injected by the module.

## Support status

|               | Nuxt 2 | Nuxt Bridge | Nuxt 3 |
| ------------- | :----- | :---------- | :----- |
| Webpack Dev   | ✅     | ✅          | 🚧     |
| Webpack Build | ✅     | ✅          | ✅     |
| Vite Dev      | -      | ✅          | ✅     |
| Vite Build    | -      | ✅          | ✅     |

## Configuration

We recommend to use the dedicated `uno.config.ts` file for configuration. See [Config File](/guide/config-file) for more details.

You can enable the `nuxtLayers` option, so Nuxt will automatically merge `uno.config` files from each Nuxt layer:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  // ...
  unocss: {
    nuxtLayers: true,
  },
})
```

then you can reexport the generated config in the root config file:

```ts [uno.config.ts]
import config from './.nuxt/uno.config.mjs'

export default config
```

or modify/extend it:

```ts
import { mergeConfigs } from '@unocss/core'
import config from './.nuxt/uno.config.mjs'

export default mergeConfigs([config, {
  // your overrides
}])
```

## License

* MIT License © 2021-PRESENT [Anthony Fu](https://github.com/antfu)

---

---
url: 'https://unocss.dev/integrations/postcss.md'
---

# PostCSS Plugin

PostCSS plugin for UnoCSS. Supports `@apply`, `@screen` and `theme()` directives.

[Source Code](https://github.com/unocss/unocss/tree/main/packages-integrations/postcss)

::: warning
This package is in an experimental state right now. It doesn't follow semver, and may introduce breaking changes in patch versions.
:::

## Install

::: code-group

```bash [pnpm]
pnpm add -D unocss @unocss/postcss
```

```bash [yarn]
yarn add -D unocss @unocss/postcss
```

```bash [npm]
npm install -D unocss @unocss/postcss
```

```bash [bun]
bun add -D unocss @unocss/postcss
```

:::

```ts [postcss.config.mjs]
import UnoCSS from '@unocss/postcss'

export default {
  plugins: [
    UnoCSS(),
  ],
}
```

```ts [uno.config.ts]
import { defineConfig, presetWind3 } from 'unocss'

export default defineConfig({
  content: {
    filesystem: [
      '**/*.{html,js,ts,jsx,tsx,vue,svelte,astro,marko}',
    ],
  },
  presets: [
    presetWind3(),
  ],
})
```

```css [style.css]
@unocss;
```

## Usage

### `@unocss`

`@unocss` at-rule is a placeholder. It will be replaced by the generated CSS.

You can also inject each layer individually:

```css [style.css]
@unocss preflights;
@unocss default;

/*
  Fallback layer. It's always recommended to include.
  Only unused layers will be injected here.
*/
@unocss;
```

If you want to include all layers no matter whether they are previously included or not, you can use `@unocss all`. This is useful if you want to include generated CSS in multiple files.

```css
@unocss all;
```

Or if you want to exclude a specific layer, you can use the `@unocss !<layer>` directive:

```css
@unocss !preflights, !<other-layer>;
```

### `@apply`

```css
.custom-div {
  @apply text-center my-0 font-medium;
}
```

Will be transformed to:

```css
.custom-div {
  margin-top: 0rem;
  margin-bottom: 0rem;
  text-align: center;
  font-weight: 500;
}
```

### `@screen`

The `@screen` directive allows you to create media queries that reference your breakpoints by name comes from [`theme.breakpoints`](https://github.com/unocss/unocss/blob/main/README.md#extend-theme).

```css
.grid {
  @apply grid grid-cols-2;
}
@screen xs {
  .grid {
    @apply grid-cols-1;
  }
}
@screen sm {
  .grid {
    @apply grid-cols-3;
  }
}
/* ... */
```

Will be transformed to:

```css
.grid {
  display: grid;
  grid-template-columns: repeat(2, minmax(0, 1fr));
}
@media (min-width: 320px) {
  .grid {
    grid-template-columns: repeat(1, minmax(0, 1fr));
  }
}
@media (min-width: 640px) {
  .grid {
    grid-template-columns: repeat(3, minmax(0, 1fr));
  }
}
/* ... */
```

#### Breakpoint Variant Support

`@screen` also supports `lt`、`at` variants

##### `@screen lt`

```css
.grid {
  @apply grid grid-cols-2;
}
@screen lt-xs {
  .grid {
    @apply grid-cols-1;
  }
}
@screen lt-sm {
  .grid {
    @apply grid-cols-3;
  }
}
/* ... */
```

Will be transformed to:

```css
.grid {
  display: grid;
  grid-template-columns: repeat(2, minmax(0, 1fr));
}
@media (max-width: 319.9px) {
  .grid {
    grid-template-columns: repeat(1, minmax(0, 1fr));
  }
}
@media (max-width: 639.9px) {
  .grid {
    grid-template-columns: repeat(3, minmax(0, 1fr));
  }
}
/* ... */
```

##### `@screen at`

```css
.grid {
  @apply grid grid-cols-2;
}
@screen at-xs {
  .grid {
    @apply grid-cols-1;
  }
}
@screen at-xl {
  .grid {
    @apply grid-cols-3;
  }
}
@screen at-xxl {
  .grid {
    @apply grid-cols-4;
  }
}
/* ... */
```

Will be transformed to:

```css
.grid {
  display: grid;
  grid-template-columns: repeat(2, minmax(0, 1fr));
}
@media (min-width: 320px) and (max-width: 639.9px) {
  .grid {
    grid-template-columns: repeat(1, minmax(0, 1fr));
  }
}
@media (min-width: 1280px) and (max-width: 1535.9px) {
  .grid {
    grid-template-columns: repeat(3, minmax(0, 1fr));
  }
}
@media (min-width: 1536px) {
  .grid {
    grid-template-columns: repeat(4, minmax(0, 1fr));
  }
}
/* ... */
```

### `theme()`

Use the `theme()` function to access your theme config values using dot notation.

```css
.btn-blue {
  background-color: theme('colors.blue.500');
}
```

Will be compiled to:

```css
.btn-blue {
  background-color: #3b82f6;
}
```

---

---
url: 'https://unocss.dev/integrations/svelte-scoped.md'
description: Svelte Scoped Vite Plugin and Svelte Preprocessor for UnoCSS.
---

# Svelte Scoped

Place generated CSS for each Svelte component's utility styles directly into the Svelte component's `<style>` block instead of in a global CSS file.

This component:

```svelte
<div class="mb-1" />
```

is transformed into:

```svelte
<div class="uno-ei382o" />

<style>
  :global(.uno-ei382o) {
    margin-bottom: 0.25rem;
  }
</style>
```

## When to use

| Use Case          |     | Description                                                                                                                                                 | Package to Use                                           |
| ----------------- | --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| Smaller apps      | :x: | Having 1 global CSS file is more convenient. Use the regular Vite plugin for [Svelte](/integrations/vite#svelte)/[SvelteKit](/integrations/vite#sveltekit). | [unocss/vite](/integrations/vite#svelte)                 |
| Larger apps       | ✅  | Svelte Scoped can help you avoid an ever-growing global CSS file.                                                                                           | [@unocss/svelte-scoped/vite](#vite-plugin)               |
| Component library | ✅  | Generated styles are placed directly in built components without the need to use UnoCSS in a consuming app's build pipeline.                                | [@unocss/svelte-scoped/preprocess](#svelte-preprocessor) |

## How it works

A regular UnoCSS/Tailwind CSS setup places utility styles in a global CSS file with proper ordering. In contrast, Svelte Scoped distributes your styles across many arbitrarily ordered Svelte component CSS files. However, it must keep the utility styles global to allow them to be context aware as needed for things like right-to-left and other [use cases](#context-aware) listed below. This presents a challenge that is solved by using Svelte's `:global()` wrapper to opt out of the default Svelte CSS hashing method and instead use a hash based on filename + class name(s) to compile unique class names that can be made global without style conflicts.

## Usage

Because Svelte Scoped rewrites your utility class names, you are limited in where you can write them:

| Supported Syntax          | Example                                                                                     |
| ------------------------- | ------------------------------------------------------------------------------------------- |
| Class attribute           | `<div class="mb-1" />`                                                                      |
| Class directive           | `<div class:mb-1={condition} />`                                                            |
| Class directive shorthand | `<div class:logo />`                                                                        |
| Class prop                | `<Button class="mb-1" />`                                                                   |
| `clsx` like               | `<div class={["mb-1", { logo, 'font-bold': isBold() }, isUnderlined() && 'underline' ]} />` |

Svelte Scoped is designed to be a drop-in replacement for a project that uses utility styles. As such, expressions found within class attributes are also supported (e.g. `<div class="mb-1 {foo ? 'mr-1' : 'mr-2'}" />`) but we recommend you use the `clsx` syntax moving forward. Note also that if you've used class names in other ways like placing them in a `<script>` block or using attributify mode then you'll need to take additional steps before using Svelte Scoped. You can utilize the `safelist` option and also check the [presets](#presets-support) section below for more tips.

### Context aware

Even though styles are distributed across your app's Svelte components, they are still global classes and will work in relationship to elements found outside of their specific components. Here are some examples:

#### Parent dependent

Classes that depend on attributes found in a parent component:

```svelte
<div class="dark:mb-2 rtl:right-0"></div>
```

turn into:

```svelte
<div class="uno-3hashz"></div>

<style>
  :global(.dark .uno-3hashz) {
    margin-bottom: 0.5rem;
  }
  :global([dir="rtl"] .uno-3hashz) {
    right: 0rem;
  }
</style>
```

#### Children influencing

You can add space between 3 children elements of which some are in separate components:

```svelte
<div class="space-x-1">
  <div>Status: online</div>
  <Button>FAQ</Button>
  <Button>Login</Button>
</div>
```

turns into:

```svelte
<div class="uno-7haszz">
  <div>Status: online</div>
  <Button>FAQ</Button>
  <Button>Login</Button>
</div>

<style>
  :global(.uno-7haszz > :not([hidden]) ~ :not([hidden])) {
    --un-space-x-reverse: 0;
    margin-left: calc(0.25rem * calc(1 - var(--un-space-x-reverse)));
    margin-right: calc(0.25rem * var(--un-space-x-reverse));
  }
</style>
```

#### Passing classes to child components

You can add a `class` prop to a component to allow passing custom classes wherever that component is consumed.

```svelte
<Button class="px-2 py-1">Login</Button>
```

turns into:

```svelte
<Button class="uno-4hshza">Login</Button>

<style>
  :global(.uno-4hshza) {
    padding-left:0.5rem;
    padding-right:0.5rem;
    padding-top:0.25rem;
    padding-bottom:0.25rem;
  }
</style>
```

An easy way to implement the class in a receiving component would be to place them on to an element using `{$$props.class}` as in `div class="{$$props.class} foo bar" />`.

### Apply directives

You can use apply directives inside your `<style>` blocks with either `--at-apply` or `@apply` or a custom value set using the `applyVariables` option.

Svelte Scoped even properly handles context dependent classes like `dark:text-white` that the regular [`@unocss/transformer-directives`](/transformers/directives) package can't handle properly because it wasn't built specifically for Svelte style blocks. For example, with Svelte Scoped this component:

```svelte
<div />

<style>
  div {
    --at-apply: rtl:ml-2;
  }
</style>
```

will be transformed into:

```svelte
<div />

<style>
  :global([dir=\\"rtl\\"]) div {
    margin-right: 0.5rem;
  }
</style>
```

In order for `rtl:ml-2` to work properly, the `[dir="rtl"]` selector is wrapped with `:global()` to keep the Svelte compiler from stripping it out automatically as the component has no element with that attribute. However, `div` can't be included in the `:global()` wrapper because that style would then affect every `div` in your app.

### Other style block directives

Using [theme()](https://unocss.dev/transformers/directives#theme) is also supported, but [@screen](https://unocss.dev/transformers/directives#screen) is **not**.

## Vite Plugin

In Svelte or SvelteKit apps, inject generated styles directly into your Svelte components, while placing the minimum necessary styles in a global stylesheet. Check out the [SvelteKit example](https://github.com/unocss/unocss/tree/main/examples/sveltekit-scoped) in Stackblitz:

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz_small.svg)](https://stackblitz.com/fork/github/unocss/unocss/tree/main/examples/sveltekit-scoped)

### Install

::: code-group

```bash [pnpm]
pnpm add -D unocss @unocss/svelte-scoped
```

```bash [yarn]
yarn add -D unocss @unocss/svelte-scoped
```

```bash [npm]
npm install -D unocss @unocss/svelte-scoped
```

```bash [bun]
bun add -D unocss @unocss/svelte-scoped
```

:::

#### Add plugin

Add `@unocss/svelte-scoped/vite` to your Vite config:

```ts [vite.config.ts]
import { sveltekit } from '@sveltejs/kit/vite'
import UnoCSS from '@unocss/svelte-scoped/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    UnoCSS({
      // injectReset: '@unocss/reset/normalize.css', // see type definition for all included reset options or how to pass in your own
      // ...other Svelte Scoped options
    }),
    sveltekit(),
  ],
})
```

#### Add config file

Setup your `uno.config.ts` file as described [below](#configuration).

#### Global styles

While almost all styles are placed into individual components, there are still a few that must be placed into a global stylesheet: preflights, safelist, and an optional reset (if you use the `injectReset` option).

Add the `%unocss-svelte-scoped.global%` placeholder into your `<head>` tag. In Svelte this is `index.html`. In SvelteKit this will be in `app.html` before `%sveltekit.head%`:

```html [index.html]
<head>
  <!-- ... -->
  <title>SvelteKit using UnoCSS Svelte Scoped</title>
  %unocss-svelte-scoped.global%
  %sveltekit.head%
</head>
```

## Svelte Preprocessor

Use utility styles to build a component library that is not dependent on including a companion CSS file by using a preprocessor to place generated styles directly into built components. Check out the [SvelteKit Library example](https://github.com/unocss/unocss/tree/main/examples/sveltekit-preprocess) in Stackblitz:

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz_small.svg)](https://stackblitz.com/fork/github/unocss/unocss/tree/main/examples/sveltekit-preprocess)

### Install

::: code-group

```bash [pnpm]
pnpm add -D unocss @unocss/svelte-scoped
```

```bash [yarn]
yarn add -D unocss @unocss/svelte-scoped
```

```bash [npm]
npm install -D unocss @unocss/svelte-scoped
```

```bash [bun]
bun add -D unocss @unocss/svelte-scoped
```

:::

#### Add preprocessor

Add `@unocss/svelte-scoped/preprocess` to your Svelte config:

```ts [svelte.config.js]
import adapter from '@sveltejs/adapter-auto'
import { vitePreprocess } from '@sveltejs/vite-plugin-svelte'
import UnoCSS from '@unocss/svelte-scoped/preprocess'

const config = {
  preprocess: [
    vitePreprocess(),
    UnoCSS({
      // ... preprocessor options
    }),
  ],
  // other Svelte config
}
```

#### Don't combine class names in development

When using Svelte Scoped in a normal app, the Vite plugin will automatically detect `dev` vs `build`. In development, classes will be kept distinct and hashed in place for ease of toggling on/off in your browser's developer tools. `class="mb-1 mr-1"` will turn into something like `class="_mb-1_9hwi32 _mr-1_84jfy4`. In production, these will be compiled into a single class name using your desired prefix, `uno-` by default, and a hash based on the filename + class names, e.g. `class="uno-84dke3`.

If you want this same behavior when using the preprocessor, you must manually set the the `combine` option based on environemnt. One way to do this is to install [cross-env](https://www.npmjs.com/package/cross-env) and update your dev script to this:

```json
{
  "dev": "cross-env NODE_ENV=development vite dev"
}
```

Then adjust your svelte.config.js:

```diff
+const prod = process.env.NODE_ENV !== 'development'
const config = {
  preprocess: [
    vitePreprocess(),
    UnoCSS({
+      combine: prod,
    }),
  ],
}
```

#### Add config file

Setup your `uno.config.ts` file as described [below](#configuration).

### Preflights

When using the preprocessor you have the option to include preflights in the specific component(s) where they are needed by adding `uno-preflights` as a style attribute.

```html
<style uno-preflights></style>
```

Any special preflights that start with a period, such as `.prose :where(a):not(:where(.not-prose, .not-prose *))`, will be wrapped with `:global()` to avoid being automatically stripped out by the Svelte compiler.

*Adding preflights into individual components is unnecessary if your classes do not depend on preflights or your built components are being consumed only in apps that already include preflights.*

### Safelist

When using the preprocessor you have the option to include safelist classes in a component by adding `uno-safelist` as a style attribute.

```html
<style uno-safelist></style>
```

Your safelist styles will be wrapped with `:global()` to avoid being automatically stripped out by the Svelte compiler.

## Configuration

Place your UnoCSS settings in an `uno.config.ts` file:

```ts [uno.config.ts]
import { defineConfig } from 'unocss'

export default defineConfig({
  // ...UnoCSS options
})
```

Extractors are not supported due to the differences in normal UnoCSS global usage and Svelte Scoped usage. Presets and Transformers are supported as described in the following sections. See [Config File](/guide/config-file) and [Config reference](/config/) for all other details.

### Presets support

Do to the nature of having a few necessary styles in a global stylesheet and everything else contained in each component where needed, presets need to be handled on a case-by-case basis:

| Preset                                                                                                                                                                                                                                                                                                                                                                      | Supported | Notes                                                                                                                                                                                                                                                                                                                                                                                                   |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ~~[@unocss/preset-uno](https://unocss.dev/presets/uno)~~, [@unocss/preset-mini](https://unocss.dev/presets/mini), [@unocss/preset-wind3](https://unocss.dev/presets/wind3), [@unocss/preset-icons](https://github.com/unocss/unocss/tree/main/packages-presets/preset-icons), [@unocss/web-fonts](https://github.com/unocss/unocss/tree/main/packages-presets/preset-icons) | ✅        | These and all community plugins, e.g. [unocss-preset-forms](https://github.com/Julien-R44/unocss-preset-forms), that only rely on rules/variants/preflights will work.                                                                                                                                                                                                                                  |
| [@unocss/preset-typography](https://github.com/unocss/unocss/tree/main/packages-presets/preset-typography)                                                                                                                                                                                                                                                                  | ✅        | Due to how this preset adds rulesets to your preflights you must add the `prose` class to your safelist when using this preset, otherwise the preflights will never be triggered. All other classes from this preset, e.g. `prose-pink`, can be component scoped.  After `v66.5.0`, `prose` styles refactored into a `rule`, which means you don't need to add the class to your safelist anymore. |
| [@unocss/preset-rem-to-px](https://github.com/unocss/unocss/tree/main/packages-presets/preset-rem-to-px)                                                                                                                                                                                                                                                                    | ✅        | This and all presets like it that only modify style output will work.                                                                                                                                                                                                                                                                                                                                   |
| [@unocss/preset-attributify](https://github.com/unocss/unocss/tree/main/packages-presets/preset-attributify)                                                                                                                                                                                                                                                                | -         | Preset won't work. Instead use [unplugin-attributify-to-class](https://github.com/MellowCo/unplugin-attributify-to-class) Vite plugin (`attributifyToClass({ include: [/\.svelte$/]})`) before the Svelte Scoped Vite plugin                                                                                                                                                                            |
| [@unocss/preset-tagify](https://github.com/unocss/unocss/tree/main/packages-presets/preset-tagify)                                                                                                                                                                                                                                                                          | -         | Presets that add custom extractors will not work. Create a preprocessor to convert `<text-red>Hi</text-red>` to `<span class="text-red">Hi</span>`, then create a PR to add the link here.                                                                                                                                                                                                              |

For other presets, if they don't rely on traditional `class="..."` usage you will need to first preprocess those class names into the `class="..."` attribute. If they add presets like typography's `.prose` class then you will need to place the classes which trigger the preset additions into your safelist.

### Transformers support

Transformers are supported for your CSS files (css|postcss|sass|scss|less|stylus|styl). To use them, add the transformer into the `cssFileTransformers` option in your `vite.config.ts`:

```ts [vite.config.ts]
import transformerDirectives from '@unocss/transformer-directives'

export default defineConfig({
  plugins: [
    UnoCSS({
      cssFileTransformers: [transformerDirectives()],
    }),
    sveltekit(),
  ],
})
```

::: info
Transformers are not supported in Svelte components due to how Svelte Scoped works.
:::

## Scoped utility classes unleash creativity

Some advice on when you might want to use scoped styles: If you have come to the point in a large project's life when every time you use a class like `.md:max-w-[50vw]` that you know is only used once you cringe as you feel the size of your global style sheet getting larger and larger, then give this package a try. Hesitancy to use exactly the class you need inhibits creativity. Sure, you could use `--at-apply: md:max-w-[50vw]` in the style block but that gets tedious and styles in context are useful. Furthermore, if you would like to include a great variety of icons in your project, you will begin to feel the weight of adding them to the global stylesheet. When each component bears the weight of its own styles and icons you can continue to expand your project without having to analyze the cost benefit of each new addition.

## License

* MIT License © 2022-PRESENT [Jacob Bowdoin](https://github.com/jacob-8)

---

---
url: 'https://unocss.dev/integrations/vite.md'
description: The Vite plugin for UnoCSS (@unocss/vite).
---

# Vite Plugin

The Vite plugin ships with the `unocss` package.

## Installation

::: code-group

```bash [pnpm]
pnpm add -D unocss
```

```bash [yarn]
yarn add -D unocss
```

```bash [npm]
npm install -D unocss
```

```bash [bun]
bun add -D unocss
```

:::

Install the plugin:

```ts [vite.config.ts]
import UnoCSS from 'unocss/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    UnoCSS(),
  ],
})
```

Create a `uno.config.ts` file:

```ts [uno.config.ts]
import { defineConfig } from 'unocss'

export default defineConfig({
  // ...UnoCSS options
})
```

Add `virtual:uno.css` to your main entry:

```ts [main.ts]
import 'virtual:uno.css'
```

## Modes

The Vite plugin comes with a set of modes that enable different behaviors.

### `global` (default)

This is the default mode for the plugin: in this mode you need to add the import of `uno.css` on your entry point.

This mode enables a set of Vite plugins for `build` and for `dev` with `HMR` support.

The generated `css` will be a global stylesheet injected on the `index.html`.

### `vue-scoped`

This mode will inject generated CSS to Vue SFCs `<style scoped>` for isolation.

### `svelte-scoped`

`svelte-scoped` mode has been moved to its own package, see [@unocss/svelte-scoped/vite](/integrations/svelte-scoped).

### `shadow-dom`

Since `Web Components` uses `Shadow DOM`, there is no way to style content directly from a global stylesheet (unless you use `CSS custom properties`, those will penetrate the `Shadow DOM`), you need to inline the generated CSS by the plugin into the `Shadow DOM` style.

To inline the generated CSS, you only need to configure the plugin mode to `shadow-dom` and include `@unocss-placeholder` magic placeholder on each web component style CSS block. If you are defining your Web Components in Vue SFCs and want to define custom styles alongside UnoCSS, you can wrap placeholder in a CSS comment to avoid syntax errors in your IDE.

### `per-module` (experimental)

This mode will generate a CSS sheet for each module, can be scoped.

### `dist-chunk` (experimental)

This mode will generate a CSS sheet for each code chunk on build, great for MPA.

## Edit classes in DevTools

Because of limitation of "on-demand" where the DevTools don't know those you haven't used in your source code yet. So if you want to try how things work by directly changing the classes in DevTools, just add the following lines to your main entry.

```ts
import 'uno.css'
import 'virtual:unocss-devtools'
```

::: warning
Please use it with caution, under the hood we use [`MutationObserver`](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver) to detect the class changes. Which means not only your manual changes but also the changes made by your scripts will be detected and included in the stylesheet. This could cause some misalignment between dev and the production build when you add dynamic classes based on some logic in script tags. We recommended adding your dynamic parts to the [safelist](https://github.com/unocss/unocss/issues/511) or setup UI regression tests for your production build if possible.
:::

## Frameworks

Some UI/App frameworks have some caveats that must be fixed to make it work, if you're using one of the following frameworks, just apply the suggestions.

### VanillaJS / TypeScript

When using VanillaJS or TypeScript, you need to add `js` and `ts` files extensions to allow UnoCSS read and parse the content, by default `js` and `ts` files are excluded, check out the [Extracting from Build Tools Pipeline](/guide/extracting#extracting-from-build-tools-pipeline) section.

### React

If you're using `@vitejs/plugin-react`:

```ts [vite.config.ts]
import React from '@vitejs/plugin-react'
import UnoCSS from 'unocss/vite'

export default {
  plugins: [
    React(),
    UnoCSS(),
  ],
}
```

If you're using `@unocss/preset-attributify` you should remove `tsc` from the `build` script.

If you are using `babel-plugin-react-compiler`, or `@vitejs/plugin-react` with `@unocss/preset-attributify`, you must add the plugin before `@vitejs/plugin-react`.

```ts [vite.config.ts]
import React from '@vitejs/plugin-react'
import UnoCSS from 'unocss/vite'

export default {
  plugins: [
    UnoCSS(),
    React(),
  ],
}
```

You have a `React` example project on [examples/vite-react](https://github.com/unocss/unocss/tree/main/examples/vite-react) directory using both plugins, check the scripts on `package.json` and its Vite configuration file.

### Preact

If you're using `@preact/preset-vite`:

```ts [vite.config.ts]
import Preact from '@preact/preset-vite'
import UnoCSS from 'unocss/vite'

export default {
  plugins: [
    UnoCSS(),
    Preact(),
  ],
}
```

or if you're using `@prefresh/vite`:

```ts [vite.config.ts]
import Prefresh from '@prefresh/vite'
import UnoCSS from 'unocss/vite'

export default {
  plugins: [
    UnoCSS(),
    Prefresh(),
  ],
}
```

If you're using `@unocss/preset-attributify` you should remove `tsc` from the `build` script.

You have a `Preact` example project on [examples/vite-preact](https://github.com/unocss/unocss/tree/main/examples/vite-preact) directory using both plugins, check the scripts on `package.json` and its Vite configuration file.

### Svelte

You must add the plugin before `@sveltejs/vite-plugin-svelte`.

To support `class:foo` and `class:foo={bar}` add the plugin and configure `extractorSvelte` on `extractors` option.

You can use simple rules with `class:`, for example `class:bg-red-500={foo}` or using `shortcuts` to include multiples rules, see `src/App.svelte` on linked example project below.

```ts [vite.config.ts]
import { svelte } from '@sveltejs/vite-plugin-svelte'
import extractorSvelte from '@unocss/extractor-svelte'
import UnoCSS from 'unocss/vite'

export default {
  plugins: [
    UnoCSS({
      extractors: [
        extractorSvelte(),
      ],
      /* more options */
    }),
    svelte(),
  ],
}
```

### Sveltekit

To support `class:foo` and `class:foo={bar}` add the plugin and configure `extractorSvelte` on `extractors` option.

You can use simple rules with `class:`, for example `class:bg-red-500={foo}` or using `shortcuts` to include multiples rules, see `src/routes/+layout.svelte` on linked example project below.

```ts [vite.config.ts]
import { sveltekit } from '@sveltejs/kit/vite'
import extractorSvelte from '@unocss/extractor-svelte'
import UnoCSS from 'unocss/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    UnoCSS({
      extractors: [
        extractorSvelte(),
      ],
      /* more options */
    }),
    sveltekit(),
  ],
})
```

### Web Components

To work with web components you need to enable `shadow-dom` mode on the plugin.

Don't forget to remove the import for `uno.css` since the `shadow-dom` mode will not expose it and the application will not work.

```ts [vite.config.ts]
import UnoCSS from 'unocss/vite'

export default {
  plugins: [
    UnoCSS({
      mode: 'shadow-dom',
      /* more options */
    }),
  ],
}
```

On each `web component` just add `@unocss-placeholder` to its style CSS block:

```ts
const template = document.createElement('template')
template.innerHTML = `
<style>
:host {...}
@unocss-placeholder
</style>
<div class="m-1em">
...
</div>
`
```

If you're using [Lit](https://lit.dev/):

```ts
@customElement('my-element')
export class MyElement extends LitElement {
  static styles = css`
    :host {...}
    @unocss-placeholder
  `
  // ...
}
```

You have a `Web Components` example project on [examples/vite-lit](https://github.com/unocss/unocss/tree/main/examples/vite-lit) directory.

#### `::part` built-in support

You can use `::part` since the plugin supports it via `shortcuts` and using `part-[<part-name>]:<rule|shortcut>` rule from `preset-mini`, for example using it with simple rules like `part-[<part-name>]:bg-green-500` or using some `shortcut`: check `src/my-element.ts` on linked example project below.

The `part-[<part-name>]:<rule|shortcut>` will work only with this plugin using the `shadow-dom` mode.

The plugin uses `nth-of-type` to avoid collisions with multiple parts in the same web component and for the same parts on distinct web components, you don't need to worry about it, the plugin will take care for you.

```ts [vite.config.ts]
import UnoCSS from 'unocss/vite'

export default {
  plugins: [
    UnoCSS({
      mode: 'shadow-dom',
      shortcuts: [
        { 'cool-blue': 'bg-blue-500 text-white' },
        { 'cool-green': 'bg-green-500 text-black' },
      ],
      /* more options */
    }),
  ],
}
```

then in your web components:

```ts
// my-container-wc.ts
const template = document.createElement('template')
template.innerHTML = `
<style>
@unocss-placeholder
</style>
<my-wc-with-parts class="part-[cool-part]:cool-blue part-[another-cool-part]:cool-green">...</my-wc-with-parts>
`
```

```ts
// my-wc-with-parts.ts
const template = document.createElement('template')
template.innerHTML = `
<style>
@unocss-placeholder
</style>
<div>
  <div part="cool-part">...</div>
  <div part="another-cool-part">...</div>
</div>
`
```

### Solid

You need to add the `vite-plugin-solid` plugin after UnoCSS's plugin.

```ts [vite.config.ts]
import UnoCSS from 'unocss/vite'
import solidPlugin from 'vite-plugin-solid'

export default {
  plugins: [
    UnoCSS({
      /* options */
    }),
    solidPlugin(),
  ],
}
```

### Elm

You need to add the `vite-plugin-elm` plugin before UnoCSS's plugin.

```ts [vite.config.ts]
import UnoCSS from 'unocss/vite'
import { defineConfig } from 'vite'
import Elm from 'vite-plugin-elm'

export default defineConfig({
  plugins: [
    Elm(),
    UnoCSS(),
  ],
})
```

### Marko

You need to add `@marko/vite` or `@marko/run/vite` before UnoCSS's plugin.

```ts [vite.config.ts]
import marko from '@marko/run/vite'
import UnoCSS from 'unocss/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    marko(),
    UnoCSS(),
  ],
})
```

## Legacy

If `@vitejs/plugin-legacy` with `renderModernChunks: false`, your need add it to `unocss` option

```ts
import legacy from '@vitejs/plugin-legacy'
import vue from '@vitejs/plugin-vue'
import { presetWind3 } from 'unocss'
import Unocss from 'unocss/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    vue(),
    Unocss({
      presets: [presetWind3()],
      legacy: {
        renderModernChunks: false,
      },
    }),
    legacy({
      targets: ['defaults', 'not IE 11'],
      renderModernChunks: false,
    }),
  ],
})
```

## License

* MIT License © 2021-PRESENT [Anthony Fu](https://github.com/antfu)

---

---
url: 'https://unocss.dev/integrations/vscode.md'
description: UnoCSS for VS Code.
---

# VS Code Extension

[Install in Marketplace](https://marketplace.visualstudio.com/items?itemName=antfu.unocss)

* Decoration and tooltip for matched utilities
* Auto loading configs
* Count of matched utilities

## Commands

| Command                         | Title                                           |
| ------------------------------- | ----------------------------------------------- |
| `unocss.reload`                 | UnoCSS: Reload UnoCSS                           |
| `unocss.insert-skip-annotation` | UnoCSS: Insert `@unocss-skip` for the selection |

## Configurations

| Key                             | Description                                              | Type           | Default    |
| ------------------------------- | -------------------------------------------------------- | -------------- | ---------- |
| `unocss.disable`                | Disable the UnoCSS extension                             | `boolean`      | `false`    |
| `unocss.languageIds`            |                                                          | `array`        | ``        |
| `unocss.root`                   | Project root that contains the UnoCSS configuration file | `array,string` |``         |
| `unocss.include`                | Directory of files to be detected                        | `array,string` | ``        |
| `unocss.exclude`                | Directory of files not to be detected                    | `array,string` |``         |
| `unocss.underline`              | Enable/disable underline decoration for class names      | `boolean`      | `true`     |
| `unocss.colorPreview`           | Enable/disable color preview decorations                 | `boolean`      | `true`     |
| `unocss.colorPreviewRadius`     | Radius for color preview                                 | `string`       | `"50%"`    |
| `unocss.remToPxPreview`         | Enable/disable rem to px preview in hover                | `boolean`      | `true`     |
| `unocss.remToPxRatio`           | Ratio of rem to px                                       | `number`       | `16`       |
| `unocss.selectionStyle`         | Enable/disable selection style decorations               | `boolean`      | `true`     |
| `unocss.strictAnnotationMatch`  | Be strict about where to show annotations                | `boolean`      | `false`    |
| `unocss.autocomplete.matchType` | The matching type for autocomplete                       | `string`       | `"prefix"` |
| `unocss.autocomplete.strict`    | Be strict about where to show autocomplete               | `boolean`      | `false`    |
| `unocss.autocomplete.maxItems`  | The maximum number of items to show in autocomplete      | `number`       | `1000`     |

## Config

To get the best IDE experience, we recommend you to [use a separate `uno.config.ts` file](/guide/config-file) for configuring your UnoCSS.

The extension will try to find the UnoCSS configurations under your project. When there is no config found, the extension will be disabled.

## Icons Preset

If you're using the [Icons Preset](/presets/icons), you can also install [Iconify IntelliSense](https://marketplace.visualstudio.com/items?itemName=antfu.iconify) to get inlay preview, auto-completion, and hover information for your icons.

---

---
url: 'https://unocss.dev/integrations/webpack.md'
description: The webpack plugin for UnoCSS (@unocss/webpack).
---

# Webpack Plugin

The webpack plugin for UnoCSS: `@unocss/webpack`. Currently, this plugin only supports the [`global` mode](https://github.com/unocss/unocss/blob/main/packages-integrations/vite/src/types.ts#L11-L21).

::: info
This plugin does not come with any default presets.
:::

## Prerequisite

`@unocss/webpack` requires `style-loader` and `css-loader` to handle CSS files.

## Installation

::: code-group

```bash [pnpm]
pnpm add -D @unocss/webpack
```

```bash [yarn]
yarn add -D @unocss/webpack
```

```bash [npm]
npm install -D @unocss/webpack
```

```bash [bun]
bun add -D @unocss/webpack
```

:::

From UnoCSS version `v0.59.0`, UnoCSS has been moved to ESM-only, you need to load your configuration via dynamic import:

::: code-group

```ts [webpack 5]
// webpack.config.js
module.exports = function () {
  return import('@unocss/webpack').then(({ default: UnoCSS }) => ({
    plugins: [
      UnoCSS()
    ],
    optimization: {
      realContentHash: true
    }
  }))
}
```

```js [webpack 4]
// webpack.config.js
module.exports = function () {
  return import('@unocss/webpack').then(({ default: UnoCSS }) => ({
    plugins: [
      UnoCSS()
    ],
    css: {
      extract: {
        filename: '[name].[hash:9].css'
      },
    },
  }))
}
```

:::

If you're using older version of UnoCSS, you can use the following code:

::: code-group

```ts [webpack 5]
// webpack.config.js
const UnoCSS = require('@unocss/webpack').default

module.exports = {
  plugins: [
    UnoCSS()
  ],
  optimization: {
    realContentHash: true
  }
}
```

```js [webpack 4]
// webpack.config.js
const UnoCSS = require('@unocss/webpack').default

module.exports = {
  plugins: [
    UnoCSS()
  ],
  css: {
    extract: {
      filename: '[name].[hash:9].css'
    }
  }
}
```

:::

Create a `uno.config.ts` file:

```ts [uno.config.ts]
import { defineConfig } from 'unocss'

export default defineConfig({
  // ...UnoCSS options
})
```

::: warning
If you are using webpack@4.x, the `optimization.realContentHash` configuration is not supported, And you should use `css.extract.filename` to customize CSS filename (we use first 9 letter of hashcode instead of contenthash as example). Beware this [known issue](https://github.com/unocss/unocss/issues/1728) with bundle and [webpack#9520](https://github.com/webpack/webpack/issues/9520#issuecomment-749534245).
:::

## Usage

Add `uno.css` to your main entry:

```ts [main.ts]
import 'uno.css'
```

## Frameworks

### Vue + Vue CLI

If you're using [Vue CLI](https://cli.vuejs.org/) with webpack 4/5 with UnoCSS `v0.59.0`, you need to use the latest [Vue CLI Service](https://cli.vuejs.org/guide/cli-service.html) `v5.0.8` to load your configuration with dynamic import:

::: code-group

```ts [webpack 5]
// vue.config.js
const process = require('node:process')

module.exports = function () {
  return import('@unocss/webpack').then(({ default: UnoCSS }) => ({
    configureWebpack: {
      devtool: 'inline-source-map',
      plugins: [
        UnoCSS()
      ],
      optimization: {
        realContentHash: true
      }
    },
    chainWebpack(config) {
      config.module.rule('vue').uses.delete('cache-loader')
      config.module.rule('tsx').uses.delete('cache-loader')
      config.merge({
        cache: false
      })
    },
    css: {
      extract: process.env.NODE_ENV === 'development'
        ? {
            filename: 'css/[name].css',
            chunkFilename: 'css/[name].css'
          }
        : true
    }
  }))
}
```

```ts [webpack 4]
// vue.config.js
const process = require('node:process')

module.exports = function () {
  return import('@unocss/webpack').then(({ default: UnoCSS }) => ({
    configureWebpack: {
      plugins: [
        UnoCSS({})
      ]
    },
    chainWebpack(config) {
      config.module.rule('vue').uses.delete('cache-loader')
      config.module.rule('tsx').uses.delete('cache-loader')
      config.merge({
        cache: false
      })
    },
    css: {
      extract: process.env.NODE_ENV === 'development'
        ? {
            filename: '[name].css',
            chunkFilename: '[name].[hash:9].css'
          }
        : true
    }
  }))
}
```

:::

If using an older version of UnoCSS, you can use the following code:

::: code-group

```ts [webpack 5]
// vue.config.js
const process = require('node:process')
const UnoCSS = require('@unocss/webpack').default

module.exports = {
  configureWebpack: {
    devtool: 'inline-source-map',
    plugins: [
      UnoCSS()
    ],
    optimization: {
      realContentHash: true
    }
  },
  chainWebpack(config) {
    config.module.rule('vue').uses.delete('cache-loader')
    config.module.rule('tsx').uses.delete('cache-loader')
    config.merge({
      cache: false
    })
  },
  css: {
    extract: process.env.NODE_ENV === 'development'
      ? {
          filename: 'css/[name].css',
          chunkFilename: 'css/[name].css'
        }
      : true
  },
}
```

```ts [webpack 4]
// vue.config.js
const process = require('node:process')
const UnoCSS = require('@unocss/webpack').default

module.exports = {
  configureWebpack: {
    plugins: [
      UnoCSS({}),
    ]
  },
  chainWebpack(config) {
    config.module.rule('vue').uses.delete('cache-loader')
    config.module.rule('tsx').uses.delete('cache-loader')
    config.merge({
      cache: false,
    })
  },
  css: {
    extract: process.env.NODE_ENV === 'development'
      ? {
          filename: '[name].css',
          chunkFilename: '[name].[hash:9].css',
        }
      : true,
  },
}
```

:::

---

---
url: 'https://unocss.dev/transformers/variant-group.md'
description: >-
  Enables the variant group feature of Windi CSS for UnoCSS
  (@unocss/transformer-variant-group)
---

# Variant group transformer

Enables the [variant group feature](https://windicss.org/features/variant-groups.html) of Windi CSS for UnoCSS.

## Installation

::: code-group

```bash [pnpm]
pnpm add -D @unocss/transformer-variant-group
```

```bash [yarn]
yarn add -D @unocss/transformer-variant-group
```

```bash [npm]
npm install -D @unocss/transformer-variant-group
```

```bash [bun]
bun add -D @unocss/transformer-variant-group
```

:::

```ts [uno.config.ts]
import transformerVariantGroup from '@unocss/transformer-variant-group'
import { defineConfig } from 'unocss'

export default defineConfig({
  // ...
  transformers: [
    transformerVariantGroup(),
  ],
})
```

::: tip
This preset is included in the `unocss` package, you can also import it from there:

```ts
import { transformerVariantGroup } from 'unocss'
```

:::

## Usage

```html
<div class="hover:(bg-gray-400 font-medium) font-(light mono)" />
```

Will be transformed to:

```html
<div class="hover:bg-gray-400 hover:font-medium font-light font-mono" />
```

## License

* MIT License © 2021-PRESENT [Anthony Fu](https://github.com/antfu)

---

---
url: 'https://unocss.dev/config/variants.md'
description: Variants allow you to apply some variations to your existing rules.
---

# Variants

[Variants](https://windicss.org/utilities/general/variants.html) allow you to apply some variations to your existing rules, like the `hover:` variant from Tailwind CSS.

## Example

```ts
variants: [
  // hover:
  (matcher) => {
    if (!matcher.startsWith('hover:'))
      return matcher
    return {
      // slice `hover:` prefix and passed to the next variants and rules
      matcher: matcher.slice(6),
      selector: s => `${s}:hover`,
    }
  },
],
rules: [
  [/^m-(\d)$/, ([, d]) => ({ margin: `${d / 4}rem` })],
]
```

* `matcher` controls when the variant is enabled. If the return value is a string, it will be used as the selector for matching the rules.
* `selector` provides the availability of customizing the generated CSS selector.

## Under the hood

Let's have a tour of what happened when matching for `hover:m-2`:

* `hover:m-2` is extracted from users usages
* `hover:m-2` send to all variants for matching
* `hover:m-2` is matched by our variant and returns `m-2`
* the result `m-2` will be used for the next round of variants matching
* if no other variant is matched, `m-2` will then goes to match the rules
* our first rule get matched and generates `.m-2 { margin: 0.5rem; }`
* finally, we apply our variants' transformation to the generated CSS. In this case, we prepended `:hover` to the `selector` hook

As a result, the following CSS will be generated:

```css
.hover\:m-2:hover { margin: 0.5rem; }
```

With this, we could have `m-2` applied only when users hover over the element.

## Going further

The variant system is very powerful and can't be covered fully in this guide, you can check [the default preset's implementation](https://github.com/unocss/unocss/tree/main/packages-presets/preset-mini/src/_variants) to see more advanced usages.

---

---
url: 'https://unocss.dev/presets/web-fonts.md'
description: Web fonts support for UnoCSS (@unocss/preset-web-fonts).
---

# Web Fonts preset

Use web fonts from [Google Fonts](https://fonts.google.com/), [FontShare](https://www.fontshare.com/) by simply providing the font names.

See [all supported providers](#providers).

[Source Code](https://github.com/unocss/unocss/tree/main/packages-presets/preset-web-fonts)

## Installation

::: code-group

```bash [pnpm]
pnpm add -D @unocss/preset-web-fonts
```

```bash [yarn]
yarn add -D @unocss/preset-web-fonts
```

```bash [npm]
npm install -D @unocss/preset-web-fonts
```

```bash [bun]
bun add -D @unocss/preset-web-fonts
```

:::

```ts [uno.config.ts]
import presetWebFonts from '@unocss/preset-web-fonts'
import presetWind3 from '@unocss/preset-wind3'
import { defineConfig } from 'unocss'

export default defineConfig({
  presets: [
    presetWind3(),
    presetWebFonts({ /* options */ }),
  ],
})
```

::: tip
This preset is included in the `unocss` package, you can also import it from there:

```ts
import { presetWebFonts } from 'unocss'
```

:::

## Providers

Currently supported Providers:

* `none` - do nothing, treat the font as system font
* `google` - [Google Fonts](https://fonts.google.com/)
* `bunny` - [Privacy-Friendly Google Fonts](https://fonts.bunny.net/)
* `fontshare` - [Quality Font Service by ITF](https://www.fontshare.com/)
* `fontsource` - [Self-Host Open Source Fonts in Neatly Bundled NPM Packages](https://fontsource.org/)
* `coollabs` - [A Privacy-Friendly Drop-In Replacement for Google Fonts](https://fonts.coollabs.io/)

::: info
PR welcome to add more providers. 🙌
:::

### Custom fetch function

Use your own function to fetch font source.

```ts [uno.config.ts]
import presetWebFonts from '@unocss/preset-web-fonts'
import presetWind3 from '@unocss/preset-wind3'
import axios from 'axios'
import ProxyAgent from 'proxy-agent'
import { defineConfig } from 'unocss'

export default defineConfig({
  presets: [
    presetWind3(),
    presetWebFonts({
      // use axios with an https proxy
      customFetch: (url: string) => axios.get(url, { httpsAgent: new ProxyAgent('https://localhost:7890') }).then(it => it.data),
      provider: 'google',
      fonts: {
        sans: 'Roboto',
        mono: ['Fira Code', 'Fira Mono:400,700'],
      },
    }),
  ],
})
```

## Options

### provider

* **Type:** `WebFontsProviders`
* **Default:** `google`

Provider service of the web fonts.

```ts
type WebFontsProviders = 'google' | 'bunny' | 'fontshare' | 'fontsource' | 'coollabs' | 'none'
```

### fonts

* **Type:** `Record<string, WebFontMeta | string | (WebFontMeta | string)[]>`

The fonts. See [example](#example) for more details.

```ts
interface WebFontMeta {
  name: string
  weights?: (string | number)[]
  italic?: boolean
  /**
   * Override the provider
   * @default <matches root config>
   */
  provider?: WebFontsProviders
}
```

### extendTheme

* **Type:** `boolean`
* **Default:** `true`

Extend the theme object.

### themeKey

* **Type:** `string`
* **Default:** `fontFamily`

Key for the theme object.

### inlineImports

* **Type:** `boolean`
* **Default:** `true`

Inline CSS `@import()`.

### customFetch

* **Type:** `(url: string) => Promise<string>`
* **Default:** `undefined`

Use your own function to fetch font source. See [Custom fetch function](#custom-fetch-function).

## Example

```ts
presetWebFonts({
  provider: 'google', // default provider
  fonts: {
    // these will extend the default theme
    sans: 'Roboto',
    mono: ['Fira Code', 'Fira Mono:400,700'],
    // custom ones
    lobster: 'Lobster',
    lato: [
      {
        name: 'Lato',
        weights: ['400', '700'],
        italic: true,
      },
      {
        name: 'sans-serif',
        provider: 'none',
      },
    ],
  },
})
```

The following CSS will be generated automatically:

```css
@import url('https://fonts.googleapis.com/css2?family=Roboto&family=Fira+Code&family=Fira+Mono:wght@400;700&family=Lobster&family=Lato:ital,wght@0,400;0,700;1,400;1,700&display=swap');

/* layer: default */
.font-lato {
  font-family: "Lato", sans-serif;
}
.font-lobster {
  font-family: "Lobster";
}
.font-mono {
  font-family: "Fira Code", "Fira Mono", ui-monospace, SFMono-Regular, Menlo,
    Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
}
.font-sans {
  font-family: "Roboto", ui-sans-serif, system-ui, -apple-system,
    BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans",
    sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol",
    "Noto Color Emoji";
}
```

## Serve Fonts Locally

By default the preset will fetch the fonts from the provider's CDN. If you want to serve the fonts locally, you can download the fonts and serve them from your own server using the processor from `@unocss/preset-web-fonts/local`.

```ts
import presetWebFonts from '@unocss/preset-web-fonts'
import { createLocalFontProcessor } from '@unocss/preset-web-fonts/local'
import { defineConfig } from 'unocss'

export default defineConfig({
  presets: [
    presetWebFonts({
      provider: 'none',
      fonts: {
        sans: 'Roboto',
        mono: 'Fira Code',
      },
      // This will download the fonts and serve them locally
      processors: createLocalFontProcessor({
        // Directory to cache the fonts
        cacheDir: 'node_modules/.cache/unocss/fonts',

        // Directory to save the fonts assets
        fontAssetsDir: 'public/assets/fonts',

        // Base URL to serve the fonts from the client
        fontServeBaseUrl: '/assets/fonts',

        // Custom fetch function to download the fonts
        fetch: async url => axios.get(url)
      })
    }),
  ],
})
```

This will download the fonts assets to `public/assets/fonts` and serve them from `/assets/fonts` on the client. When doing this, please make sure the license of the fonts allows you to redistribute so, the tool is not responsible for any legal issues.

::: info

This feature is Node.js specific and will not work in the browser.

:::

---

---
url: 'https://unocss.dev/guide/why.md'
---

# Why UnoCSS?

## Motivations

We recommend you to read the blog post [Reimagine Atomic CSS](https://antfu.me/posts/reimagine-atomic-css) written by the creator of UnoCSS, [Anthony Fu](https://antfu.me/), to get a better understanding of the motivation behind UnoCSS.

## How is UnoCSS Different from X?

### Windi CSS

UnoCSS was started by one of the [Windi CSS](https://windicss.org/)'s team members, with a lot of inspiration taken from the work we did in Windi CSS. While Windi CSS is no longer actively maintained (as of March 2023), you may consider UnoCSS as a *"spiritual successor"* of Windi CSS.

UnoCSS inherits Windi CSS's on-demand nature, [attributify mode](/presets/attributify), [shortcuts](/config/shortcuts), [variant groups](/transformers/variant-group), [compilation mode](/transformers/compile-class) and a lot more. On top of that, UnoCSS is built from the ground up with the maximum extensibility and performance in mind, making us able to introduce new features like [pure CSS icons](/presets/icons), [valueless attributify](/presets/attributify#valueless-attributify), [tagify](/presets/tagify), [web fonts](/presets/web-fonts), etc.

Most importantly, UnoCSS is extracted as an atomic CSS engine, where all the features are optional, and making it easy to create your own conventions, own design system, and own presets - with the combinations of the features you want.

### Tailwind CSS

Both Windi CSS and UnoCSS took a lot of inspiration from [Tailwind CSS](https://tailwindcss.com/). Since UnoCSS is built from the ground up, we are able to have a great overview of how atomic CSS has been designed with prior arts and abstracted into an elegant and powerful API. With quite different design goals, it's not really an apples-to-apples comparison with Tailwind CSS. But we will try to list a few differences.

Tailwind CSS is a PostCSS plugin, while UnoCSS is an isomorphic engine with a collection of first-class integrations with build tools (including a [PostCSS plugin](/integrations/postcss)). This means UnoCSS can be much more flexible to be used in different places (for example, [CDN Runtime](/integrations/runtime), which generates CSS on the fly) and have deep integrations with build tools to provide better HMR, performance, and developer experience (for example, the [Inspector](/tools/inspector)).

Technical trade-offs aside, UnoCSS is also designed to be fully extensible and customizable, while Tailwind CSS is more opinionated. Building a custom design system (or design tokens) on top of Tailwind CSS can be hard, and you can't really move away from the Tailwind CSS's conventions. With UnoCSS, you can build pretty much anything you want with full control. For example, we implemented the whole Tailwind CSS compatible utilities within [a single preset](/presets/wind3), and there are a lot of [awesome community presets](/presets/community) implemented with other interesting philosophies.

Thanks to the flexibility UnoCSS provides, we are able to experiment with a lot of innovative features on top of it, for example:

* [Pure CSS icons](/presets/icons)
* [Attributify Mode](/presets/attributify)
* [Variant Groups](/transformers/variant-group)
* [Shortcuts](/config/shortcuts)
* [Tagify](/presets/tagify)
* [Web fonts](/presets/web-fonts)
* [CDN Runtime](/integrations/runtime)
* [Inspector](/tools/inspector)

Due to the differing design goals over Tailwind CSS, UnoCSS does not support Tailwind CSS's plugin system or configurations, meaning it might make it harder to migrate from a heavily customized Tailwind CSS project. This is the intended decision to make UnoCSS high-performant and extensible, and we believe the trade-off is worth it.

---

---
url: 'https://unocss.dev/presets/wind3.md'
description: The Tailwind CSS / Windi CSS compact preset for UnoCSS (@unocss/preset-wind3).
---

# Wind3 preset

The Tailwind CSS / Windi CSS compact preset for UnoCSS.

[Source Code](https://github.com/unocss/unocss/tree/main/packages-presets/preset-wind3)

::: info
`@unocss/preset-wind` and `@unocss/preset-uno` are deprecated and renamed to `@unocss/preset-wind3`. This preset inherits from [`@unocss/preset-mini`](/presets/mini).
:::

## Installation

::: code-group

```bash [pnpm]
pnpm add -D @unocss/preset-wind3
```

```bash [yarn]
yarn add -D @unocss/preset-wind3
```

```bash [npm]
npm install -D @unocss/preset-wind3
```

```bash [bun]
bun add -D @unocss/preset-wind3
```

:::

```ts [uno.config.ts]
import presetWind3 from '@unocss/preset-wind3'
import { defineConfig } from 'unocss'

export default defineConfig({
  presets: [
    presetWind3(),
  ],
})
```

::: tip
This preset is included in the `unocss` package, you can also import it from there:

```ts
import { presetWind3 } from 'unocss'
```

:::

## Rules

The primary goal of this preset is to provide compatibility with [Tailwind CSS](https://tailwindcss.com/) and [Windi CSS](https://windicss.org/). It should be noted that complete compatibility may not be guaranteed. Please refer to their [documentation](https://tailwindcss.com/docs) for detailed usage.

For all rules and presets included in this preset, please refer to our interactive docs or directly go to the [source code](https://github.com/unocss/unocss/tree/main/packages-presets/preset-wind3).

## Features

### Dark mode

By default, this preset generates class-based dark mode with `dark:` variant.

```html
<div class="dark:bg-red:10" />
```

will generate:

```css
.dark .dark\:bg-red\:10 {
  background-color: rgb(248 113 113 / 0.1);
}
```

#### Media query based dark mode

To instead use media query based dark mode globally you can change the config for the `dark:` variant:

```ts
presetWind3({
  dark: 'media'
})
```

Now

```html
<div class="dark:bg-red:10" />
```

will generate:

```css
@media (prefers-color-scheme: dark) {
  .dark\:bg-red\:10 {
    background-color: rgb(248 113 113 / 0.1);
  }
}
```

#### Opt-in media query based dark mode

To use opt-in media query based dark mode, you can use the `@dark:` variant:

```html
<div class="@dark:bg-red:10" />
```

```css
@media (prefers-color-scheme: dark) {
  .\@dark\:bg-red\:10 {
    background-color: rgb(248 113 113 / 0.1);
  }
}
```

## Differences from Tailwind CSS

### Quotes

Using quotes in the template (the files intended to be processed) is not supported due to how the extractor works. E.g. you won't be able to write `before:content-['']`. For these cases, you may prefer to introduce a new utility that you can explicitly set such as `class="before:content-empty"`.

### background-position with arbitrary values

Tailwind [allows](https://tailwindcss.com/docs/background-position#using-custom-values) one to use custom values for `background-position` using the bare syntax:

```html
<div class="bg-[center_top_1rem]"></div>
```

The Wind preset will instead interpret `center_top_1rem` as a color. Use a `position:` prefix to accomplish the same thing:

```html
<div class="bg-[position:center_top_1rem]"></div>
```

### Animates

Tailwind CSS has fewer built-in animations, we fully support its animation rules, and internally integrate [Animate.css](https://github.com/animate-css/animate.css) to provide more animation effects.

You can use the `animate-` prefix to guide IntelliSense to find the animation you need quickly.

:::tip
We don't merge conflicting animation names from Tailwind and Animate.css. If you need to use the animation name from Animate.css, please use `animate-<name>-alt`.
:::

For example

|                                                                                                                                         Tailwind CSS                                                                                                                                          |                                                                                                                                            Animate.css                                                                                                                                            |
| :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
|                                                                                                                                       `animate-bounce`                                                                                                                                        |                                                                                                                                       `animate-bounce-alt`                                                                                                                                        |
|  |  |

If you want to customize or modify the animation effect, we provide highly customizable configuration items. You can modify the duration, delay, speed curve, etc. of the animation through the configuration item.

```ts [uno.config.ts]
export default defineConfig({
  theme: {
    animation: {
      keyframes: {
        custom: '{0%, 100% { transform: scale(0.5); } 50% { transform: scale(1); }}',
      },
      durations: {
        custom: '1s',
      },
      timingFns: {
        custom: 'cubic-bezier(0.4,0,.6,1)',
      },
      properties: {
        custom: { 'transform-origin': 'center' },
      },
      counts: {
        custom: 'infinite',
      },
    }
  }
})
```

Preview the custom animation:

:::tip
You can also add `category` to group animations for better management. This will make it easier for downstream tools to consume animation effects.

```ts [uno.config.ts] {9}
export default defineConfig({
  theme: {
    animation: {
      keyframes: {
        custom: '{0%, 100% { transform: scale(0.5); } 50% { transform: scale(1); }}',
      },
      // ...
      category: {
        custom: 'Zooming',
      },
    }
  }
})
```

:::

## Differences from Windi CSS

### Breakpoints

| Windi CSS | UnoCSS      |
| :-------- | :---------- |
| `<sm:p-1` | `lt-sm:p-1` |
| `@lg:p-1` | `at-lg:p-1` |
| `>xl:p-1` | `xl:p-1`    |

### Bracket syntax spaces

This preset uses `_` instead of `,` to respect space in bracket syntax.

| Windi CSS                          | UnoCSS                             |
| :--------------------------------- | :--------------------------------- |
| `grid-cols-[1fr,10px,max-content]` | `grid-cols-[1fr_10px_max-content]` |

Since some CSS rules require `,` as parts of the value, e.g. `grid-cols-[repeat(3,auto)]`

## Experimental Features

::: warning
This preset includes experimental features that may be changed in breaking ways at any time.
:::

### Media Hover

Media hover addresses the [sticky hover](https://css-tricks.com/solving-sticky-hover-states-with-media-hover-hover/) problem where tapping target that includes hover style on mobile will persist that hover style until tapping elsewhere.

Since the regular `:hover` style most probably used so widely, the variant uses `@hover` syntax to distinguish it from the regular `hover` pseudo.

The variant `@hover-text-red` will output:

```css
@media (hover: hover) and (pointer: fine) {
  .\@hover-text-red:hover {
    --un-text-opacity: 1;
    color: rgb(248 113 113 / var(--un-text-opacity));
  }
}
```

## Options

::: info
This preset options are inherited from [`@unocss/preset-mini`](/presets/mini#options).
:::

### important

* **Type:** `boolean | string`
* **Default:** `false`

The `important` option lets you control whether UnoCSS's utilities should be marked with `!important`. This can be really useful when using UnoCSS with existing CSS that has high specificity selectors.

::: warning
Using this option will apply important to all utilities generated by UnoCSS. You can use `important:` variant instead if you mean to apply it to specific utilities only.
:::

However, setting `important` to `true` can introduce some issues when incorporating third-party JS libraries that add inline styles to your elements. In those cases, UnoCSS's `!important` utilities defeat the inline styles, which can break your intended design.

To get around this, you can set important to an ID selector like `#app` instead:

```ts [uno.config.ts]
import presetWind3 from '@unocss/preset-wind'
import { defineConfig } from 'unocss'

export default defineConfig({
  presets: [
    presetWind3({
      important: '#app',
    }),
  ],
})
```

This configuration will prefix all of your utilities with the given selector, effectively increasing their specificity without actually making them `!important`.

The utility `dark:bg-blue` will output:

```css
#app :is(.dark .dark\:bg-blue) {
  --un-bg-opacity: 1;
  background-color: rgb(96 165 250 / var(--un-bg-opacity));
}
```

---

---
url: 'https://unocss.dev/presets/wind4.md'
description: The Tailwind4 CSS compact preset for UnoCSS (@unocss/preset-wind4).
---

# Wind4 preset

The Tailwind4 CSS compact preset for UnoCSS. It's compatible with all features of PresetWind3 and enhances it further.

[Source Code](https://github.com/unocss/unocss/tree/main/packages-presets/preset-wind4)

::: tip
You can spend a little time reading this document to understand the changes
:::

## Installation

::: code-group

```bash [pnpm]
pnpm add -D @unocss/preset-wind4
```

```bash [yarn]
yarn add -D @unocss/preset-wind4
```

```bash [npm]
npm install -D @unocss/preset-wind4
```

```bash [bun]
bun add -D @unocss/preset-wind4
```

:::

```ts twoslash [uno.config.ts]
import { defineConfig, presetWind4 } from 'unocss'

export default defineConfig({
  presets: [
    presetWind4(),
    //  ^?
  ],
})
```

## Compatibility

Refer to [Tailwind Compatibility](https://tailwindcss.com/docs/compatibility) to learn about browser support and compatibility.

## Theme

`PresetWind4`'s theme is almost identical to `PresetWind3`'s theme, but some theme keys have been adjusted.

::: warning
Please note when switching to PresetWind4, refer to the table below to check your theme key configuration and make appropriate adjustments.
:::

|                                            PresetWind3                                            |                          PresetWind4                          |
| :-----------------------------------------------------------------------------------------------: | :-----------------------------------------------------------: |
|                                           `fontFamily`                                            |                            `font`                             |
|                                            `fontSize`                                             |            Moved to `fontSize` property in `text`             |
|                                           `lineHeight`                                            |   Moved to `lineHeight` property in `text` or use `leading`   |
|                                          `letterSpacing`                                          | Moved to `letterSpacing` property in `text` or use `tracking` |
|                                          `borderRadius`                                           |                           `radius`                            |
|                                             `easing`                                              |                            `ease`                             |
|                                           `breakpoints`                                           |                         `breakpoint`                          |
|                                       `verticalBreakpoints`                                       |                     `verticalBreakpoint`                      |
|                                            `boxShadow`                                            |                           `shadow`                            |
|                                                 -                                                 |                         `insetShadow`                         |
|     Size properties like `width`, `height`, `maxWidth`, `maxHeight`, `minWidth`, `minHeight`      |                   Unified to use `spacing`                    |
|                                       `transitionProperty`                                        |                          `property`                           |
| `gridAutoColumn`, `gridAutoRow`, `gridColumn`, `gridRow`, `gridTemplateColumn`, `gridTemplateRow` |                               -                               |
|                                       `container.maxWidth`                                        |                     `containers.maxWidth`                     |
|                                                 -                                                 |                          `defaults`                           |

### `Theme.defaults`

`Theme.defaults` is a global default theme configuration that will be applied to `reset` styles or used as default values for certain rules.

Below are the default values for `Theme.defaults`, which you can override in your theme configuration.

```ts twoslash [uno.config.ts]
import type { Theme } from '@unocss/preset-wind4/theme'

export const defaults: Theme['default'] = {
  transition: {
    duration: '150ms',
    timingFunction: 'cubic-bezier(0.4, 0, 0.2, 1)',
  },
  font: {
    family: 'var(--font-sans)',
    featureSettings: 'var(--font-sans--font-feature-settings)',
    variationSettings: 'var(--font-sans--font-variation-settings)',
  },
  monoFont: {
    family: 'var(--font-mono)',
    featureSettings: 'var(--font-mono--font-feature-settings)',
    variationSettings: 'var(--font-mono--font-variation-settings)',
  },
}
```

## Options

PresetWind4's basic configuration is similar to [PresetWind3](/presets/wind3#options), with the following important changes.

### Preflights

We have added the `preflights` configuration option in `PresetWind4` to control whether to enable preset styles.

#### Reset

In PresetWind4, we align the reset styles with tailwind4 and integrate them internally. You don't need to install any additional CSS reset package like `@unocss/reset` or `normalize.css`.

```ts [main.ts]
import '@unocss/reset/tailwind.css' // [!code --]
import '@unocss/reset/tailwind-compat.css' // [!code --]
```

You only need to control whether to enable reset styles through a switch:

```ts twoslash [uno.config.ts]
import { defineConfig, presetWind4 } from 'unocss'

export default defineConfig({
  presets: [
    presetWind4({
      preflights: { // [!code ++]
        reset: true, // [!code ++]
      } // [!code ++]
    }),
  ],
})
```

#### Theme

Choose how to generate theme CSS variables.

##### Mode

The UnoCSS engine with `presetWind4` installed will automatically collect dependencies on the theme when parsing utilities and generate CSS variables at the end.

* `true`: Generate theme keys fully.
* `false`: Disable theme keys. (Not recommended ⚠️)
* `'on-demand'`: Generate theme keys only when used. -> ✅ **(By default)**

```ts twoslash [uno.config.ts]
import { defineConfig, presetWind4 } from 'unocss'

export default defineConfig({
  presets: [
    presetWind4({
      preflights: { // [!code ++]
        theme: true, // [!code ++]
      }, // [!code ++]
    }),
  ],
})
```

##### Process

And you can further control the output of your theme variables. For example, if you want to convert `rem` to `px` for theme variables, we provide the `createRemToPxProcessor` function to process your theme variables.

```ts twoslash [uno.config.ts]
import { createRemToPxProcessor } from '@unocss/preset-wind4/utils' // [!code ++]
import { defineConfig, presetWind4 } from 'unocss'

export default defineConfig({
  presets: [
    presetWind4({
      preflights: { // [!code ++]
        theme: { // [!code ++]
          mode: 'on-demand', // Default by 'on-demand' // [!code ++]
          process: createRemToPxProcessor(), // [!code ++]
        } // [!code ++]
      }, // [!code ++]
    }),
  ],
})
```

By the way, if you want to use the `presetRemToPx` preset to convert `rem` to `px`, you no longer need to import this preset separately as `presetWind4` provides this functionality internally.

```ts twoslash [uno.config.ts]
import { createRemToPxProcessor } from '@unocss/preset-wind4/utils' // [!code ++]
import { defineConfig, presetWind4 } from 'unocss'

export default defineConfig({
  presets: [
    presetWind4({
      preflights: { // [!code ++]
        theme: { // [!code ++]
          process: createRemToPxProcessor(), // [!code ++]
        } // [!code ++]
      }, // [!code ++]
    }),
  ],
  postprocess: [createRemToPxProcessor()], // [!code ++]
})
```

#### Property

Control the generation of `@property` CSS rules in the `properties` layer.

By default, PresetWind4 uses `@property` to define CSS custom properties for better browser optimization. These properties are automatically generated based on your utilities usage and wrapped in a `@supports` query for progressive enhancement.

```ts twoslash [uno.config.ts]
import { defineConfig, presetWind4 } from 'unocss'

export default defineConfig({
  presets: [
    presetWind4({
      preflights: {
        property: true, // Enable (default) | `false` to disable [!code ++]
      },
    }),
  ],
})
```

##### Parent and Selector

You can customize the parent wrapper and selector:

```ts twoslash [uno.config.ts]
import { defineConfig, presetWind4 } from 'unocss'

export default defineConfig({
  presets: [
    presetWind4({
      preflights: {
        property: {
          // Custom parent selector (e.g., use @layer instead of @supports)
          parent: '@layer custom-properties',
          // Custom selector for applying properties
          selector: ':where(*, ::before, ::after)',
        },
      },
    }),
  ],
})
```

If you don't want the `@supports` wrapper and want properties applied directly:

```ts twoslash [uno.config.ts]
import { defineConfig, presetWind4 } from 'unocss'

export default defineConfig({
  presets: [
    presetWind4({
      preflights: {
        property: {
          parent: false, // No parent wrapper
        },
      },
    }),
  ],
})
```

**Default output:**

```css
@supports ((-webkit-hyphens: none) and (not (margin-trim: inline))) or
  ((-moz-orient: inline) and (not (color: rgb(from red r g b)))) {
  *,
  ::before,
  ::after,
  ::backdrop {
    --un-text-opacity: 100%;
    /* ... */
  }
}
```

**With `parent: false`:**

```css
*,
::before,
::after,
::backdrop {
  --un-text-opacity: 100%;
  /* ... */
}
```

## Generated CSS

In the output of PresetWind4, three new layers have been added: `base`, `theme`, and `properties`.

|  Layer Name  |              Description              | order |
| :----------: | :-----------------------------------: | :---: |
| `properties` | CSS properties defined by `@property` | -200  |
|   `theme`    |      Theme-related CSS variables      | -150  |
|    `base`    |      Base preflight/reset styles      | -100  |

### `properties` Layer

We have used `@property` to define CSS properties in many rules to achieve better performance and smaller size.

For example, commonly used utilities like `text-op-xx`, `bg-op-xx`, and so on.

```css
@property --un-text-opacity {
  syntax: '<percentage>';
  inherits: false;
  initial-value: 100%;
}
```

### `theme` Layer

We've placed theme-related CSS variables in the `theme` layer to make it easier for you to override and use directly.
It can be comprehensive or on-demand. It always comes from your theme configuration.

::: info
The generated key names may not be exactly the same as `Tailwind4`. We try to avoid making significant changes to the key names in the theme to respect users migrating from `presetWind3`.
You can also customize the output you want in the [Preflights Theme Process](#process).
:::

```css
:root,
:host {
  --spacing: 0.25rem;
  --font-sans: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial,
    'Noto Sans', sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji';
  --font-serif: ui-serif, Georgia, Cambria, 'Times New Roman', Times, serif;
  --font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier New', monospace;
  --colors-black: #000;
  --colors-white: #fff;
  /* ... */
}
```

## Compatibility with Other Presets

`PresetWind4` enhances and is compatible with `PresetWind3`. Since other packages were originally developed for `PresetWind3`, some issues may arise when using them together. Known issues include:

### presetRemToPx

`presetRemToPx` is no longer needed in `PresetWind4` as it is already included internally. You can remove it from your configuration.

Refer to the [`process`](#process) option in Options.

### presetLegacyCompat

In `presetWind4`, we use the `oklch` color model to support better color contrast and color perception. Therefore, it is not compatible with `presetLegacyCompat` and is **not recommended** for use together.

Please refer to the [Compatibility](#compatibility) section for more information.