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 VariantsCopy Anchor Link

• 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 includes merge. tailwind-variants/lite skips the table, or lets you inject one you already have.

Key featuresCopy Anchor Link

VariantsCopy Anchor Link

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'  }});

SlotsCopy Anchor Link

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

Compound variantsCopy Anchor Link

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

ExtendCopy Anchor Link

Build on existing recipes — one parent or several at once. Extend a base button to add an iconOnly variant, or compose shared focus and motion recipes, without duplicating styles.

ResponsiveCopy Anchor Link

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

CommunityCopy Anchor Link

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

CreditsCopy Anchor Link

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.