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

Installation

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

npm install 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

Then import from the default entry point:

import { tv, createTV, cn } 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 } from 'tailwind-variants/lite';

Note: The lite build doesn't support the twMerge and twMergeConfig options. Choose this if bundle size is critical and you don't need automatic conflict resolution.

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.experimental.classRegex": [
    ["([\"'`][^\"'`]*.*?[\"'`])", "[\"'`]([^\"'`]*).*?[\"'`]"]
  ]
}

Prettier plugin setup (optional)

If you are using prettier-plugin-tailwindcss (opens in a new tab) 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.