{"id":10708,"library":"cva","title":"Class Variance Authority (CVA)","description":"Class Variance Authority (CVA) is a tiny, TypeScript-first utility library for defining and resolving UI component variants in a structured, type-safe manner. It allows developers to describe base classes and variant-specific classes, handling the runtime resolution based on provided props. CVA supports features like compound variants, default variants, and provides a `VariantProps` utility type for extracting TypeScript prop types. Currently, the stable package is `class-variance-authority`, with version 0.7.1 as of the latest npm publish over a year ago. While the `cva` package name exists, it's a placeholder, and the official project intends to use `cva` as the primary name from v1 onwards. It is framework-agnostic (works with React, Vue, Svelte, plain HTML) and CSS-agnostic (Tailwind CSS, CSS Modules, plain classes), making it highly flexible. Its small bundle size (approx. 1.6 KB minified + gzipped) and lack of runtime style injection are key differentiators against CSS-in-JS solutions, providing full control over stylesheet output.","status":"active","version":"0.0.0","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","placeholder","zce"],"install":[{"cmd":"npm install cva","lang":"bash","label":"npm"},{"cmd":"yarn add cva","lang":"bash","label":"yarn"},{"cmd":"pnpm add cva","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used internally for efficiently combining class names.","package":"clsx","optional":false}],"imports":[{"note":"The main utility function is a named export. While the `cva` package name exists, the actual library is published as `class-variance-authority` (as of v0.x). Using `import { cva } from 'cva'` will likely import the old, placeholder package.","wrong":"import cva from 'class-variance-authority';\nimport { cva } from 'cva';","symbol":"cva","correct":"import { cva } from 'class-variance-authority';"},{"note":"Use `type` import for `VariantProps` to ensure it's removed during compilation, as it's a TypeScript-only utility type.","wrong":"import { VariantProps } from 'class-variance-authority';","symbol":"VariantProps","correct":"import { type VariantProps } from 'class-variance-authority';"},{"note":"For CommonJS, `cva` is a named export from the module object. The primary package is `class-variance-authority`.","wrong":"const cva = require('class-variance-authority');","symbol":"* (CommonJS)","correct":"const { cva } = require('class-variance-authority');"}],"quickstart":{"code":"import { cva, type VariantProps } from 'class-variance-authority';\n\nconst buttonVariants = cva(\n  'inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 disabled:opacity-50 disabled:pointer-events-none',\n  {\n    variants: {\n      intent: {\n        primary: 'bg-blue-600 text-white hover:bg-blue-700',\n        secondary: 'bg-gray-200 text-gray-900 hover:bg-gray-300',\n        danger: 'bg-red-500 text-white hover:bg-red-600',\n      },\n      size: {\n        sm: 'h-9 px-3 py-2',\n        md: 'h-10 px-4 py-2',\n        lg: 'h-11 px-6 py-3',\n      },\n    },\n    compoundVariants: [\n      { intent: 'primary', size: 'md', class: 'uppercase' },\n      { intent: 'secondary', size: 'sm', class: 'font-normal' }\n    ],\n    defaultVariants: {\n      intent: 'primary',\n      size: 'md',\n    },\n  }\n);\n\ntype ButtonProps = VariantProps<typeof buttonVariants>;\n\n// Example usage:\nconsole.log(buttonVariants({ intent: 'primary', size: 'lg' }));\n// Expected output: 'inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 disabled:opacity-50 disabled:pointer-events-none bg-blue-600 text-white hover:bg-blue-700 h-11 px-6 py-3'\n\nconsole.log(buttonVariants({ intent: 'secondary', size: 'sm' }));\n// Expected output: 'inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 disabled:opacity-50 disabled:pointer-events-none bg-gray-200 text-gray-900 hover:bg-gray-300 h-9 px-3 py-2 font-normal'\n\nconsole.log(buttonVariants({}));\n// Expected output (default variants): 'inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 disabled:opacity-50 disabled:pointer-events-none bg-blue-600 text-white hover:bg-blue-700 h-10 px-4 py-2 uppercase'","lang":"typescript","description":"This quickstart demonstrates how to define component variants using `cva` with base classes, distinct variants, compound variants for specific combinations, and default values. It also shows how to extract a type-safe `ButtonProps` interface using `VariantProps` for use in a component's props."},"warnings":[{"fix":"Always `npm install class-variance-authority` (or `yarn add class-variance-authority`). From v1, the package name `cva` is intended to become primary, but verify this in official documentation when upgrading.","message":"The official package name for Class Variance Authority is `class-variance-authority`, not `cva`. The `cva` package on npm is an abandoned placeholder.","severity":"gotcha","affected_versions":"<=0.7.1"},{"fix":"Monitor official CVA documentation and release notes for v1.0.0. When it ships, update your imports from `from 'class-variance-authority'` to `from 'cva'`.","message":"Future versions (specifically v1) are expected to transition the primary npm package name from `class-variance-authority` to `cva`. This will require updating import paths in your codebase.","severity":"breaking","affected_versions":">=1.0.0 (expected)"},{"fix":"Change `import { VariantProps } from 'class-variance-authority';` to `import { type VariantProps } from 'class-variance-authority';`","message":"When using TypeScript, always use `type` import for `VariantProps` to ensure it's stripped from the compiled output.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure you have installed `class-variance-authority` (`npm install class-variance-authority`) and your import statement is `import { cva } from 'class-variance-authority';`.","cause":"Attempting to import from the `cva` package name, which is a placeholder, instead of `class-variance-authority`.","error":"Cannot find module 'cva' or its corresponding type declarations."},{"fix":"Check your `cva` definition to ensure the variant name and its possible values match what you are passing. TypeScript helps catch these at compile time; ensure your editor shows the correct type suggestions.","cause":"Passing an invalid variant value that is not defined in your `cva` configuration, or a typo in the variant name.","error":"Argument of type '{ variant: string; }' is not assignable to parameter of type 'VariantProps<typeof buttonVariants> | undefined'."}],"ecosystem":"npm"}