css-variants

css-variants

Fastest CSS variant library for JavaScript and TypeScript

Type-safe alternative to CVA (Class Variance Authority) and tailwind-variants. ~1KB gzipped. 3-11x faster. Zero dependencies.

Documentation · API Reference · Comparison

What is css-variants?

css-variants is a JavaScript library for managing CSS class variants with full TypeScript support. Define style variations (color, size, state) declaratively and get the correct CSS classes at runtime.

Works with Tailwind CSS, vanilla CSS, CSS Modules, or any styling solution.

Installation

npm install css-variants

pnpm add css-variants

yarn add css-variants

Quick Start

cv() — Class Variants

Create type-safe variants for single-element components:

import { cv } from 'css-variants'

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

button()                                // Uses defaults
button({ color: 'secondary', size: 'lg' }) // Override variants
button({ className: 'w-full' })         // Add custom classes

scv() — Slot Class Variants

Create variants for multi-element components (cards, modals, dropdowns):

import { scv } from 'css-variants'

const card = scv({
  slots: ['root', 'header', 'body', 'footer'],
  base: {
    root: 'rounded-xl border shadow-sm',
    header: 'px-6 py-4 border-b font-semibold',
    body: 'px-6 py-4',
    footer: 'px-6 py-3 bg-gray-50',
  },
  variants: {
    variant: {
      default: { root: 'bg-white border-gray-200' },
      primary: { root: 'bg-blue-50 border-blue-200' },
    },
  },
})

const classes = card({ variant: 'primary' })
// classes.root   → 'rounded-xl border shadow-sm bg-blue-50 border-blue-200'
// classes.header → 'px-6 py-4 border-b font-semibold'

sv() — Style Variants

Create variants that return CSS style objects:

import { sv } from 'css-variants'

const box = sv({
  base: { display: 'flex', borderRadius: '8px' },
  variants: {
    size: {
      sm: { padding: '8px' },
      lg: { padding: '24px' },
    },
  },
})

<div style={box({ size: 'lg' })} />

cx() — Class Merger

Lightweight clsx alternative for conditional class merging:

import { cx } from 'css-variants'

cx('btn', 'btn-primary')              // 'btn btn-primary'
cx('btn', isActive && 'active')       // 'btn active' or 'btn'
cx('btn', { disabled: isDisabled })   // 'btn disabled' or 'btn'

Why css-variants?

Feature	css-variants	CVA	tailwind-variants
Bundle size	~1KB	~2KB	~5KB
Performance	Baseline	3-7x slower	5-11x slower
Slot variants	Built-in	No	Yes
Style variants	Built-in	No	No
Dependencies	0	1	1

Tailwind CSS Integration

Use with tailwind-merge for class conflict resolution:

import { cv, cx } from 'css-variants'
import { twMerge } from 'tailwind-merge'

const button = cv({
  base: 'px-4 py-2 rounded',
  variants: {
    size: { lg: 'px-6 py-3' },
  },
  classNameResolver: (...args) => twMerge(cx(...args)),
})

Full Tailwind guide →

Framework Examples

React

import { cv } from 'css-variants'

const button = cv({
  base: 'rounded font-medium',
  variants: {
    variant: { primary: 'bg-blue-600 text-white' },
  },
})

type ButtonProps = React.ButtonHTMLAttributes<HTMLButtonElement> &
  Parameters<typeof button>[0]

function Button({ variant, className, ...props }: ButtonProps) {
  return <button className={button({ variant, className })} {...props} />
}

Vue

<script setup lang="ts">
import { cv } from 'css-variants'

const button = cv({
  base: 'rounded font-medium',
  variants: {
    variant: { primary: 'bg-blue-600 text-white' },
  },
})

defineProps<{ variant?: 'primary' }>()
</script>

<template>
  <button :class="button({ variant })"><slot /></button>
</template>

Migrate from CVA

- import { cva } from 'class-variance-authority'
+ import { cv } from 'css-variants'

- const button = cva('base-classes', {
+ const button = cv({
+   base: 'base-classes',
    variants: { /* same */ },
    compoundVariants: [
-     { color: 'primary', class: 'extra' }
+     { color: 'primary', className: 'extra' }
    ],
  })

Full migration guide →

API Reference

Function	Description
cv()	Class variants for single-element components
scv()	Slot class variants for multi-element components
sv()	Style variants for inline CSS style objects
ssv()	Slot style variants for multi-element inline styles
cx()	Class merger utility (like clsx)

Documentation

css-variants.vercel.app

• Getting Started
• API Reference
• Tailwind CSS Guide
• React, Vue, Svelte Guides
• css-variants vs CVA vs tailwind-variants
• FAQ

License

MIT © Tim Phan