class-variance-authority

class-variance-authority (CVA) lets you define a component’s visual variants — size, intent, state, and any compound combination of them — as a single declarative config object, then resolves the right class string at call time based on the props passed in. It wraps clsx internally so you still get array/object/conditional class syntax for free, but adds a typed layer on top: TypeScript infers your component’s prop types directly from the variant config via the exported VariantProps helper, so variant names and their allowed values stay in sync between the styling definition and the component’s public API. Originally built for Stitches-style variant ergonomics without a CSS-in-JS runtime, CVA has become the de facto variant-composition primitive behind shadcn/ui and a large share of the Tailwind CSS component ecosystem.

What You Get

• The cva() factory — declare base classes, variants, defaultVariants, and compoundVariants once, get back a function that resolves to a class string per call
• cx — a direct re-export of clsx for plain conditional class concatenation outside of a variant config
• VariantProps<T> — a TypeScript helper that derives a component’s prop types straight from its cva() config, so variant names/values can’t drift out of sync with the component signature
• A class/className escape hatch on every generated function, so callers can always merge in ad-hoc classes on top of the resolved variant output
• Zero CSS-in-JS runtime — output is a plain string, so it works with Tailwind, CSS Modules, vanilla-extract, or hand-written CSS equally well

Common Use Cases

• Defining variant props (size, variant, disabled) for a shadcn/ui-style Button, Badge, or Alert component built on Tailwind CSS
• Sharing one variant config between multiple sibling components (e.g. Button and IconButton) that need consistent size/intent options
• Replacing hand-rolled clsx(…) ternary chains in design-system components with a single declarative config that’s easier to review and extend
• Building framework-agnostic style logic (React, Vue, Svelte, Astro) since cva() returns a plain string and has no framework-specific dependency

Under The Hood

Architecture The core implementation lives entirely in packages/class-variance-authority/src/index.ts (~150 lines), exporting two primitives: cx (a direct re-export of clsx for raw class concatenation) and cva (a curried factory function). Calling cva(base, config) returns a props-accepting function; internally it walks config.variants via Object.keys, resolves each variant’s selected key against props or config.defaultVariants using a falsyToString helper (so false/0 variant keys aren’t coerced away), then reduces config.compoundVariants against the merged props+defaults to append additional classes, finally concatenating everything through clsx (cx) alongside any props.class/props.className escape hatch. There is no internal state, no classes, no external I/O — it’s a pure, synchronous class-string composition pipeline. Types (VariantProps, ConfigSchema, etc.) are isolated in src/types.ts and lean on TypeScript generics/conditional types to give callers compile-time-checked variant props. The repo is a pnpm workspace housing this package plus a parallel v1 rewrite (packages/cva, still in beta) and a docs Astro site (docs/), but the shipped runtime surface of class-variance-authority itself is intentionally minimal.

Tech Stack TypeScript-only source (99.75% per GitHub language stats). Single runtime dependency: clsx (^2.1.1). The build tool is tsdown (a Rolldown-based bundler) producing dual ESM/CJS output plus .d.ts types. Dev tooling includes @arethetypeswrong/core and publint for package-export correctness checks, size-limit enforcing a 1.2KB budget on dist/index.js, TypeScript 6.0.3 for type-checking, and react/react-dom as devDependencies only (used to type-test VariantProps against component prop shapes, not as a runtime dependency). Package manager is pnpm with a workspace tying the core package to the docs site and the parallel v1 rewrite.

Code Quality packages/class-variance-authority/src/index.test.ts is a single but substantial 1766-line test file exercising variant resolution, defaultVariants, compoundVariants (including array-valued compound matching), null-variant overrides, and TypeScript type inference via type-only assertions. The implementation favors small, named helper functions (falsyToString) and explicit reduce/map compositions over cleverness; there are no custom error classes or thrown exceptions because the API can’t fail at runtime — invalid variant keys are caught at the type level rather than checked at runtime, a deliberate zero-runtime-validation design suited to a hot-path styling utility.

API Design The public API is two functions (cx, cva) plus one exported type helper (VariantProps<T>), which keeps the learning curve nearly flat: define variants as a nested object literal, call the returned function with a subset of variant keys, get a class string back. VariantProps<typeof myCva> lets consumers derive component prop types directly from the variant config instead of duplicating them — the library’s signature ergonomic win, and exactly what shadcn/ui-style component libraries lean on. The class/className escape hatch is a small but consistent affordance for merging caller-supplied classes on every call site. Documentation lives off-repo at cva.style (an Astro site checked into docs/) rather than in the README, keeping the README itself terse — good for npm page browsing, though GitHub-only visitors get less immediate context than the docs site provides.