Condensed reference for tailwind-variants v3.3.

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

Lite build:

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

`tv`

Creates a variant recipe. Returns a callable function plus metadata.

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

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)

type TVConfig = {
  twMerge?: boolean;
  twMergeConfig?: TwMergeConfig;
};

Call-site props

type ClassProp = {
  class?: ClassValue;
  className?: ClassValue;
};

Pass variant keys plus optional class / className overrides.

`createTV`

Returns a tv with default config:

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

`cn`

Concatenate and merge with default config. Returns a string (v3.2.2+).

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:

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:

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:

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:

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

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

API Reference