Installation

Setup UnoCSS

UnoCSS Variants only builds class strings. You still need UnoCSS in the project so those utilities exist in CSS.

Install the package

pnpm add unocss-variants

npm install unocss-variants

bun add unocss-variants

Published version 1.5.0 is unocss-variants on npm. The source at that tag exports uv and cn. See the cn page for a mismatch between those types and the published JavaScript bundle.

Configure a uv layer

Because uv never merges utilities, give later styles a higher CSS layer. Add a uv layer and prefix classes that must win with uno-layer-uv::

import { defineConfig } from 'unocss';

export default defineConfig({
  layers: {
    uv: 10
  }
});

Higher numbers are emitted later and win over the default layer. Full explanation: Layers & conflict resolution.

Your first recipe

Define a recipe with uv, then call it like a function. defaultVariants keep call sites short.

<script setup>
import { uv } from 'unocss-variants';

const button = uv({
  base: 'font-medium bg-blue-500 color-white rounded-full active:opacity-80',
  variants: {
    color: {
      primary: 'bg-blue-500 color-white',
      secondary: 'bg-purple-500 color-white'
    },
    size: {
      sm: 'text-sm',
      md: 'text-base',
      lg: 'px-4 py-3 text-lg'
    }
  },
  compoundVariants: [
    {
      size: ['sm', 'md'],
      class: 'px-3 py-1'
    }
  ],
  defaultVariants: {
    size: 'md',
    color: 'primary'
  }
});
</script>

<template>
  <button :class="button({ size: 'sm', color: 'secondary' })">
    Click me
  </button>
</template>

Editor setup

Install the UnoCSS VS Code extension so utilities inside recipe strings are detected. The default extractor picks up quoted class strings in uv({ ... }) calls.

There is no Tailwind classRegex to copy — UnoCSS Variants is not Tailwind, and it does not ship IntelliSense for a responsiveVariants map.

Next steps