Config

Tailwind Variants has several ways to specify config options:

Passing config to the tv function
Creating a custom tv instance using createTV
Modifying the defaultConfig variable

Build Options (v3+)

Starting from v3, Tailwind Variants offers two build options:

Original Build (Default)

Import from tailwind-variants
Includes tailwind-merge for automatic conflict resolution
Supports all configuration options including twMerge and twMergeConfig
Requires tailwind-merge to be installed as a dependency

import { tv, createTV, cn } from 'tailwind-variants';

Lite Build

Import from tailwind-variants/lite
Excludes tailwind-merge for a smaller bundle (~80% smaller)
Does not support twMerge or twMergeConfig options
No external dependencies required

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

Choose the lite build if:

You don't need automatic Tailwind class conflict resolution
Bundle size is a critical concern
You handle class merging manually or don't have conflicting classes

Local Config

The easiest way to configure Tailwind Variants is using the second argument of the tv function. This will set the configuration for this specific tv call and is useful for one-off config changes.

tv(
  { base: '' },
  {
    twMerge: false
    // ...
  }
);

Global config

If you want your config to apply to all usages of tv, you can modify the defaultConfig variable to set global configuration for all calls of tv.

import { defaultConfig } from 'tailwind-variants';
 
defaultConfig.twMerge = false;

Custom `tv` instance

If you have different configs for different use cases, the default config might not work for you. Instead, you can use the createTV function to create an instance of tv with the specified config.

import { createTV } from 'tailwind-variants';
 
const tv = createTV({
  twMerge: false
  // ...
});
 
tv({ base: '' });

Advanced: Custom `tv` wrapper

For more advanced use cases, you can create a custom tv wrapper that extends the default configuration with your own custom merge config:

// tv.ts
import type {TV} from "tailwind-variants";
import {tv as tvBase} from "tailwind-variants";
 
const COMMON_UNITS = ["small", "medium", "large"];
 
const twMergeConfig = {
  theme: {
    spacing: ["divider"],
    radius: COMMON_UNITS,
  },
  classGroups: {
    shadow: [{shadow: COMMON_UNITS}],
    opacity: [{opacity: ["disabled"]}],
    "font-size": [{text: ["tiny", ...COMMON_UNITS]}],
    "border-w": [{border: COMMON_UNITS}],
    "bg-image": [
      "bg-stripe-gradient-default",
      "bg-stripe-gradient-primary",
      "bg-stripe-gradient-secondary",
      "bg-stripe-gradient-success",
      "bg-stripe-gradient-warning",
      "bg-stripe-gradient-danger",
    ],
  },
};
 
export const tv: TV = (options, config) =>
  tvBase(options, {
    ...config,
    twMerge: config?.twMerge ?? true,
    twMergeConfig: {
      ...config?.twMergeConfig,
      theme: {
        ...config?.twMergeConfig?.theme,
        ...twMergeConfig.theme,
      },
      classGroups: {
        ...config?.twMergeConfig?.classGroups,
        ...twMergeConfig.classGroups,
      },
    },
  });

This approach allows you to:

Extend the default tailwind-merge configuration with custom theme values
Add custom class groups for your design system
Maintain type safety with the TV type
Override any default configuration while preserving the rest

Config Options

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

`twMerge`

description: Whether to merge class names with the tailwind-merge library. It avoids having duplicate tailwind classes. (Recommended) see more here (opens in a new tab)

Note:

Starting from v2, tailwind-merge is an optional peer dependency that needs to be installed separately.

Starting from v3, this option is only available in the original build (tailwind-variants), not in the lite build (tailwind-variants/lite).

If you don't install tailwind-merge, you must either use the lite build or set twMerge: false.

type: boolean

default: true (original build only)

availability: Original build only (tailwind-variants)

`twMergeConfig`

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

type: TwMergeConfig

default: {}