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

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

Responsive variants (optional)

If you want to use responsive variants, you need to add the Tailwind Variants wrapper to your TailwindCSS config file tailwind.config.js.

// tailwind.config.js
const { withTV } = require('tailwind-variants/transformer');
 
/** @type {import('tailwindcss').Config} */
module.exports = withTV({
  content: ['./index.html', './src/**/*.{js,ts,jsx,tsx}'],
  theme: {
    extend: {}
  },
  plugins: []
});

Why do I need to add the transformer?

If you are wondering why you need to add the transformer, it's because TailwindCSS uses something called JIT (opens in a new tab) which compiles your CSS on demand based on the classes you use in your HTML / JSX files / etc. As the responsive variants need to be dynamic the JIT compiler doesn't know what classes to compile, so we need to add the transformer to tell the compiler what classes to compile.

Responsive variants usage

Tailwind Variants allows you to apply variants to different screen sizes.

import { tv } from 'tailwind-variants';
 
const button = tv(
  {
    base: 'font-semibold text-white py-1 px-3 rounded-full active:opacity-80',
    variants: {
      color: {
        primary: 'bg-blue-500 hover:bg-blue-700',
        secondary: 'bg-purple-500 hover:bg-purple-700',
        success: 'bg-green-500 hover:bg-green-700',
        error: 'bg-red-500 hover:bg-red-700'
      }
    }
  },
  {
    responsiveVariants: ['xs', 'sm', 'md'] // `true` to apply to all screen sizes
  }
);
 
button({
  color: {
    initial: 'primary',
    xs: 'secondary',
    sm: 'success',
    md: 'error'
  }
});
 
/**
 * Result:
 * font-semibold text-white py-1 px-3 rounded-full active:opacity-80 bg-blue-500 hover:bg-blue-700
 * xs:bg-purple-500 xs:hover:bg-purple-700 sm:bg-green-500 sm:hover:bg-green-700 md:bg-red-500
 * md:hover:bg-red-700
 */

IntelliSense setup (optional)

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

If you are using VSCode and the TailwindCSS IntelliSense Extension (opens in a new tab), you have to add the following to your settings.json file.

{
  "tailwindCSS.experimental.classRegex": [
    ["tv\\((([^()]*|\\([^()]*\\))*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"]
  ]
}

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.

Introduction Comparison