Registry / web-framework / tailwind-variants

tailwind-variants

library3.2.2jsnpmunverified

tailwind-variants is a library that extends Tailwind CSS with a powerful, first-class variant API, enabling developers to define component styles based on states, sizes, and other properties. It supports features like slots, composition, compound variants, and automatic conflict resolution via `tailwind-merge`. The library is fully typed for enhanced developer experience and is framework-agnostic. Currently at version 3.2.2, it sees active development with frequent minor and patch releases, addressing bugs and introducing new utilities like `cx` and `cnMerge`. A key differentiator is its dual build approach (original with `tailwind-merge` and a lighter-weight `/lite` version without it) and its performance optimizations, offering significant speed improvements in v3.

web-framework serialization http-networking

npm install tailwind-variants

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · TAILWIND-VARIANTS

tailwind-variants

web-frameworkjavascriptv3.2.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

✓ import { tv } from 'tailwind-variants'

✗ const tv = require('tailwind-variants')

The primary function to create variant definitions. For ESM, use `import`. CommonJS `require` is generally discouraged since modern versions are ESM-first.

tv (lite build)

✓ import { tv } from 'tailwind-variants/lite'

✗ import { tv } from 'tailwind-variants'

Introduced in v3 for a smaller bundle size by excluding `tailwind-merge`. Use this if you don't need automatic conflict resolution.

✓ import { cn } from 'tailwind-variants'

✗ import { cn } from 'tailwind-variants/lite' // If tailwind-merge conflict resolution is needed; cn in /lite does not merge conflicting classes. cn('px-2', 'px-4')({ twMerge: false }) // Incorrect usage since v3.2.2, cn no longer accepts config.

Utility for concatenating and merging class names with *default* `tailwind-merge` config. In v3.2.2+, `cn` returns a string directly and no longer accepts configuration arguments.

✓ import { cx } from 'tailwind-variants'

✗ import { cnBase } from 'tailwind-variants'

Lightweight utility for simple class name concatenation *without* `tailwind-merge` conflict resolution (similar to `clsx`). Added in v3.2.0, replaces `cnBase`. Available in both original and `/lite` builds.

cnMerge

✓ import { cnMerge } from 'tailwind-variants'

Utility for concatenating and merging class names with *custom* `tailwind-merge` configuration. Introduced in v3.2.2.

VariantProps

✓ import type { VariantProps } from 'tailwind-variants'

✗ import { VariantProps } from 'tailwind-variants'

TypeScript type utility to extract variant props from a `tv` component definition. Use `type` import for clarity and to ensure it's removed during transpilation.

This quickstart demonstrates defining a reusable button component with multiple variants for size, color, and full-width state, along with compound variants and default values. It showcases how to apply these variants to generate dynamic Tailwind CSS class strings.

import { tv } from 'tailwind-variants'; // Define a button component with variants const button = tv({ base: "font-medium bg-blue-500 text-white rounded-full active:opacity-80", variants: { color: { primary: "bg-blue-500 text-white", secondary: "bg-purple-500 text-white", danger: "bg-red-500 text-white" }, size: { sm: "text-sm px-3 py-1", md: "text-base px-4 py-2", lg: "px-5 py-3 text-lg" }, fullWidth: { true: "w-full", false: "inline-block" } }, compoundVariants: [ { // Example of combining size and color size: ['sm', 'md'], color: 'primary', class: 'border border-blue-700' } ], defaultVariants: { size: "md", color: "primary", fullWidth: false } }); // Usage in a functional component (e.g., React) function MyButton({ size, color, fullWidth, children }) { return ( <button className={button({ size, color, fullWidth })}> {children} </button> ); } // Example rendering the button (conceptually) console.log(button()); // Renders default: "font-medium bg-blue-500 text-white rounded-full active:opacity-80 text-base px-4 py-2" console.log(button({ size: "sm", color: "secondary" })); // Renders: "font-medium bg-purple-500 text-white rounded-full active:opacity-80 text-sm px-3 py-1" console.log(button({ size: "lg", color: "danger", fullWidth: true })); // Renders: "font-medium bg-red-500 text-white rounded-full active:opacity-80 px-5 py-3 text-lg w-full"

Debug

Known issues

breakingIn v1.0.0, the `responsiveVariants` option and the `withTv` helper were removed. `responsiveVariants` was removed due to Tailwind CSS v4 no longer supporting `config.content.transform`.

fix

Remove `responsiveVariants` and `withTv` usage. For responsive variants, add them manually to your class names.

affects: >=1.0.0

