joe-bell/cva
Cva
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.
Features
- Variant Defaults - Provides default value propagation so components render consistently when no explicit variant is chosen.
- Variant Prop Type Extractors - Infers the union of all variant prop values from a component definition for reuse in parent components.
- Variant Prop Type Inferences - Derives the union of all variant prop types from a configuration object for compile-time validation.
- Typed Variant Definitions - Defines component variants as typed objects so the compiler catches invalid combinations before runtime.
- Variant Default Values - Assigns fallback variant values at definition time so components render consistently when no explicit prop is provided.
- Inferred Prop Types - Derives the union of all variant prop types from a configuration object, enabling compile-time validation of component usage.
- Polymorphic Component Rendering - Supports polymorphic element binding, allowing the same variant logic to be applied to any HTML element type.
- Variant-Based Class Generators - Generates CSS class strings from typed variant definitions with zero runtime overhead.
- Variant Prop Type Inferences - Derives the union of all variant prop types from a configuration object for compile-time validation.
- Component Variant Presets - Defines visual or behavioral variations for a component and generates the correct class name string based on the chosen variant.
- Variant Default Value Assignments - Assigns fallback values for variant props so a component renders a consistent style when no explicit variant is chosen.
- Polymorphic Components - Provides polymorphic element binding so variant logic applies to any HTML element.
- Reusable Variant Definitions - Combines multiple variant definitions into a single, type-safe class name resolver for complex component styling.
- Static Variant Resolvers - Resolves component styles by mapping variant prop combinations to class strings through a statically defined configuration object.
- Variant-Based Style Resolvers - Defines visual variants for a component and produces a function that resolves the correct class names based on selected variant props.
- Compound Variant Activators - Ships a compound variant matching engine that activates styles only when multiple independent conditions are met.
- Conditional Compound Variants - Activates style variants only when multiple independent variant conditions are simultaneously satisfied.
- Variant Prop Type Inferences - Derives the union of all variant prop types from a configuration object for compile-time validation.
- Compound Variant Activators - Provides compound variant matching that activates styles only when multiple independent conditions are simultaneously satisfied.
- Multi-Condition Variant Activators - Activates compound variants when several independent variant conditions are met simultaneously, merging their class names.
- Type-Safe Variant Combiners - Combines multiple variant selections into a single, type-safe class name string for a component.
- Variant-Based Class Generators - Generates CSS class strings from typed variant definitions with full TypeScript type safety and zero runtime overhead.
- Variant Definition Composers - Combines multiple variant definitions into a single, type-safe class name resolver for complex component styling.
- Variant Prop Type Inferences - Derives the union of all variant prop types from a configuration object for compile-time validation.
- Tailwind CSS Conflict Resolvers - Includes a conflict resolution mechanism that merges conflicting Tailwind utility classes using last-wins precedence.
- Tailwind Class - Merges conflicting Tailwind CSS utility classes by wrapping variant definitions with a conflict-resolution utility.
- Class String Joiners - Handles class name concatenation gracefully, managing conditional and duplicate entries without runtime overhead.
- Conflict Resolvers - Includes a conflict resolution mechanism that merges conflicting Tailwind utility classes using last-wins precedence.
- Variant-Based Component Extenders - Combines multiple variant-based class name strings into a single component, preserving each variant's styling.
- Conflict Resolution Utilities - Includes a conflict resolution mechanism that merges conflicting Tailwind utility classes using a last-wins precedence rule.
