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

cva

Class Variance Authority 🧬

Introduction

Coming from BEM…

import { cva } from "@joebell/cva";

const button = cva("button", {
  variants: {
    intent: {
      primary: "button--primary",
      secondary: "button--secondary",
      warning: "button--warning",
      danger: "button--danger",
    },
    size: {
      small: "button--small",
      medium: "button--medium",
      large: "button--large",
    },
  },
  compoundVariants: [
    { intent: "primary", size: "medium", class: "button--primary-small" },
  ],
  defaultVariants: {
    intent: "primary",
    size: "medium",
  },
});

button();
// => "button button--primary button--medium"

button({ intent: "secondary", size: "small" });
// => "button button--secondary button--small"

Tailwind

import { cva } from "@joebell/cva";

const button = cva(["font-semibold", "border", "rounded"], {
  variants: {
    intent: {
      primary: [
        "bg-blue-500",
        "text-white",
        "border-transparent",
        "hover:bg-blue-600",
      ],
      // **or**
      // primary: "bg-blue-500 text-white border-transparent hover:bg-blue-600",
      secondary: [
        "bg-white",
        "text-gray-800",
        "border-gray-400",
        "hover:bg-gray-100",
      ],
      warning: [
        "bg-yellow-500",
        "text-black",
        "border-transparent",
        "hover:bg-yellow-600",
      ],
      danger: [
        "bg-red-500",
        "text-white",
        "border-transparent",
        "hover:bg-red-600",
      ],
    },
    size: {
      small: ["text-sm", "py-1", "px-2"],
      medium: ["text-base", "py-2", "px-4"],
      large: ["text-lg", "py-2.5", "px-4"],
    },
  },
  compoundVariants: [{ intent: "primary", size: "medium", class: "uppercase" }],
  defaultVariants: {
    intent: "primary",
    size: "medium",
  },
});

button();
// => "font-semibold border rounded bg-blue-500 text-white border-transparent hover:bg-blue-600 text-base py-2 px-4 uppercase"

button({ intent: "secondary", size: "small" });
// => "font-semibold border rounded bg-white text-gray-800 border-gray-400 hover:bg-gray-100 text-sm py-1 px-2"

Problem?

Prior Art

• clb
• Stitches
• Vanilla Extract

Installation

npm i @joebell/cva

Getting Started

Composing Classes

Whilst cva doesn't yet offer a built-in method for composing classes, it does offer the tools to extend components on your own terms…

For example; two cva styles, concatenated together with cx:

// styles/components.ts
import type * as CVA from "cva";
import { cva, cx } from "@joebell/cva";

/**
 * Box
 */
export type BoxProps = CVA.VariantProps<typeof box>;
export const box = cva(["box", "box-border"], {
  variants: {
    margin: { 0: "m-0", 2: "m-2", 4: "m-4", 8: "m-8" },
    padding: { 0: "p-0", 2: "p-2", 4: "p-4", 8: "p-8" },
  },
  defaultVariants: {
    margin: 0,
    padding: 0,
  },
});

/**
 * Card
 */
type CardBaseProps = CVA.VariantProps<typeof cardBase>;
const cardBase = cva(["card", "border-solid", "border-slate-300", "rounded"], {
  variants: {
    shadow: {
      md: "drop-shadow-md",
      lg: "drop-shadow-lg",
      xl: "drop-shadow-xl",
    },
  },
});

export interface CardProps extends BoxProps, CardBaseProps {}
export const card = ({ margin, padding, shadow }: CardProps = {}) =>
  cx(box({ margin, padding }), cardBase({ shadow }));

API Reference

• cva – build a class variance authority
• cx – concatenate class names

cva

const component = cva("base", options);

Parameters

1. base – the base class name
2. options (optional)
   1. variants
   2. compoundVariants
   3. defaultVariants

cx

Examples

⚠️ Warning: The examples below are purely demonstrative and haven't been tested thoroughly (yet)

React (with CSS Modules)

/* button.css */
.base {
  /* */
}

.primary {
  /* */
}
.secondary {
  /* */
}

.small {
  /* */
}
.medium {
  /* */
}

.primaryMedium {
  /* */
}

// button.tsx
import React from "react";
import { cva } from "@joebell/cva";
import * as CVA from "@joebell/cva";

import {
  base,
  primary,
  secondary,
  small,
  medium,
  primaryMedium,
} from "./button.css";