breakingFrom v2.0.0, `tailwind-merge` became an *optional* peer dependency. It is no longer bundled by default with `tailwind-variants` to reduce bundle size for users who don't need conflict resolution. If you relied on automatic conflict resolution, you must install `tailwind-merge` separately.

fix

If you require automatic conflict resolution, explicitly install `tailwind-merge`: `npm install tailwind-merge`. For custom configurations, use `cnMerge`.

affects: >=2.0.0

breakingStarting from v3.0.0, `tailwind-variants` introduced two build options: the original build (which includes `tailwind-merge` if installed) and a `/lite` build that completely excludes `tailwind-merge` for a smaller bundle. The `createTV`, `tv`, and `cn` functions from the `/lite` build no longer accept `tailwind-merge` configuration options.

fix

Choose the appropriate import: `import { tv } from 'tailwind-variants'` for default behavior with `tailwind-merge`, or `import { tv } from 'tailwind-variants/lite'` for a smaller bundle without conflict resolution capabilities. Adjust usage to avoid passing `tailwind-merge` config to `/lite` imports.

affects: >=3.0.0

breakingIn v3.2.0, the `cnBase` utility function was deprecated and replaced by `cx`. `cnBase` provided simple concatenation without conflict resolution.

fix

Replace all instances of `cnBase` with `cx`. The API remains identical.

affects: >=3.2.0

breakingIn v3.2.2, the `cn` function was refactored. It now directly returns a string with default `tailwind-merge` conflict resolution and no longer accepts configuration arguments (e.g., `cn('px-2', 'px-4')({ twMerge: false })`). This configurability was moved to the new `cnMerge` function.

fix

If you were calling `cn` with configuration arguments, migrate to `cnMerge`. For simple merging with default config, `cn` usage remains largely the same, just without the `()` call for configuration.

affects: >=3.2.2

gotchaCompatibility between `tailwind-variants`, `tailwind-merge`, and `tailwindcss` versions is crucial. `tailwind-variants` v1.x+ supports Tailwind CSS v4.x (requiring `tailwind-merge` v3.x). If using Tailwind CSS v3.x, `tailwind-variants` v0.x with `tailwind-merge` v2.6.0 is required.

fix

Always check the compatibility notes in the `tailwind-variants` README or documentation when installing or upgrading. Ensure `tailwind-merge` and `tailwindcss` versions align with the recommended `tailwind-variants` version.

affects: *

Errors

Common errors & fixes

TypeError: (0, tv__WEBPACK_IMPORTED_MODULE_0__.tv) is not a function

Attempting to use `tailwind-variants` with CommonJS `require()` syntax in an ESM project, or incorrect import statement in an ESM project.

fix

Ensure you are using `import { tv } from 'tailwind-variants'` (or `/lite`) for ESM modules. If in a mixed environment, check your build configuration to ensure ESM is handled correctly.

Conflicting Tailwind classes are not being merged or resolved (e.g., 'px-2 px-4' instead of 'px-4').

`tailwind-merge` is either not installed, or you are using the `/lite` build of `tailwind-variants`, which intentionally excludes `tailwind-merge`.

fix

If you need conflict resolution, ensure `tailwind-merge` is installed (`npm install tailwind-merge`) and that you are importing from the default `tailwind-variants` entry point (not `/lite`). If using `/lite`, handle conflicts manually or switch to the full build.

Property 'twMerge' does not exist on type '(...args: ClassValue[]) => string' (or similar TypeScript error when passing config to `cn`).

Attempting to pass a configuration object to the `cn` function in `tailwind-variants` v3.2.2+, which no longer accepts it.

fix

For custom `tailwind-merge` configurations, use the `cnMerge` function introduced in v3.2.2. If no custom config is needed, simply call `cn` without arguments: `cn('px-2', 'px-4')` instead of `cn('px-2', 'px-4')()`.

Module not found: Error: Can't resolve 'tailwind-variants/transformer'

You might be attempting to use the `withTV` utility which was part of `tailwind-variants` v0.x and used for Tailwind CSS config transformation. This was removed in v1.0.0.

fix

Remove `withTV` from your `tailwind.config.js` or any other configuration files. `tailwind-variants` v1.0.0+ no longer requires this transformer due to changes in Tailwind CSS v4.

Upgrade

Version history

3.2.2latest on npm

Audit

Dependencies

tailwind-mergeoptionalOptional peer dependency for automatic Tailwind CSS class conflict resolution. Required for the default build, but not for the `/lite` build.

tailwindcssrequiredCore dependency as `tailwind-variants` extends Tailwind CSS functionality.

Agent activity

8 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/heroui-inc/tailwind-variants ↗

packagehttps://www.npmjs.com/package/tailwind-variants ↗

homepagehttps://tailwind-variants.org ↗