CVA (Class Variance Authority)

Since cva does not provide a built-in way to mark variants as required, you should use TypeScript utility types like Omit, Pick, and Required to enforce specific variant props in your component's interface.

To make a variant required:

1. Extract all variant props using VariantProps.
2. Use Omit to remove the variant from the base props.
3. Use Pick and Required to re-add the variant as a mandatory field.
4. Extend your component's interface with these combined types.

import { cva, type VariantProps } from "class-variance-authority";

export const buttonVariants = cva("…", {
  variants: {
    optional: { a: "…", b: "…" },
    required: { a: "…", b: "…" },
  },
});

export type ButtonVariantProps = VariantProps<typeof buttonVariants>;

/**
 * Button
 */
export interface ButtonProps
  extends
    Omit<ButtonVariantProps, "required">,
    Required<Pick<ButtonVariantProps, "required">> {}

export const button = (props: ButtonProps) => buttonVariants(props);

// ✅ Correct usage:
button({ required: "a" });

// ❌ TypeScript Error:
// Property "required" is missing in type "{}" but required in type "ButtonProps".
button({});

You can merge one or more cva components into a single component using the composes property. This allows you to build complex components by shallowly merging base styles and variants from existing cva definitions. You can pass a single component directly or an array of multiple components.

Important: Pass components to composes as an inline array literal or one marked as const. Using a pre-declared, mutable array variable (e.g., const list = [a, b]) will cause the loss of tuple inference, which can lead to incorrect or missing variant types in the resulting component.

import { cva, type VariantProps } from "cva";

const box = cva({
  base: "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,
  },
});

const root = cva({
  base: "card rounded border-solid border-slate-300",
  variants: {
    shadow: {
      md: "drop-shadow-md",
      lg: "drop-shadow-lg",
      xl: "drop-shadow-xl",
    },
  },
});

// Compose the components
export const card = cva({ composes: [box, root] });
export interface CardProps extends VariantProps<typeof card> {}

// Usage
card({ margin: 2, shadow: "md" });
// => "box box-border m-2 p-0 card rounded border-solid border-slate-300 drop-shadow-md"

card({ margin: 2, shadow: "md", class: "adhoc-class" });
// => "box box-border m-2 p-0 card rounded border-solid border-slate-300 drop-shadow-md adhoc-class"

Since cva does not have a built-in method for composing components, you can extend and concatenate multiple cva instances using the cx utility.

To do this:

1. Define your base components using cva.
2. Extract their variant types using VariantProps.
3. Create a new component function that accepts the combined props and returns the result of cx() applied to all base components.

Note: If you are using cva@beta, first-class composition is available via the composes property.

import type { VariantProps } from "class-variance-authority";
import { cva, cx } from "class-variance-authority";

/**
 * Base component 1
 */
export type BoxProps = 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,
  },
});

/**
 * Base component 2
 */
type CardBaseProps = 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",
    },
  },
});

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

Prefixing a variant name with an underscore (e.g., _intent) marks it as an internal variant. Internal variants are available for use in the cva function and can be used in defaultVariants or compoundVariants, but they are automatically omitted from the types generated by VariantProps and the schema from getSchema. This is useful for managing component state internally without exposing those options to the public API.

import { cva, type VariantProps } from "cva";

const button = cva({
  base: "button",
  variants: {
    _intent: { primary: "button--primary", secondary: "button--secondary" },
    size: { small: "button--small", medium: "button--medium" },
  },
  defaultVariants: {
    _intent: "primary",
    size: "medium",
  },
});

// _intent is omitted from ButtonProps
interface Props
  extends
    React.ButtonHTMLAttributes<HTMLButtonElement>,
    VariantProps<typeof button> {
  active?: boolean;
}

function Button({ active, size, className, ...props }: Props) {
  return (
    <button
      className={button({
        size,
        _intent: active ? "primary" : "secondary",
        class: className,
      })}
      {...props}
    />
  );
}