class-variance-authority

What is class-variance-authority?

The class-variance-authority (CVA) npm package is a utility for managing and composing CSS class names in a more declarative and type-safe manner. It helps in creating consistent and reusable class name patterns, especially useful in component-based frameworks like React.

What are class-variance-authority's main functionalities?

Defining Variants

This feature allows you to define variants for your CSS classes. You can specify different styles for different states or conditions, making it easier to manage complex styling logic.

const button = cva('btn', {
  variants: {
    size: {
      small: 'btn-small',
      large: 'btn-large'
    },
    color: {
      primary: 'btn-primary',
      secondary: 'btn-secondary'
    }
  },
  defaultVariants: {
    size: 'small',
    color: 'primary'
  }
});

// Usage
const className = button({ size: 'large', color: 'secondary' });

Combining Variants

This feature allows you to combine multiple variant definitions into a single class name. It helps in creating more complex and reusable class name patterns.

const button = cva('btn', {
  variants: {
    size: {
      small: 'btn-small',
      large: 'btn-large'
    },
    color: {
      primary: 'btn-primary',
      secondary: 'btn-secondary'
    }
  }
});

const iconButton = cva(button, {
  variants: {
    icon: {
      left: 'btn-icon-left',
      right: 'btn-icon-right'
    }
  }
});

// Usage
const className = iconButton({ size: 'large', color: 'primary', icon: 'left' });

Type Safety

CVA provides type safety when defining and using variants. This ensures that you are using the correct variant names and values, reducing the likelihood of runtime errors.

const button = cva('btn', {
  variants: {
    size: {
      small: 'btn-small',
      large: 'btn-large'
    },
    color: {
      primary: 'btn-primary',
      secondary: 'btn-secondary'
    }
  }
});

// TypeScript will enforce correct usage
const className: string = button({ size: 'large', color: 'primary' });

Other packages similar to class-variance-authority

classnames

The classnames package is a simple utility for conditionally joining class names together. It is less feature-rich compared to CVA but is widely used for its simplicity and ease of use. Unlike CVA, it does not provide built-in support for defining and managing variants.

styled-components

Styled-components is a library for styling React components using tagged template literals. It offers a more comprehensive solution for styling, including support for themes and dynamic styling. However, it is more complex and has a steeper learning curve compared to CVA.

emotion

Emotion is a library designed for writing CSS styles with JavaScript. It provides powerful and flexible styling capabilities, including support for CSS-in-JS, theming, and more. While it offers more features than CVA, it is also more complex and may be overkill for simpler use cases.

README

class-variance-authority

For documentation, visit cva.style.