{"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,"search_vec":"'0.7.1':81 '1.6':148 'agnost':121,132 'ago':91 'allow':32 'approx':147 'author':3,7,78 'base':36,47 'bundl':145 'class':1,5,37,42,76,138 'class-variance-author':75 'compon':22 'compound':55 'control':169 'css':131,134,135,163 'css-agnost':130 'css-in-j':162 'current':70 'cva':4,8,51,94,109 'default':57 'defin':18 'describ':35 'develop':33 'differenti':160 'exist':97 'extract':66 'featur':53 'first':14 'flexibl':142 'framework':120 'framework-agnost':119 'full':168 'gzip':151 'handl':43 'high':141 'html':128 'inject':157 'intend':106 'javascript':173 'js':165 'kb':149 'key':159 'lack':153 'latest':85 'librari':16 'like':54 'make':139 'manner':30 'minifi':150 'modul':136 'name':96,113 'npm':86 'offici':104 'onward':116 'output':172 'packag':73,95 'placehold':101,174 'plain':127,137 'primari':112 'project':105 'prop':50,68 'provid':49,60,167 'publish':87 'react':124 'resolut':46 'resolv':20 'runtim':45,155 'safe':29 'size':146 'small':144 'solut':166 'specif':41 'stabl':72 'structur':26 'style':156 'stylesheet':171 'support':52 'svelt':126 'tailwind':133 'tini':11 'type':28,64,69 'type-saf':27 'typescript':13,67 'typescript-first':12 'ui':21 'use':108 'util':15,63 'v1':115 'varianc':2,6,77 'variant':23,40,56,58 'variant-specif':39 'variantprop':62 'version':80 'vue':125 'work':122 'year':90 'zce':175","created_at":"2026-04-19T13:34:12.944219+00:00","updated_at":"2026-04-19T13:34:12.944219+00:00","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","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.9.5","cli_name":"","cli_version":null,"type":"library","homepage":"https://cva.style","github":null,"docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/cva","openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}