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 / cnBase

A utility function for concatenating and merging class names. Enhanced in v3 to support functionality similar to classnames/clsx.

// Original build (with tailwind-merge) import { cn, cnBase } from 'tailwind-variants';   // Lite build (without tailwind-merge) import { cn, cnBase } from 'tailwind-variants/lite';   // Usage 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: Both cn and cnBase are exported for backwards compatibility, but cn is the recommended import name in v3+.

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 (opens in a new tab)

type: boolean

default: true

twMergeConfig

description: The config object for tailwind-merge library. see more here (opens in a new tab)

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>>; };