cva is a TypeScript utility for defining and resolving visual variants for UI components with full type safety. It generates CSS class strings from typed variant definitions, enabling compile-time validation of component usage by deriving the union of all variant prop types from a configuration object.
The library distinguishes itself through compound variant matching, which activates styles only when multiple independent variant conditions are simultaneously satisfied, merging their class names. It also provides default value propagation to ensure consistent rendering when no explicit variant is chosen, and supports polymorphic element binding so the same variant logic can be applied to any HTML element type. For projects using Tailwind CSS, cva includes a conflict resolution mechanism that merges conflicting utility classes using a last-wins precedence rule.
The tool allows composing variant definitions, extracting variant prop types for reuse, and extending styled components while preserving each variant's styling. It handles class name concatenation gracefully, managing conditional and duplicate entries without runtime overhead.