Skip to content

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

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

Released under the MIT License.