Variants
Create multiple versions of a component with variant axes, boolean flags, compound rules, and defaults.
Adding variants
Add axes under variants. There is no limit to how many you define. Each value is a class string, an array of classes, or — with slots — a map of slot names.
import { uv } from 'unocss-variants';
const button = uv({
base: 'font-semibold color-white text-sm py-1 px-4 rounded-full active:opacity-80',
variants: {
color: {
primary: 'bg-blue-500 hover:bg-blue-700',
secondary: 'bg-purple-500 hover:bg-purple-700',
success: 'bg-green-500 hover:bg-green-700'
}
}
});
button({ color: 'secondary' });
// font-semibold color-white text-sm py-1 px-4 rounded-full active:opacity-80 bg-purple-500 hover:bg-purple-700
You can also pass arrays:
base: ['font-semibold', 'color-white', ...].Multiple variants
Axes combine independently.
import { uv } from 'unocss-variants';
const button = uv({
base: 'font-semibold color-white rounded-full active:opacity-80',
variants: {
color: {
primary: 'bg-blue-500 hover:bg-blue-700',
secondary: 'bg-purple-500 hover:bg-purple-700',
success: 'bg-green-500 hover:bg-green-700'
},
size: {
sm: 'py-1 px-3 text-xs',
md: 'py-1.5 px-4 text-sm',
lg: 'py-2 px-6 text-md'
}
}
});
button({ color: 'primary', size: 'sm' });
// font-semibold color-white rounded-full active:opacity-80 bg-blue-500 hover:bg-blue-700 py-1 px-3 text-xs
button({ color: 'secondary', size: 'md' });
// font-semibold color-white rounded-full active:opacity-80 bg-purple-500 hover:bg-purple-700 py-1.5 px-4 text-sm
button({ color: 'success', size: 'lg' });
// font-semibold color-white rounded-full active:opacity-80 bg-green-500 hover:bg-green-700 py-2 px-6 text-md
Boolean variants
Use 'true' / 'false' keys (or true / false in JS) for flags such as disabled. Passing disabled: true selects the true entry.
import { uv } from 'unocss-variants';
const button = uv({
base: 'font-semibold color-white text-sm py-1 px-4 rounded-full active:opacity-80',
variants: {
color: {
primary: 'bg-blue-500 hover:bg-blue-700',
secondary: 'bg-purple-500 hover:bg-purple-700',
success: 'bg-green-500 hover:bg-green-700'
},
disabled: {
true: 'opacity-50 uno-layer-uv:bg-gray-500 pointer-events-none'
}
}
});
button({ color: 'secondary', disabled: true });
// font-semibold color-white text-sm py-1 px-4 rounded-full active:opacity-80 bg-purple-500 hover:bg-purple-700 opacity-50 uno-layer-uv:bg-gray-500 pointer-events-none
uno-layer-uv:bg-gray-500 is what makes the gray background win over bg-purple-500. Without the layer prefix, both background utilities stay in the string and stylesheet order decides the winner.
Compound variants
compoundVariants is an array of objects. Each object lists the variant values that must match, plus class or className to append when they do.
import { uv } from 'unocss-variants';
const button = uv({
base: 'font-semibold color-white text-sm py-1 px-4 rounded-full active:opacity-80',
variants: {
color: {
primary: 'bg-blue-500 hover:bg-blue-700',
secondary: 'bg-purple-500 hover:bg-purple-700',
success: 'bg-green-500 hover:bg-green-700'
},
disabled: {
true: 'opacity-50 uno-layer-uv:bg-gray-500 pointer-events-none'
}
},
compoundVariants: [
{
color: 'success',
disabled: true,
class: 'uno-layer-uv:bg-green-100 uno-layer-uv:color-green-700 dark:color-green-800'
}
]
});
button({ color: 'success', disabled: true });
// font-semibold color-white text-sm py-1 px-4 rounded-full active:opacity-80 bg-green-500 hover:bg-green-700 opacity-50 uno-layer-uv:bg-gray-500 pointer-events-none uno-layer-uv:bg-green-100 uno-layer-uv:color-green-700 dark:color-green-800
compoundVariants must be an array. Passing a plain object throws at call time.Match several values
Use an array on a compound key to match any of those values.
const button = uv({
base: 'font-semibold color-white text-md py-1.5 px-4 rounded-full active:opacity-80',
variants: {
color: {
primary: 'bg-blue-500 hover:bg-blue-700',
secondary: 'bg-purple-500 hover:bg-purple-700',
success: 'bg-green-500 hover:bg-green-700'
},
disabled: {
true: 'opacity-50 bg-gray-500 pointer-events-none'
}
},
compoundVariants: [
{
color: 'success',
disabled: true,
class: 'bg-green-100 color-green-700 dark:color-green-800'
},
{
color: ['primary', 'secondary'],
disabled: true,
class: 'color-slate-400 uno-layer-uv:bg-slate-200 uno-layer-uv:dark:bg-slate-800 opacity-100'
}
]
});
button({ color: 'primary', disabled: true });
// font-semibold color-white text-md py-1.5 px-4 rounded-full active:opacity-80 bg-blue-500 hover:bg-blue-700 opacity-50 bg-gray-500 pointer-events-none color-slate-400 uno-layer-uv:bg-slate-200 uno-layer-uv:dark:bg-slate-800 opacity-100
button({ color: 'secondary', disabled: true });
// font-semibold color-white text-md py-1.5 px-4 rounded-full active:opacity-80 bg-purple-500 hover:bg-purple-700 opacity-50 bg-gray-500 pointer-events-none color-slate-400 uno-layer-uv:bg-slate-200 uno-layer-uv:dark:bg-slate-800 opacity-100
Default variants
defaultVariants supplies values when a key is omitted at the call site. Keys listed here stay optional on VariantProps.
import { uv } from 'unocss-variants';
const button = uv({
base: 'font-semibold color-white rounded-full active:opacity-80',
variants: {
color: {
primary: 'bg-blue-500 hover:bg-blue-700',
secondary: 'bg-purple-500 hover:bg-purple-700',
success: 'bg-green-500 hover:bg-green-700'
},
size: {
sm: 'py-1 px-3 text-sm',
md: 'py-1.5 px-4 text-md',
lg: 'py-2 px-6 text-lg'
}
},
defaultVariants: {
color: 'primary',
size: 'md'
}
});
button();
// font-semibold color-white rounded-full active:opacity-80 bg-blue-500 hover:bg-blue-700 py-1.5 px-4 text-md
Passing size: 'sm' overrides the default for that call only.