API Reference

Here’s the API reference for the tailwind-variants exported types and functions.

Main Functions

tv

import { tv } from 'tailwind-variants'
 
const element = tv(options, config)
 
// call the element function to get the class names
 
element({'...'}) // => string
 
// call the element function with slots to get the class names
 
const { slot1, slot2 } = element({...}) // => Record<Function, Function>
 
slot1({}) // => string
 
// access to the returned object
 
element.base // => string
element.slots // => Record<string, string>
element.variants // => Record<string, string>
element.variantKeys // => string[]
element.defaultVariants // => Record<string, string>
element.compoundVariants // => Array<Record<string, string>>
element.compoundSlots // => Array<Record<string, string>>

createTV

Creates a custom tv instance with the specified default configuration.

import { createTV } from 'tailwind-variants';
 
const tv = createTV({
  twMerge: true,
  twMergeConfig: {
    // custom config
  }
});

cn

A utility function for concatenating and merging class names with automatic conflict resolution. In v3.2.2+, cn returns a string directly with default twMerge config - no function call needed.

// Original build (with tailwind-merge)
import { cn } from 'tailwind-variants';
 
// Lite build (without tailwind-merge)
import { cn } from 'tailwind-variants/lite';
 
// Usage - with conflict resolution (original build)
cn('text-blue-500', 'text-red-500'); // => "text-red-500" (conflicts resolved)
cn('text-blue-500', 'hover:text-blue-700'); // => "text-blue-500 hover:text-blue-700"
cn(['text-blue-500', null, undefined, 'hover:text-blue-700']); // => "text-blue-500 hover:text-blue-700"
cn('text-blue-500', { 'font-bold': true, italic: false }); // => "text-blue-500 font-bold"

Note:

• v3.2.2+: cn now returns a string directly (no config support). For custom twMerge config, use cnMerge.
• In the original build, cn defaults twMerge to true and uses tailwind-merge for automatic conflict resolution. Use cx if you need a lightweight utility without conflict resolution.

cnMerge

A utility function for concatenating and merging class names with support for custom twMerge configuration. Use cnMerge when you need to customize the twMerge behavior.

Added in v3.2.2 - This function provides config-based usage that was previously available through cn’s Proxy implementation.

// Original build (with tailwind-merge)
import { cnMerge } from 'tailwind-variants';
 
// Lite build (without tailwind-merge)
import { cnMerge } from 'tailwind-variants/lite';
 
// Usage with custom config
cnMerge('px-2', 'px-4')({ twMerge: false }); // => "px-2 px-4" (no conflict resolution)
cnMerge('px-2', 'px-4')(); // => "px-4" (with default config, conflicts resolved)
cnMerge('text-blue-500', 'text-red-500')({ twMerge: true }); // => "text-red-500" (conflicts resolved)
 
// With custom twMergeConfig
cnMerge(
  'px-2',
  'px-4'
)({
  twMerge: true,
  twMergeConfig: {
    // custom tailwind-merge config
  }
});

When to use cnMerge vs cn?

• Use cn for the common case - it returns a string directly with default config
• Use cnMerge when you need to customize twMerge behavior (disable it, or provide custom config)

cnBase

Deprecated: cnBase is exported for backwards compatibility but should be replaced with cx (v3.2.0+). The cx function provides the same functionality with a clearer name.

cx

A lightweight utility function for concatenating class names without tailwind-merge conflict resolution. Similar to clsx - simple concatenation without merging conflicting classes. Use cx when you don’t need automatic conflict resolution and want a smaller bundle size.

Added in v3.2.0 - This function replaces cnBase and provides the same functionality with a clearer name.

// Original build (with tailwind-merge)
import { cx } from 'tailwind-variants';
 
// Lite build (without tailwind-merge)
import { cx } from 'tailwind-variants/lite';
 
// Usage - no conflict resolution
// Simple concatenation
cx('text-xl', 'font-bold'); // => 'text-xl font-bold'
 
// Handles arrays and objects
cx(['px-4', 'py-2'], { 'bg-blue-500': true, 'text-white': false }); // => 'px-4 py-2 bg-blue-500'
 
// Ignores falsy values (except 0)
cx('text-xl', false && 'font-bold', null, undefined); // => 'text-xl'
 
// Multiple classes
cx('text-blue-500', 'text-red-500'); // => "text-blue-500 text-red-500" (both classes included)
cx('text-blue-500', 'hover:text-blue-700'); // => "text-blue-500 hover:text-blue-700"
cx(['text-blue-500', null, undefined, 'hover:text-blue-700']); // => "text-blue-500 hover:text-blue-700"
cx('text-blue-500', { 'font-bold': true, italic: false }); // => "text-blue-500 font-bold"

When to use cx vs cn?

• Use cx when you don’t need conflict resolution and want a smaller bundle
• Use cn when you need automatic Tailwind CSS conflict resolution (original build only)

Migration from cnBase: In v3.2.0+, replace cnBase with cx. The API is identical.

Options

The options argument is an object with the following properties:

type TVOptions = {
  extend?: TVReturnType | undefined;
  base?: ClassValue;
  slots?: Record<string, ClassValue>;
  variants?: Record<string, Record<string, ClassValue>>;
  defaultVariants?: Record<string, ClassValue>;
  compoundVariants?: Array<Record<string, string> & ClassProp>;
  compoundSlots?: Array<Record<string, string> & ClassProp>;
};

extend

description: This property allows you to extend the base styles, slots, variants, defaultVariants and compoundVariants from another component.

type: TVReturnType | undefined

default: undefined

To learn more about Components composition, check out this page.

base

description: This property allows you to define the base styles for the component.

type: ClassValue

default: undefined

slots

description: This property allows you to define the slots for the component.

type: Record<string, ClassValue> | undefined

default: {}

To learn more about slots and how to use them, check out the Slots page.

variants

description: This property allows you to define the variants for the component.

type: Record<string, Record<string, ClassValue>> | undefined

default: {}

To learn more about variants and how to use them, check out the Variants page.

defaultVariants

description: This property allows you to define the default variants for the component.

type: Record<string, ClassValue> | undefined

default: {}

To learn more about default variants and how to use them, check out the Default Variants page.

compoundVariants

description: This property allows you to define the compound variants for the component.

type: Array<Record<string, string> & ClassProp> | undefined

default: []

To learn more about compound variants and how to use them, check out the Compound Variants page.

compoundSlots

description: This property allows you to define the compound slots for the component.

type: Array<Record<string, string> & ClassProp> | undefined

default: []

To learn more about compound slots and how to use them, check out the Compound Slots page.

Config (optional)

The config argument is an object with the following properties:

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

twMerge

description: Whether to merge the class names with tailwind-merge library. It’s avoid to have duplicate tailwind classes. (Recommended) see more here 

type: boolean

default: true

twMergeConfig

description: The config object for tailwind-merge library. see more here 

type: TwMergeConfig

default: {}

Types

ClassValue

type ClassValue = string | string[] | null | undefined | ClassValue[];

ClassProp

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

TVReturnType

type TVReturnType = {
  base?: string;
  extend?: TVReturnType;
  slots?: Record<string, string>;
  variants?: Record<string, string>;
  variantKeys?: string[];
  defaultVariants?: Record<string, string>;
  compoundVariants?: Array<Record<string, string>>;
};