Lightweight helpers to compose class names and inline styles using variants. Zero runtime deps, small bundle, and first-class TypeScript support.
npm install css-variantsFastest 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.
---
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.
``bash`
npm install css-variants
`bash`
pnpm add css-variants
`bash`
yarn add css-variants
---
Create type-safe variants for single-element components:
`typescript
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
`
Create variants for multi-element components (cards, modals, dropdowns):
`typescript
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'
`
Create variants that return CSS style objects:
`typescript
import { sv } from 'css-variants'
const box = sv({
base: { display: 'flex', borderRadius: '8px' },
variants: {
size: {
sm: { padding: '8px' },
lg: { padding: '24px' },
},
},
})
$3
Lightweight clsx alternative for conditional class merging:
typescript
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:
typescript
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)),
})
`---
Framework Examples
$3
tsx
import { cv } from 'css-variants'const button = cv({
base: 'rounded font-medium',
variants: {
variant: { primary: 'bg-blue-600 text-white' },
},
})
type ButtonProps = React.ButtonHTMLAttributes &
Parameters[0]
function Button({ variant, className, ...props }: ButtonProps) {
return
}
`$3
vue
`---
Migrate from CVA
diff
- 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' }
],
})
`---
API Reference
| 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) |---
- Getting Started
- API Reference
- Tailwind CSS Guide
- React, Vue, Svelte Guides
- css-variants vs CVA vs tailwind-variants
- FAQ
---
MIT © Tim Phan