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)

If you are using VSCode and the TailwindCSS IntelliSense Extension (opens in a new tab) you can enable autocompletion for Tailwind Variants by adding the following to your settings.json file.

{
  "tailwindCSS.experimental.classRegex": [
    ["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