CVA (Class Variance Authority) Patterns

Quick Guide: cva() turns a component's visual states into one typed configuration object: base classes, variant groups (size, intent, state), compoundVariants for combinations that need their own styles, and defaultVariants for what a caller omits. VariantProps<typeof variants> derives the prop types from that object. It emits class-name strings and settles nothing about what those class names mean, so it works with utility classes, CSS modules or plain CSS alike.

Detailed Resources:

• examples/core.md — basic variants, boolean states, multiple variant groups, required variants
• examples/compound-variants.md — multi-condition styles, array syntax, state matrices
• examples/composition.md — VariantProps, class names from a scoped stylesheet, call-site appending and merging, multi-part components, extending variants
• reference.md — API signatures, pattern-selection table, pre-ship checklist

<critical_requirements>

Before writing CVA code

Define every variant option inside the variants object. Conditional class logic outside cva() splits the definition in two, and the derived types stop describing the component.