// ⚠️ Disclaimer: Use of Tailwind CSS is optional
const button = cva(base, {
  variants: {
    intent: {
      primary,
      secondary,
    },
    size: {
      small,
      medium,
    },
  },
  compoundVariants: [
    { intent: "primary", size: "medium", class: primaryMedium },
  ],
  defaultVariants: {
    intent: "primary",
    size: "medium",
  },
});

export type ButtonProps = CVA.VariantProps<typeof button>;

export const Button: React.FC<ButtonProps> = ({ intent, size, ...props }) => (
  <button className={button({ intent, size })} {...props} />
);

React (with Tailwind)

// button.tsx
import React from "react";
import { cva } from "@joebell/cva";
import * as CVA from "@joebell/cva";

// ⚠️ Disclaimer: Use of Tailwind CSS is optional
const button = cva("button", {
  variants: {
    intent: {
      primary: [
        "bg-blue-500",
        "text-white",
        "border-transparent",
        "hover:bg-blue-600",
      ],
      secondary: [
        "bg-white",
        "text-gray-800",
        "border-gray-400",
        "hover:bg-gray-100",
      ],
    },
    size: {
      small: ["text-sm", "py-1", "px-2"],
      medium: ["text-base", "py-2", "px-4"],
    },
  },
  compoundVariants: [{ intent: "primary", size: "medium", class: "uppercase" }],
  defaultVariants: {
    intent: "primary",
    size: "medium",
  },
});

export type ButtonProps = CVA.VariantProps<typeof button>;

export const Button: React.FC<ButtonProps> = ({ intent, size, ...props }) => (
  <button className={button({ intent, size })} {...props} />
);

11ty (with Tailwind)

// button.11ty.js
const { cva } = require("@joebell/cva");

// ⚠️ Disclaimer: Use of Tailwind CSS is optional
const button = cva("button", {
  variants: {
    intent: {
      primary: [
        "bg-blue-500",
        "text-white",
        "border-transparent",
        "hover:bg-blue-600",
      ],
      secondary: [
        "bg-white",
        "text-gray-800",
        "border-gray-400",
        "hover:bg-gray-100",
      ],
    },
    size: {
      small: ["text-sm", "py-1", "px-2"],
      medium: ["text-base", "py-2", "px-4"],
    },
  },
  compoundVariants: [{ intent: "primary", size: "medium", class: "uppercase" }],
  defaultVariants: {
    intent: "primary",
    size: "medium",
  },
});

module.exports = function ({ label, intent, size }) {
  return `<button class="${button({ intent, size })}">${label}</button>`;
};

Svelte

<!-- button.svelte -->
<script lang="ts">
  import { cva } from "@joebell/cva";
  import type * as CVA from "@joebell/cva";

  const button = cva("button", {
    variants: {
      intent: {
        primary: "button--primary",
        secondary: "button--secondary",
      },
      size: {
        small: "button--small",
        medium: "button--medium",
      },
    },
    compoundVariants: [
      { intent: "primary", size: "medium", class: "button--primary-medium" },
    ],
    defaultVariants: {
      intent: "primary",
      size: "medium",
    },
  });

  type ButtonProps = CVA.VariantProps<typeof button>;

  export let intent: ButtonProps["intent"];
  export let size: ButtonProps["size"];
</script>

<button class={button({ intent, size })}><slot /></button>

<style>
  .button { /* … */ }

  .button--primary { /* … */ }
  .button--secondary { /* … */ }

  .button--small { /* … */ }
  .button--medium { /* … */ }

  .button--primary-medium { /* … */ }
</style>

Vue 3

<!-- button.vue -->
<script lang="ts">
import { defineComponent } from "vue";

import { cva } from "@joebell/cva";
import type * as CVA from "@joebell/cva";

const button = cva("button", {
  variants: {
    intent: {
      primary: "button--primary",
      secondary: "button--secondary",
    },
    size: {
      small: "button--small",
      medium: "button--medium",
    },
  },
  compoundVariants: [
    { intent: "primary", size: "medium", class: "button--primary-medium" },
  ],
  defaultVariants: {
    intent: "primary",
    size: "medium",
  },
});

type ButtonProps = CVA.VariantProps<typeof button>;

export default defineComponent({
  props: ["intent" as ButtonProps["intent"], "size" as ButtonProps["size"]],
  methods: {
    button,
  },
});
</script>

<template>
  <button :class="button({ intent, size })">
    <slot></slot>
  </button>
</template>

<style>
.button {
  /* … */
}

.button--primary {
  /* … */
}
.button--secondary {
  /* … */
}

.button--small {
  /* … */
}
.button--medium {
  /* … */
}

.button--primary-medium {
  /* … */
}
</style>