Introduction

Tailwind Variants is a first-class variant API for Tailwind CSS. You define a component recipe once — base styles, variants, defaults, and compound rules — and call it anywhere with typed props.

Design systems need consistency without copy-pasting class strings. Tailwind Variants gives you Stitches-style variants on top of Tailwind: composable, predictable, and framework-agnostic.

Why Tailwind Variants

• One recipe, many call sites — Change color or size at the call site instead of editing long class strings.
• Conflict resolution built in — The default build merges conflicting Tailwind classes. No extra tailwind-merge install for TV.
• Slots for multi-part UI — Buttons with icons, alerts with titles, cards with headers — each part gets its own styles and variants.
• TypeScript-first — Infer variant props with VariantProps. Slotted components get typed slot functions.
• Two builds — Default (with merge) or tailwind-variants/lite when bundle size matters more.

Key features

Variants

Define variant keys like color, size, or boolean flags like disabled. Each key maps to Tailwind classes. Think of each key as an independent axis when you combine several (for example color × size).

import { tv } from 'tailwind-variants';const button = tv({  base: 'inline-flex cursor-pointer items-center justify-center rounded-full font-medium select-none transition-colors',  variants: {    variant: {      primary: 'bg-zinc-900 text-white hover:bg-zinc-800',      secondary: 'border border-zinc-300 bg-zinc-50 text-zinc-900 hover:bg-zinc-100',      tertiary: 'text-zinc-700 hover:bg-zinc-200/70 hover:text-zinc-950'    },    size: {      sm: 'h-8 px-3 text-sm',      md: 'h-10 px-4 text-sm'    }  },  defaultVariants: {    variant: 'primary',    size: 'md'  }});

Slots

Split a component into named parts — base, icon, label — and style each independently.

Compound variants

Apply extra classes when specific variant combinations match — for example, color: primary + size: lg.

Extend

Build on existing recipes. Extend a base button to add an iconOnly variant without duplicating styles.

Responsive

Put Tailwind breakpoint prefixes (sm:, md:, lg:) in your recipe class strings. See Responsive.

Community

Issues, feature requests, showcases, and questions are welcome. Pick the channel that fits:

• Discord — chat and quick help
• GitHub Discussions — longer-form questions
• GitHub Issues — bugs and proposals
• Twitter — announcements and updates

Credits

Tailwind Variants is heavily inspired by Stitches and CVA.

Thanks to Tianen Pang for API design and early library work, Junior Garcia for building the library and docs, Mark Skelton for ongoing maintenance, and Joe Bell for CVA.

See Acknowledgements for the full list of inspirations and dependencies.