---
title: "API reference"
description: "Reference for uv, cn, VariantProps, and the options object. Verified against unocss-variants 1.5.0 source and the published dist."
canonical_url: "https://vinicunca.dev/unocss-variants/api"
---
# API reference

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

```ts
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.

```ts
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

```ts
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](https://vinicunca.dev/unocss-variants/concepts/cn) for the source vs npm 1.5.0 export split.

```ts
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>`

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

See [TypeScript](https://vinicunca.dev/unocss-variants/concepts/typescript).

## Types

### `ClassValue`

```ts
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:

```ts
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.


## Sitemap

See the full [sitemap](https://vinicunca.dev/sitemap.md) for all pages.