# API Reference (https://www.tailwind-variants.org/docs/api-reference)

Reference for tv, createTV, VariantProps, cn/cx/cnMerge, and configuration types exported by Tailwind Variants.

Condensed reference for `tailwind-variants` v3.3.

```ts
import {
  tv,
  createTV,
  cn,
  cnMerge,
  cx,
  type VariantProps
} from 'tailwind-variants';
```

Lite build:

```ts
import { tv, cx } from 'tailwind-variants/lite';
```

## `tv`
Creates a variant recipe. Returns a callable function plus metadata.

```ts
const button = tv(options, config?);

button({ variant: 'primary' }); // => string (no slots)
button({ variant: 'primary' }).base(); // => string (with slots)

button.base;              // resolved base string
button.slots;             // slot class map
button.variants;          // variant definitions
button.variantKeys;       // ['variant', 'size', ...]
button.defaultVariants;   // { variant: 'primary', ... }
button.compoundVariants;  // array
button.compoundSlots;     // array
```

### Options
```ts
type TVOptions = {
  extend?: TVReturnType;
  base?: ClassValue;
  slots?: Record<string, ClassValue>;
  variants?: Record<string, Record<string, ClassValue>>;
  defaultVariants?: Record<string, ClassValue>;
  compoundVariants?: Array<Record<string, unknown> & ClassProp>;
  compoundSlots?: Array<Record<string, unknown> & ClassProp>;
};
```

| Option             | Description                                                       |
| ------------------ | ----------------------------------------------------------------- |
| `extend`           | Merge another recipe's base, slots, variants, defaults, compounds |
| `base`             | Shared classes for every call                                     |
| `slots`            | Named parts; `{}` enables implicit `base` slot only               |
| `variants`         | Variant axes; per-slot objects when using slots                   |
| `defaultVariants`  | Values applied when keys are omitted                              |
| `compoundVariants` | Extra classes when multiple conditions match                      |
| `compoundSlots`    | Extra classes on specific slots when conditions match             |

### Config (2nd argument)
```ts
type TVConfig = {
  twMerge?: boolean;
  twMergeConfig?: TwMergeConfig;
};
```

### Call-site props
```ts
type ClassProp = {
  class?: ClassValue;
  className?: ClassValue;
};
```

Pass variant keys plus optional `class` / `className` overrides.

## `createTV`
Returns a `tv` with default config:

```ts
const tv = createTV({
  twMerge: true,
  twMergeConfig: { extend: { /* ... */ } }
});
```

## `cn`
Concatenate and merge with default config. Returns a **string** (v3.2.2+).

```ts
cn('px-2', 'px-4'); // => "px-4"
cn('text-sm', { 'font-bold': true }); // => "text-sm font-bold"
```

Default build only.

## `cnMerge`
Concatenate with optional per-call config:

```ts
cnMerge('px-2', 'px-4')(); // => "px-4"
cnMerge('px-2', 'px-4')({ twMerge: false }); // => "px-2 px-4"
```

Default build only. Not exported from `/lite`.

## `cx`
Lightweight concat without conflict resolution:

```ts
cx('text-blue-500', 'text-red-500'); // => "text-blue-500 text-red-500"
```

Available in default and lite builds. Replaces deprecated `cnBase`.

## `VariantProps`
Extract variant prop types from a recipe:

```ts
type Props = VariantProps<typeof button>;
// { variant?: 'primary' | 'secondary' | 'tertiary'; size?: 'sm' | 'md' }
```

## Types
| Type              | Description                                                          |
| ----------------- | -------------------------------------------------------------------- |
| `ClassValue`      | `string \| string[] \| Record<string, boolean> \| null \| undefined` |
| `VariantProps<T>` | Inferred variant keys from recipe `T`                                |
| `TVReturnType`    | Return type of `tv()` — callable + metadata                          |

## Slotted return type
When `slots` is defined, calling the recipe returns an object of functions:

```ts
const { base, title } = alert({ color: 'danger' });
base({ class: 'mt-2' }); // => string
```

Each slot function accepts `class` / `className` and variant overrides scoped to that slot.