/unocss

UnoCSS Theme

UnoCSS supports theming similar to Tailwind CSS / Windi CSS. The theme property is deep-merged with the default theme.

Basic Usage

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

Using Theme in Rules

Access theme values in dynamic rules:

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

Using Theme in Variants

variants: [
  {
    name: 'variant-name',
    match(matcher, { theme }) {
      // Access theme.breakpoints, theme.colors, etc.
    },
  },
]

Using Theme in Shortcuts

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

Breakpoints

Warning: Custom breakpoints object overrides the default, not merges.

theme: {
  breakpoints: {
    sm: '320px',
    md: '640px',
  },
}

Only sm: and md: variants will be available.

Inherit Default Breakpoints

Use extendTheme to merge with defaults:

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

Note: verticalBreakpoints works the same for vertical layout.

Breakpoint Sorting

Breakpoints are sorted by size. Use consistent units to avoid errors:

theme: {
  breakpoints: {
    sm: '320px',
    // Don't mix units - convert rem to px
    // md: '40rem', // Bad
    md: `${40 * 16}px`, // Good
    lg: '960px',
  },
}

ExtendTheme

extendTheme lets you modify the merged theme object:

Mutate Theme

extendTheme: (theme) => {
  theme.colors.veryCool = '#0000ff'
  theme.colors.brand = {
    primary: 'hsl(var(--hue, 217) 78% 51%)',
  }
}

Replace Theme

Return a new object to completely replace:

extendTheme: (theme) => {
  return {
    ...theme,
    colors: {
      ...theme.colors,
      veryCool: '#0000ff',
    },
  }
}

Theme Differences in Presets

preset-wind3 vs preset-wind4

Common Theme Keys

• colors - Color palette
• breakpoints - Responsive breakpoints
• fontFamily - Font stacks
• fontSize - Text sizes
• spacing - Spacing scale
• borderRadius - Border radius values
• boxShadow - Shadow definitions
• animation - Animation keyframes and timing