---
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"
      },
    },
  }
}
```