Getting started

Tailwind Variants combines the power of TailwindCSS with a first-class variant API.

Setup TailwindCSS

Tailwind Variants requires you to have TailwindCSS installed in your project. If you haven’t installed TailwindCSS yet, you can follow the TailwindCSS installation guide .

Compatibility: Tailwind Variants v3.x supports Tailwind CSS v4.x and requires tailwind-merge v3.x when using the original build. If you are still on Tailwind CSS v3.x, use tailwind-variants v0.x with tailwind-merge v2.6.0.

Installation

To use Tailwind Variants in your project, you can install it as a dependency:

npm install tailwind-variants

yarn add tailwind-variants

pnpm add tailwind-variants

Choose Your Build (v3+)

Starting from v3, Tailwind Variants offers two build options:

Option 1: Original Build (with tailwind-merge)

For automatic Tailwind CSS conflict resolution, install tailwind-merge as a dependency:

npm install tailwind-merge

yarn add tailwind-merge

pnpm add tailwind-merge

Then import from the default entry point:

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

Option 2: Lite Build (without tailwind-merge)

For a smaller bundle size (~80% smaller), use the lite build which doesn’t include tailwind-merge:

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

Note: The lite build doesn’t include tailwind-merge, so it doesn’t export cnMerge and doesn’t support the twMerge or twMergeConfig options. In the lite build, cn is a no-merge adapter that returns a curried (config) => string — use it for simple concatenation only. Choose this build if bundle size is critical and you don’t need automatic conflict resolution. cnMerge (v3.2.2+) is available only in the original build.

Usage

import { tv } from 'tailwind-variants';
 
const button = tv({
  base: 'font-medium bg-blue-500 text-white rounded-full active:opacity-80',
  variants: {
    color: {
      primary: 'bg-blue-500 text-white',
      secondary: 'bg-purple-500 text-white'
    },
    size: {
      sm: 'text-sm',
      md: 'text-base',
      lg: 'px-4 py-3 text-lg'
    }
  },
  compoundVariants: [
    {
      size: ['sm', 'md'],
      class: 'px-3 py-1'
    }
  ],
  defaultVariants: {
    size: 'md',
    color: 'primary'
  }
});
 
return (
  <button className={button({ size: 'sm', color: 'secondary' })}>
    Click me
  </button>
);

IntelliSense setup (optional)

To enable autocompletion for Tailwind Variants you can follow the instructions below.

{
  "tailwindCSS.classFunctions": ["tv"]
}

require('lspconfig').tailwindcss.setup({
  settings = {
    tailwindCSS = {
      classFunctions = { "tv" },
    },
  },
})

{
  "classFunctions": ["tv"]
}

Prettier plugin setup (optional)

If you are using prettier-plugin-tailwindcss  to sort your class names, you can add tv to the list of functions that should be sorted.

module.exports = {
  plugins: [require('prettier-plugin-tailwindcss')],
  tailwindFunctions: ['tv']
};

Contributing

PR’s on Tailwind Variants are always welcome, please see our contribution guidelines (opens in a new tab) to learn how you can contribute to this project.