{"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,"search_vec":"'0.2.1':59 '2':121 'allow':94 'also':109 'altern':103 'approach':26 'base':66 'cach':107 'class':83 'cn':89 'cnbase':91 'collis':85 'compon':32 'compos':63 'compoundslot':70 'compoundvari':69 'correspond':139 'css':19,46,130 'current':55 'custom':96 'deep':75 'defin':28 'definit':73 'depend':125 'design':16 'environ':53 'explicit':134 'featur':61 'first':25 'implement':101 'includ':62 'incorpor':110 'instal':117 'integr':44,76 'javascript':144 'key':60 'librari':105 'manag':30 'manual':116 'merg':80,104,120 'mini':49 'monorepo':42 'must':115 'name':84 'offer':21 'optim':112 'packag':9 'part':36 'peer':124 'perform':113 'pluggabl':99 'program':50 'project':127 'provid':88 'recommend':135 'resolut':86 'respons':71 'robust':82 'runtim':12,141 'similar':52 'slot':67,106 'solut':143 'specif':15 'stabl':56 'style':33 'support':65 'tailwind':1,6,18,45,79,119,129 'tailwind-merg':78,118 'tailwind-variant-v3':5 'tailwindcss':41 'twmergeadapt':100 'twmergeconfig':97 'typescript':24,145 'typescript-first':23 'ui':31 'use':128,137 'user':114 'util':14,92 'v3':3,8,20 'v4':131,140 'variant':2,7,13,64,68,72,142 'version':57 'weapp':40 'weapp-tailwindcss':39 'wechat':48","created_at":"2026-04-21T18:00:19.826780+00:00","updated_at":"2026-04-21T18:00:19.826780+00:00","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","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/sonofmagic/weapp-tailwindcss","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/tailwind-variant-v3","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-20","install_tag":null}}