Registry / web-framework / tailwind-variant-v3

tailwind-variant-v3

library0.2.1jsnpmunverified

The `tailwind-variant-v3` package is a runtime variant utility specifically designed for Tailwind CSS v3, offering a TypeScript-first approach for defining and managing UI component styles. It is part of the `weapp-tailwindcss` monorepo, which integrates Tailwind CSS into WeChat Mini Programs and similar environments. The current stable version is `0.2.1`. Key features include composable variants (supporting `base`, `slots`, `variants`, `compoundVariants`, `compoundSlots`), responsive variant definitions, and deep integration with `tailwind-merge` for robust class name collision resolution. It provides `cn` and `cnBase` utilities and allows for custom `twMergeConfig` and pluggable `twMergeAdapter` implementations for alternative merging libraries. Slot caching is also incorporated to optimize performance. Users must manually install `tailwind-merge@^2` as a peer dependency. For projects using Tailwind CSS v4, it is explicitly recommended to use a corresponding v4 runtime variant solution.

web-framework serialization

npm install tailwind-variant-v3

github ↗package ↗

INSTALL

IMPORT

SIG · TAILWIND-VARIANT-V

tailwind-variant-v3

web-frameworkjavascriptv0.2.1

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-variant-v3'

✗ const { tv } = require('tailwind-variant-v3')

Primary function to create styled variants. The package is ESM-first.

✓ import { cn } from 'tailwind-variant-v3'

✗ const cn = require('tailwind-variant-v3').cn

Utility for merging Tailwind CSS class names using the configured `twMergeAdapter`. ESM-first.

create

✓ import { create } from 'tailwind-variant-v3'

✗ import create from 'tailwind-variant-v3'

Factory function to pre-inject default configurations and return bound `cn`, `tv`, and `createTV`. It is a named export, not a default.

TailwindMergeAdapter

✓ import type { TailwindMergeAdapter } from 'tailwind-variant-v3'

Type definition for creating custom `tailwind-merge` style adapters.

This quickstart demonstrates how to define a button component using `tv` with base styles, slots, variants, and default variants. It then shows how to generate and access specific slot classes and how to use the `cn` utility for merging arbitrary class names.

import { cn, tv } from 'tailwind-variant-v3' const button = tv({ base: 'inline-flex items-center gap-2 font-medium transition-colors', slots: { icon: 'size-4', label: 'truncate' }, variants: { tone: { primary: 'bg-blue-500 text-white hover:bg-blue-600', secondary: 'bg-zinc-900 text-zinc-50 hover:bg-zinc-800', ghost: 'bg-transparent text-zinc-900 hover:bg-zinc-100' }, size: { sm: { base: 'h-8 px-3 text-xs', icon: 'size-3' }, md: { base: 'h-10 px-4 text-sm', icon: 'size-4' }, lg: { base: 'h-12 px-6 text-base', icon: 'size-5' } } }, defaultVariants: { tone: 'primary', size: 'md' } }) // Generate slot classes for a ghost, large button const slots = button({ tone: 'ghost', size: 'lg' }) // Access individual slot classes const baseClasses = slots.base() // Example: 'inline-flex items-center gap-2 font-medium transition-colors h-12 px-6 text-base' const iconClasses = slots.icon({ class: 'text-xl' }) // Example: 'size-5 text-xl' // Use cn for general class merging const combinedClasses = cn('flex', ['text-sm', 'md:text-lg'])({ twMerge: true }) console.log('Base Classes:', baseClasses) console.log('Icon Classes:', iconClasses) console.log('Combined Classes:', combinedClasses)

Debug

Known issues

breakingThis package (`tailwind-variant-v3`) is specifically designed for Tailwind CSS v3. If you are using Tailwind CSS v4, you must use the corresponding v4 runtime variant solution to avoid compatibility issues.

fix

For Tailwind CSS v4, migrate to the appropriate `tailwind-variant-v4` or similar package provided by the monorepo for v4 compatibility.

affects: *

gotchaThe package has a peer dependency on `tailwind-merge` (specifically `^2`). This dependency is not automatically installed and must be added manually to your project.

fix

Install `tailwind-merge` in your project: `npm install tailwind-merge@^2` or `pnpm add tailwind-merge@^2` or `yarn add tailwind-merge@^2`.

affects: *

gotchaWhen using an alternative merge adapter, such as `@weapp-tailwindcss/merge-v3`, you must manually install it and then explicitly inject it into `tv` or `create` using the `twMergeAdapter` option.

fix

Install the desired adapter (e.g., `npm install @weapp-tailwindcss/merge-v3`) and pass it via `twMergeAdapter` in your `tv` or `create` configuration.

affects: *

Errors

Common errors & fixes

Cannot find module 'tailwind-merge'

`tailwind-merge` is a peer dependency of `tailwind-variant-v3` and must be installed manually.

fix

Run `npm install tailwind-merge@^2` (or `pnpm add` / `yarn add`) in your project directory.

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

This package is ESM-first. This error typically occurs when attempting to use CommonJS `require()` syntax or incorrect destructuring in an environment that expects ESM.

fix

Ensure your project's `tsconfig.json` and `package.json` are configured for ES Modules (e.g., `"type": "module"`, `"module": "ESNext"`) and use `import { tv, cn } from 'tailwind-variant-v3'`.

Argument of type '{ twMergeAdapter: TailwindMergeAdapter; }' is not assignable to parameter of type '...'

Type mismatch or incorrect implementation provided when attempting to inject a custom `TailwindMergeAdapter` for `tailwind-merge`.

fix

Ensure that the `TailwindMergeAdapter` type is correctly imported and that the `twMerge` and `extendTailwindMerge` functions from your chosen merge library (e.g., `@weapp-tailwindcss/merge-v3`) are correctly provided to the adapter object.

Upgrade

Version history

0.2.1latest on npm

Audit

Dependencies

tailwind-mergerequiredRequired peer dependency for class name merging, specifically version >=2 <3.

@weapp-tailwindcss/merge-v3optionalAn optional alternative merge adapter for `tailwind-merge` style functionality, requiring explicit installation and injection.

Agent activity

14 hits · last 30 days

node

Resources

githubhttps://github.com/sonofmagic/weapp-tailwindcss ↗

packagehttps://www.npmjs.com/package/tailwind-variant-v3 ↗