{"id":15851,"library":"tailwind-variant-v3","title":"Tailwind Variant v3","description":"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.","status":"active","version":"0.2.1","language":"javascript","source_language":"en","source_url":"https://github.com/sonofmagic/weapp-tailwindcss","tags":["javascript","typescript"],"install":[{"cmd":"npm install tailwind-variant-v3","lang":"bash","label":"npm"},{"cmd":"yarn add tailwind-variant-v3","lang":"bash","label":"yarn"},{"cmd":"pnpm add tailwind-variant-v3","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for class name merging, specifically version >=2 <3.","package":"tailwind-merge","optional":false},{"reason":"An optional alternative merge adapter for `tailwind-merge` style functionality, requiring explicit installation and injection.","package":"@weapp-tailwindcss/merge-v3","optional":true}],"imports":[{"note":"Primary function to create styled variants. The package is ESM-first.","wrong":"const { tv } = require('tailwind-variant-v3')","symbol":"tv","correct":"import { tv } from 'tailwind-variant-v3'"},{"note":"Utility for merging Tailwind CSS class names using the configured `twMergeAdapter`. ESM-first.","wrong":"const cn = require('tailwind-variant-v3').cn","symbol":"cn","correct":"import { cn } from 'tailwind-variant-v3'"},{"note":"Factory function to pre-inject default configurations and return bound `cn`, `tv`, and `createTV`. It is a named export, not a default.","wrong":"import create from 'tailwind-variant-v3'","symbol":"create","correct":"import { create } from 'tailwind-variant-v3'"},{"note":"Type definition for creating custom `tailwind-merge` style adapters.","symbol":"TailwindMergeAdapter","correct":"import type { TailwindMergeAdapter } from 'tailwind-variant-v3'"}],"quickstart":{"code":"import { cn, tv } from 'tailwind-variant-v3'\n\nconst button = tv({\n  base: 'inline-flex items-center gap-2 font-medium transition-colors',\n  slots: {\n    icon: 'size-4',\n    label: 'truncate'\n  },\n  variants: {\n    tone: {\n      primary: 'bg-blue-500 text-white hover:bg-blue-600',\n      secondary: 'bg-zinc-900 text-zinc-50 hover:bg-zinc-800',\n      ghost: 'bg-transparent text-zinc-900 hover:bg-zinc-100'\n    },\n    size: {\n      sm: { base: 'h-8 px-3 text-xs', icon: 'size-3' },\n      md: { base: 'h-10 px-4 text-sm', icon: 'size-4' },\n      lg: { base: 'h-12 px-6 text-base', icon: 'size-5' }\n    }\n  },\n  defaultVariants: {\n    tone: 'primary',\n    size: 'md'\n  }\n})\n\n// Generate slot classes for a ghost, large button\nconst slots = button({ tone: 'ghost', size: 'lg' })\n\n// Access individual slot classes\nconst baseClasses = slots.base() // Example: 'inline-flex items-center gap-2 font-medium transition-colors h-12 px-6 text-base'\nconst iconClasses = slots.icon({ class: 'text-xl' }) // Example: 'size-5 text-xl'\n\n// Use cn for general class merging\nconst combinedClasses = cn('flex', ['text-sm', 'md:text-lg'])({ twMerge: true })\n\nconsole.log('Base Classes:', baseClasses)\nconsole.log('Icon Classes:', iconClasses)\nconsole.log('Combined Classes:', combinedClasses)\n","lang":"typescript","description":"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."},"warnings":[{"fix":"For Tailwind CSS v4, migrate to the appropriate `tailwind-variant-v4` or similar package provided by the monorepo for v4 compatibility.","message":"This 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.","severity":"breaking","affected_versions":"*"},{"fix":"Install `tailwind-merge` in your project: `npm install tailwind-merge@^2` or `pnpm add tailwind-merge@^2` or `yarn add tailwind-merge@^2`.","message":"The package has a peer dependency on `tailwind-merge` (specifically `^2`). This dependency is not automatically installed and must be added manually to your project.","severity":"gotcha","affected_versions":"*"},{"fix":"Install the desired adapter (e.g., `npm install @weapp-tailwindcss/merge-v3`) and pass it via `twMergeAdapter` in your `tv` or `create` configuration.","message":"When 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.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Run `npm install tailwind-merge@^2` (or `pnpm add` / `yarn add`) in your project directory.","cause":"`tailwind-merge` is a peer dependency of `tailwind-variant-v3` and must be installed manually.","error":"Cannot find module 'tailwind-merge'"},{"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'`.","cause":"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.","error":"TypeError: (0 , tailwind_variant_v3__WEBPACK_IMPORTED_MODULE_0__.tv) is not a function"},{"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.","cause":"Type mismatch or incorrect implementation provided when attempting to inject a custom `TailwindMergeAdapter` for `tailwind-merge`.","error":"Argument of type '{ twMergeAdapter: TailwindMergeAdapter; }' is not assignable to parameter of type '...'"}],"ecosystem":"npm"}