css-variants — Fastest CSS Variant Library for JavaScript

What is css-variants?

css-variants is a JavaScript library for managing CSS class variants with full TypeScript support. It generates CSS classes at runtime based on declarative variant definitions like color, size, and state.

Why developers choose css-variants:

• ~1KB gzipped — smallest variant library available
• 3-11x faster — outperforms CVA and tailwind-variants in benchmarks
• Zero dependencies — no clsx or tailwind-merge bundled
• Framework-agnostic — React, Vue, Svelte, Solid, vanilla JS
• CSS-agnostic — Tailwind, CSS Modules, vanilla CSS, CSS-in-JS

Drop-in CVA and tailwind-variants replacement

css-variants is a drop-in replacement for CVA (Class Variance Authority) and tailwind-variants with better performance plus additional features like slot variants and style variants.

---

How to Define a CSS Variant

Use the cv() function to define variants declaratively. The function returns a callable that generates CSS class strings.

import { cv } from 'css-variants'

const button = cv({
  base: 'px-4 py-2 rounded font-medium transition-colors',
  variants: {
    color: {
      primary: 'bg-blue-600 text-white hover:bg-blue-700',
      secondary: 'bg-gray-200 text-gray-800 hover:bg-gray-300',
    },
    size: {
      sm: 'text-sm px-3 py-1.5',
      lg: 'text-lg px-6 py-3',
    },
  },
  defaultVariants: {
    color: 'primary',
    size: 'sm',
  },
})

button()                                   // Uses defaults: primary + sm
button({ color: 'secondary', size: 'lg' }) // Overrides: secondary + lg

---

Why Use css-variants Over CVA or tailwind-variants?

~1KB Bundle Size

Smallest variant library available. Zero dependencies means nothing else to download.

3-11x Faster Runtime

Optimized algorithms outperform CVA and tailwind-variants in all benchmarks.

Full TypeScript Support

Complete type inference. Get autocomplete for variant props without manual type definitions.

Framework and CSS Agnostic

Works with React, Vue, Svelte, Solid and any CSS approach (Tailwind, CSS Modules, vanilla).

---

API Functions

cv() — Class Variants Generate CSS class strings for single-element components

scv() — Slot Class Variants Generate class strings for multi-element components (cards, modals)

sv() — Style Variants Generate inline CSS style objects with variant support

cx() — Class Merger Merge and conditionally apply CSS class names (like clsx)

---

css-variants vs CVA vs tailwind-variants

Library	Bundle Size	Performance
css-variants	~1KB	Baseline
CVA	~2KB	3-7x slower
tailwind-variants	~5KB	5-11x slower

View Detailed Benchmarks See benchmark methodology and complete performance comparison data

---

Does css-variants Work Without Tailwind CSS?

Yes. css-variants is CSS-framework agnostic. Use it with any CSS approach:

// Tailwind CSS
const button = cv({
  base: 'px-4 py-2 rounded',
  variants: { color: { primary: 'bg-blue-600 text-white' } },
})

// Vanilla CSS
const button = cv({
  base: 'btn',
  variants: { color: { primary: 'btn-primary' } },
})

// CSS Modules
import styles from './Button.module.css'
const button = cv({
  base: styles.btn,
  variants: { color: { primary: styles.primary } },
})

---

How to Use css-variants with React, Vue, Svelte

React

<button className={button({ color: 'primary' })}>
  Click me
</button>

Vue

<button :class="button({ color: 'primary' })">
  Click me
</button>

Svelte

<button class={button({ color: 'primary' })}>
  Click me
</button>

Solid

<button class={button({ color: 'primary' })}>
  Click me
</button>

---

How to Migrate from CVA or tailwind-variants

Migrate from CVA Step-by-step guide to migrate from class-variance-authority

Migrate from tailwind-variants Step-by-step guide to migrate from tailwind-variants

Full Library Comparison Feature-by-feature comparison: css-variants vs CVA vs tailwind-variants

---

Get Started

Introduction Learn what css-variants is and why you should use it

Quick Start Build your first variant in under 5 minutes

Tailwind Integration Best practices for using css-variants with Tailwind CSS

FAQ Answers to frequently asked questions