API Reference

cva

Builds a cva component

import { cva } from "cva";

const component = cva(options);

Parameters

1. options
   • base: the base class name (string, string[] or other clsx value)
   • variants: your variants schema. A variant name prefixed with _ is internal: hidden from the component’s props type and from getSchema, but still settable via defaultVariants and matchable in compoundVariants
   • compoundVariants: variants based on a combination of previously defined variants
   • defaultVariants: set default values for previously defined variants
   • composes: shallow merge one or more other cva components into this one, as a single component or an array (see Composing Components)

Returns

A cva component function

cx

Concatenates class names (an alias of clsx)

import { cx } from "cva";

const className = cx(classes);

Parameters

• classes: array of classes to be concatenated (see clsx usage)

Returns

string

getSchema

Extracts a plain-object schema (variant names, possible values, and default values) from a cva component. Use it to generate Storybook controls, documentation, or any other UI that reads a component’s variants without re-declaring them. See Utilities for use cases.

import { cva, getSchema } from "cva";

const button = cva({
  base: "button",
  variants: {
    intent: {
      primary: "button--primary",
      secondary: "button--secondary",
    },
    disabled: {
      true: "button--disabled",
      false: "button--enabled",
    },
  },
  defaultVariants: {
    intent: "primary",
    disabled: false,
  },
});

getSchema(button);
// => {
//   intent: { values: ["primary", "secondary"], defaultValue: "primary" },
//   disabled: { values: [true, false], defaultValue: false },
// }

getSchema omits a variant that has no values (e.g. variants: { empty: {} }) and any internal (_-prefixed) variant.

Parameters

component: a component created by cva (including components composed via composes)

Returns

An object keyed by variant name. Each entry has:

• values: a readonly array of the variant’s possible values
• defaultValue: present only if the variant has a defaultVariants entry

defineConfig

Generate cva and cx functions based on your preferred configuration.

Store in a cva.config.ts file, and import across your project.

cva.config.ts

import { defineConfig } from "cva";

export const { cva, cx } = defineConfig(options);

1. options
   • hooks
     • onComplete: returns a concatenated class string of all classes passed to cx or cva.

defineConfig also returns a deprecated compose function for migrating from class-variance-authority; use the composes property on cva instead. See What’s new?.