1---
2name: unocss-theme
3description: Theming system for colors, breakpoints, and design tokens
4---
5 
6# UnoCSS Theme
7 
8UnoCSS supports theming similar to Tailwind CSS / Windi CSS. The `theme` property is deep-merged with the default theme.
9 
10## Basic Usage
11 
12```ts
13theme: {
14  colors: {
15    veryCool: '#0000ff', // class="text-very-cool"
16    brand: {
17      primary: 'hsl(var(--hue, 217) 78% 51%)', // class="bg-brand-primary"
18      DEFAULT: '#942192' // class="bg-brand"
19    },
20  },
21}
22```
23 
24## Using Theme in Rules
25 
26Access theme values in dynamic rules:
27 
28```ts
29rules: [
30  [/^text-(.*)$/, ([, c], { theme }) => {
31    if (theme.colors[c])
32      return { color: theme.colors[c] }
33  }],
34]
35```
36 
37## Using Theme in Variants
38 
39```ts
40variants: [
41  {
42    name: 'variant-name',
43    match(matcher, { theme }) {
44      // Access theme.breakpoints, theme.colors, etc.
45    },
46  },
47]
48```
49 
50## Using Theme in Shortcuts
51 
52```ts
53shortcuts: [
54  [/^badge-(.*)$/, ([, c], { theme }) => {
55    if (Object.keys(theme.colors).includes(c))
56      return `bg-${c}4:10 text-${c}5 rounded`
57  }],
58]
59```
60 
61## Breakpoints
62 
63**Warning:** Custom `breakpoints` object **overrides** the default, not merges.
64 
65```ts
66theme: {
67  breakpoints: {
68    sm: '320px',
69    md: '640px',
70  },
71}
72```
73 
74Only `sm:` and `md:` variants will be available.
75 
76### Inherit Default Breakpoints
77 
78Use `extendTheme` to merge with defaults:
79 
80```ts
81extendTheme: (theme) => {
82  return {
83    ...theme,
84    breakpoints: {
85      ...theme.breakpoints,
86      sm: '320px',
87      md: '640px',
88    },
89  }
90}
91```
92 
93**Note:** `verticalBreakpoints` works the same for vertical layout.
94 
95### Breakpoint Sorting
96 
97Breakpoints are sorted by size. Use consistent units to avoid errors:
98 
99```ts
100theme: {
101  breakpoints: {
102    sm: '320px',
103    // Don't mix units - convert rem to px
104    // md: '40rem', // Bad
105    md: `${40 * 16}px`, // Good
106    lg: '960px',
107  },
108}
109```
110 
111## ExtendTheme
112 
113`extendTheme` lets you modify the merged theme object:
114 
115### Mutate Theme
116 
117```ts
118extendTheme: (theme) => {
119  theme.colors.veryCool = '#0000ff'
120  theme.colors.brand = {
121    primary: 'hsl(var(--hue, 217) 78% 51%)',
122  }
123}
124```
125 
126### Replace Theme
127 
128Return a new object to completely replace:
129 
130```ts
131extendTheme: (theme) => {
132  return {
133    ...theme,
134    colors: {
135      ...theme.colors,
136      veryCool: '#0000ff',
137    },
138  }
139}
140```
141 
142## Theme Differences in Presets
143 
144### preset-wind3 vs preset-wind4
145 
146| preset-wind3 | preset-wind4 |
147|--------------|--------------|
148| `fontFamily` | `font` |
149| `fontSize` | `text.fontSize` |
150| `lineHeight` | `text.lineHeight` or `leading` |
151| `letterSpacing` | `text.letterSpacing` or `tracking` |
152| `borderRadius` | `radius` |
153| `easing` | `ease` |
154| `breakpoints` | `breakpoint` |
155| `boxShadow` | `shadow` |
156| `transitionProperty` | `property` |
157 
158## Common Theme Keys
159 
160- `colors` - Color palette
161- `breakpoints` - Responsive breakpoints
162- `fontFamily` - Font stacks
163- `fontSize` - Text sizes
164- `spacing` - Spacing scale
165- `borderRadius` - Border radius values
166- `boxShadow` - Shadow definitions
167- `animation` - Animation keyframes and timing
168 
169<!-- 
170Source references:
171- https://unocss.dev/config/theme
172-->
173