API reference

Reference for uv, cn, VariantProps, and the options object. Verified against unocss-variants 1.5.0 source and the published dist.

import type { ClassValue, UvReturnType, VariantProps } from 'unocss-variants';
import {

  cn, // source export; not in npm 1.5.0 JS — see cn page
  uv

} from 'unocss-variants';

uv takes one argument. There is no config parameter.

`uv(options)`

Creates a recipe. The return value is a function plus metadata.

const button = uv(options);

button({ color: 'primary' }); // string when `slots` is omitted

const { base, title } = alert({ color: 'danger' }); // slot functions when `slots` is set
base(); // string
title({ class: 'truncate' }); // string

button.base; // ClassValue — the resolved base definition
button.slots; // slot class map
button.variants; // variant definitions
button.variantKeys; // string[] of axis names
button.defaultVariants; // default variant values
button.compoundVariants; // array
button.compoundSlots; // array
button.extend; // parent recipe or null

Do not write uv(options, config) or element({ '...' }). Props are a typed object of variant keys plus optional class / className.

Options

extend

UvReturnType | undefined

Parent recipe to merge. See Composing components. Default: undefined.

base

ClassValue

Classes always included (or the implicit base slot when slots is set). Default: undefined.

slots

Record<string, ClassValue>

Named parts. A non-empty object switches the return value to slot functions and adds an implicit base slot. Default: omitted (string return). On npm 1.5.0, slots: {} does not enter slot mode.

variants

Record<string, Record<string, ClassValue | SlotMap>>

Variant axes. Values are class strings/arrays, or per-slot maps. See Variants. Default: {}.

defaultVariants

Record<string, string | boolean | undefined>

Values used when a key is omitted at the call site. This is not a class map. See Default variants. Default: {}.

compoundVariants

Array<VariantMatch & ClassProp>

Extra classes when several keys match. Must be an array. class / className may be a string or a slot map. Default: [].

compoundSlots

Array<{ slots: string[] } & VariantMatch & ClassProp>

Extra classes applied to the listed slots, optionally gated by variant keys. Default: [].

Call-site props

type ClassProp<V = ClassValue>
  = | { class?: V; className?: never }
    | { class?: never; className?: V };

Plus one optional field per variant key. class and className are interchangeable.

`cn` / `cnBase`

Join class values without merging. See cn for the source vs npm 1.5.0 export split.

cn('px-2', 'px-4'); // 'px-2 px-4'  (source)
cnBase('px-2', 'px-4'); // 'px-2 px-4'  (npm 1.5.0 runtime)

`VariantProps<T>`

type VariantProps<Component extends (...args: any) => any> = Omit<
  NonNullable<Parameters<Component>[0]>,
  'class' | 'className'
>;

See TypeScript.

Types

`ClassValue`

type ClassValue = ClassArray | string | null | undefined | 0 | 0n | false;
type ClassArray = ReadonlyArray<ClassValue>;

Not a { [class]: boolean } dictionary. Object maps are accepted by cn / cnBase (CnOptions), not by this type.

`UvReturnType`

Callable recipe plus:

interface UvReturnProps {
  extend: UvReturnType | null | undefined;
  base: ClassValue;
  slots: Record<string, ClassValue> | undefined;
  variants: Record<string, unknown> | undefined;
  defaultVariants: Record<string, unknown>;
  compoundVariants: Array<unknown>;
  compoundSlots: Array<unknown>;
  variantKeys: Array<string> | undefined;
}

The historical name UVReturnType is wrong — use UvReturnType.

Not exported (source)

createUv / createTV
cx, cnMerge
defaultConfig
Anything from unocss-variants/lite

createUv still appears on the stale npm 1.5.0 JavaScript bundle as createUv() => uv. Do not depend on it.