repository·main·Indexed 25 days ago
https://github.com/heroui-inc/tailwind-variantsA fully typed, framework-agnostic variant API for Tailwind CSS supporting slots, composition, and built-in conflict resolution. It provides the tv() function for creating variant-aware components, createTV() for custom configurations, and utility functions like cx(), cn(), and cnMerge() for class name manipulation. A lite version is available via tailwind-variants/lite for smaller bundle sizes without built-in conflict resolution.
You can install tailwind-variants using npm, yarn, or pnpm.
For a smaller bundle size without built-in conflict resolution, import from tailwind-variants/lite instead of the default entry point.
npm i tailwind-variants
# or
yarn add tailwind-variants
# or
pnpm add tailwind-variantsThe benchmark suite measures the performance of the built tailwind-variants package. It compares the current version against the latest released version of tailwind-variants and the latest version of class-variance-authority (CVA). It also compares utility functions like cx, cn, and cnMerge against alternatives like clsx, twJoin, and cnfast.
To run the full benchmark suite:
pnpm benchmarkTo run a fast smoke test (note: this is not suitable for making performance claims):
pnpm benchmark --quickTo disable ANSI colors in the terminal output, set the NO_COLOR=1 environment variable.
When configuring tailwind-variants, you can control how Tailwind CSS class conflicts are resolved using the twMerge and twMergeConfig properties.
twMerge: A boolean that determines whether to merge conflicting Tailwind classes. Defaults to true.twMergeConfig: An object used to pass custom configuration to the underlying tailwind-merge engine. It supports extend and override patterns for merging configurations, making it compatible with standard tailwind-merge extension shapes.The benchmark suite follows specific rules to ensure accuracy:
tailwind-variants are imported from their built dist/index.js entry points.tailwind-merge version. Equivalent workloads are guaranteed to produce identical output before measurement begins.tailwind-merge configuration runs in a separate final phase because the TV merger cache is process-global.cx utility function is exported from the lite entrypoint and can be used directly for basic class name concatenation and merging.tv and createTV for defining variants and cn for class name merging. These functions are optimized for minimal overhead.cn function allows you to merge class names. It returns a function that can optionally accept a configuration object. If no classes are provided or they result in an empty string, it returns undefined.Use these utilities to handle nested arrays:
flatArray<T>(arr: unknown[]): T[]: Flattens a single array of unknown depth into a flat array of type T.flatMergeArrays<T>(...arrays: unknown[][]): T[]: Flattens multiple arrays into a single flat array and filters out falsy values.cx function is a utility for joining class names. It accepts various inputs (strings, objects, arrays, etc.) and returns a normalized, single string of class names. It automatically handles whitespace normalization and removes extra spaces.createTV function returns a new tv instance (of type TVLite), allowing you to generate fresh variant factory functions.The mergeObjects function performs a deep merge of two objects.
flatMergeArrays.joinObjects function merges two objects. If a key exists in both objects, it uses cx() to merge their values (useful for merging Tailwind class strings). If a key exists only in one, it is preserved.