A type-safe variant styling API for Tailwind CSS — a faster drop-in replacement for tailwind-variants, for anyone
building components whose classes depend on props.
Overview
@codefast/tv turns one configuration into a typed function that returns the right Tailwind classes for a set of props.
Describe your base, variants, and slots once; call the function with props; get back a merged class string. It's a
drop-in, faster replacement for tailwind-variants, with the same configuration shape.
tv() costs next to nothing. The first calls resolve straight from the configuration, the next compiles it into a plan,
and from then on resolving a component is string work — with a repeated selection answered from a cache.
- One configuration, one typed function. Describe
base,variants,compoundVariants,slots, anddefaultVariantsonce; get back a function whose props are inferred from it. - Conflicts settled by
cn. A caller'sclassNamewins over the configuration, and an unknown variant value is a type error. - Compiled once, when it pays.
tv()only wraps the configuration; the first renders read it directly — two for a component without slots, one with them — and the next compiles it into a plan, so a component rendered that few times costs no more than those renders, and every render after is string work with repeated selections answered from a cache. - Drop-in, with no runtime dependencies of its own. Same configuration shape as
tailwind-variants; the merge engine,cn, is a peer, so you get one copy at the version you chose.
Installation
pnpm add @codefast/tv cn
# npm install @codefast/tv cn
# yarn add @codefast/tv cn@codefast/tv ships ESM only. cn is a peer dependency (>=0.5.0), and the package runs on Node.js 24.15 or later and
in Chrome and Edge 136, Firefox 136, or Safari 18.4 or later (support policy). It requires
TypeScript 7 or later for its types. It's published on 0.x and versioned on its own track: breaking changes ship as
minor versions, so pin the minor version when you need stability.
Quick start
import { tv } from "@codefast/tv";
const button = tv({
base: "inline-flex items-center justify-center rounded-md font-medium",
variants: {
variant: { primary: "bg-primary text-primary-foreground", outline: "border border-input bg-background" },
size: { sm: "h-9 px-3 text-sm", md: "h-10 px-4", lg: "h-11 px-8" },
},
defaultVariants: { variant: "primary", size: "md" },
});
button();
// => "inline-flex items-center justify-center rounded-md font-medium bg-primary text-primary-foreground h-10 px-4"
button({ variant: "outline", size: "lg" });
// => "... border border-input bg-background h-11 px-8"
button({ size: "sm", className: "w-full" });
// => "... bg-primary text-primary-foreground h-9 px-3 text-sm w-full"Every call accepts className, or class, for ad-hoc additions. They are appended last, so they win any Tailwind
conflict with the configuration; when both are passed, className is used, on a call, a slot and a compound entry
alike. A resolution with no classes at all returns "".
A variant value is read as its group key: a number and its string spelling select the same key (cols: 1 or
cols: "1"), "" reads as false, and null, an array or an object selects nothing. Only an omitted or undefined
value falls back to defaultVariants.
Variants
Boolean variants
A variant group with "true" / "false" keys accepts real booleans. When such a group has no entry in
defaultVariants, it defaults to false:
const toggle = tv({
base: "rounded-md text-sm",
variants: {
pressed: { true: "bg-accent", false: "bg-transparent" },
disabled: { true: "pointer-events-none opacity-50" },
},
});
toggle(); // => "rounded-md text-sm bg-transparent"
toggle({ pressed: true, disabled: true });
// => "rounded-md text-sm bg-accent pointer-events-none opacity-50"Compound variants
compoundVariants apply extra classes only when all listed conditions match. A condition value may be an array,
matching any of its entries, and undefined, null and false match one another, so a condition on false also holds
for an omitted boolean variant:
const alert = tv({
base: "rounded-lg border px-4 py-3",
variants: {
variant: { default: "bg-background", destructive: "text-destructive" },
size: { sm: "text-sm", md: "text-base" },
},
compoundVariants: [{ variant: "destructive", size: ["sm", "md"], className: "font-semibold" }],
defaultVariants: { variant: "default", size: "md" },
});
alert({ variant: "destructive" });
// => "rounded-lg border px-4 py-3 text-destructive text-base font-semibold"Slots
Add slots to style a multi-part component. The variant function then returns an object of per-slot functions. A
variant value can be a plain class string (applied to the base slot) or a slot-to-class map:
const card = tv({
slots: {
root: "rounded-xl border bg-card shadow-sm",
header: "flex flex-col gap-1.5 p-6",
content: "p-6 pt-0",
},
variants: { inset: { true: { content: "px-3" } } },
});
const styles = card({ inset: true });
styles.root(); // => "rounded-xl border bg-card shadow-sm"
styles.content(); // => "p-6 pt-0 px-3"
styles.content({ className: "pb-0" }); // => "p-6 pt-0 px-3 pb-0" — merged per slotEach slot function also accepts variant props of its own, which override the values given at the top-level call for that
slot only; a variant left null or undefined there keeps the call's selection, and compound variants and compound
slots test the slot's own props before the call's. In a slot configuration, a compound variant's class or className
may be a slot map.
Compound slots
compoundSlots target several slots at once, optionally gated on variant conditions:
const pagination = tv({
slots: { item: "flex flex-wrap", prev: "", next: "" },
variants: { size: { sm: "", md: "" } },
compoundSlots: [
{ slots: ["item", "prev", "next"], className: "size-9 rounded-md" },
{ slots: ["item", "prev", "next"], size: "sm", className: "size-7 text-xs" },
],
defaultVariants: { size: "md" },
});
pagination({ size: "sm" }).item();
// => "flex flex-wrap rounded-md size-7 text-xs"Extending
extend inherits another variant function's configuration and merges the child's onto it the way upstream does. What
both declare joins, the parent's classes first: the base (a slot parent's base slot included), each variant value,
and each slot or slot-map entry. Defaults merge with the child's winning, compound variants and compound slots
concatenate with the parent's first, and a child's compoundSlots apply without redeclaring slots. The child's
variant names come first, so its variants' classes are emitted before the parent's. The resulting types reflect the
union, and a chain of any depth collapses into one configuration when tv() runs:
const baseButton = tv({
base: "inline-flex items-center rounded-md",
variants: { size: { sm: "h-9 px-3", md: "h-10 px-4" } },
defaultVariants: { size: "md" },
});
const iconButton = tv({
extend: baseButton,
base: "aspect-square",
variants: { tone: { ghost: "hover:bg-accent", outline: "border border-input" } },
defaultVariants: { tone: "ghost" },
});
iconButton();
// => "inline-flex items-center rounded-md aspect-square hover:bg-accent h-10 px-4"
iconButton({ tone: "outline", size: "sm" });
// => "inline-flex items-center rounded-md aspect-square border border-input h-9 px-3"
const compactButton = tv({ extend: baseButton, variants: { size: { sm: "text-xs" } } });
compactButton({ size: "sm" });
// => "inline-flex items-center rounded-md h-9 px-3 text-xs" — the redeclared value joins the parent'sOptions and createTV
tv(config, options) takes an optional second argument:
twMerge— how conflicts are resolved:truemerges withcn'stwMerge(the default),falsekeeps every declared class, and a function(classes: string) => stringreplaces the merge —extendTailwindMerge(…)fromcn/configfor custom class groups, or another engine.cacheResolutions— setfalseto resolve every call from scratch (defaulttrue).
A variant function remembers what each selection resolved to, because a list renders the same few selections many times and both the plan walk and the merge are pure functions of the selection. Two consequences are worth knowing:
- Once its plan is compiled — from the second call on — a slot component called with a selection it has already seen gets back the same object of slot functions. That is stable enough for a React dependency array; it also means the object is shared, so do not mutate it.
- The store is bounded and keyed by the selection, so a variant whose values are effectively unique per call (an id, a
timestamp, a fresh object) fills it with entries nothing reads again.
cacheResolutions: falseis the escape hatch for that component.
createTV(options) bakes those options into a shared factory and returns { tv, cn }:
import { createTV } from "@codefast/tv";
import { extendTailwindMerge } from "cn/config";
const { tv, cn } = createTV({
twMerge: extendTailwindMerge({ extend: { classGroups: { "font-size": [{ text: ["huge"] }] } } }),
});
cn("text-base", "text-huge"); // => "text-huge" — the custom group is understoodOptions passed locally to tv(config, options) override the factory's, one by one: an option left out or undefined
takes the shared value. Every variant function also exposes config, its fully merged configuration (what extend
reads), and variantKeys, the variant names in declaration order with an extending function's own first — the same list
upstream exposes, for splitting variant props from the rest by hand.
Choosing the merge engine
The package imports two things from cn: its twMerge, as the default merge, and
its cn, which this package re-exports. cn produces the same output as tailwind-merge and runs faster on a string
it has not seen; anything else comes in through the twMerge option, so the application decides which engine runs. An
app that still imports tailwind-merge elsewhere can alias it to cn so the bundle carries one engine:
// vite.config.ts
resolve: { alias: { "tailwind-merge": "cn" } },The merge runs on every selection a resolver has not answered before, so the engine decides what a first render costs. A repeated selection without a caller class is answered from the store. A caller's class merges onto the selection's classes: a component without slots remembers the answer from that class's second sighting, while a slot called with a class merges on every call.
Class utilities
import { cn, cx } from "@codefast/tv";
cn("px-4 py-2", "px-6"); // => "py-2 px-6" — joined, then merged
cx("px-4 py-2", "px-6"); // => "px-4 py-2 px-6" — joined only, no merging
cn("base", isActive && "text-primary", { hidden: false }); // conditional values, the shapes clsx acceptscn is the engine's own, re-exported, and answers a repeated call from its argument cache. cx joins the same shapes
without merging, and is what createTV returns as cn under twMerge: false.
TypeScript
VariantProps extracts the variant props of a variant function (with class / className stripped) for reuse in
component props:
import { tv } from "@codefast/tv";
import type { VariantProps } from "@codefast/tv";
import type { ComponentProps } from "react";
const button = tv({
base: "rounded px-4 py-2",
variants: { variant: { primary: "bg-primary", outline: "border" } },
});
interface ButtonProps extends ComponentProps<"button">, VariantProps<typeof button> {}
function Button({ variant, className, ...props }: ButtonProps) {
return <button className={button({ variant, className })} {...props} />;
}Variant values, slot names, and compound conditions are all inferred — passing an unknown variant value or accessing a
slot that does not exist is a type error. ClassValue is the type of anything accepted where classes are expected
(strings, numbers, nested arrays, readonly ones included, condition objects). Configuration and option types
(VariantConfig, SlotVariantConfig, ExtensionVariantConfig, TailwindVariantsOptions, and friends) are exported
for library authors, as are the resolver shapes: VariantResolver<Variants, Slots> selects FlatVariantResolver
without slots and SlotVariantResolver with them, and TailwindVariantsFactory is typeof tv. A configuration held in
a variable is typed by its shape exactly as the same object literal would be.
Migrating from tailwind-variants
The configuration shape is the same — base, variants, slots, defaultVariants, compoundVariants,
compoundSlots, extend, plus the twMerge option — so for most codebases the migration is the import:
- import { tv, cn, cx } from "tailwind-variants";
+ import { tv, cn, cx } from "@codefast/tv";Resolution matches upstream tailwind-variants 4.0.0 — variant values, extend, compounds, slot props, class and
className, and "" for no classes. The differences to check for are in what the package exports and returns:
createTVreturns an object{ tv, cn }sharing the global options, rather than a baretvfunction — destructure instead of assigning directly.cnMergeand a mutabledefaultConfigare not exported; usecreateTVto configure merging.clsx,twJoin,twMergeand the default export are not re-exported; import them fromcn, the merge engine this package is built on.- There is no
twMergeConfig: passtwMerge: extendTailwindMerge(config)instead, withextendTailwindMergefromcn/config, which is also how upstream'sliteentry takes a merge function. The package has one entry point, sotailwind-variants/lite,/merge,/configand/utilshave no counterpart:twMerge: falseis the merge-freetv. - When a call, a slot call or a compound entry passes both
classandclassName,classNameis used; upstream applies both,classfirst. variantKeysis exposed as upstream exposes it; the other metadata upstream attaches to the function (base,variants,defaultVariants,slots,compoundVariants,compoundSlots,extend) lives underconfig.
Benchmarks
The repository maintains a benchmark suite that runs the same variant workloads —
simple, complex, slots, compound slots, extend, createTV, and extreme configurations, each with and without merging
— against the upstream tailwind-variants package and class-variance-authority in isolated subprocesses. Its
RESULTS.md is generated from the committed baseline — every figure,
the bundle table, and every row the package loses — and CI fails when it drifts from that run. Numbers vary by hardware,
so run it yourself rather than reading them here:
pnpm --filter @benchmark/tailwind-variants benchThe speed comes from settling things once, and only once a component has shown it will be rendered again. tv() wraps
the configuration and the first calls read it directly; the next call compiles it into a plan — compound conditions and
slot positions settled, each variant value flattened to a string the first time a call selects it — so every resolution
after is string concatenation rather than dictionary lookups. The answer is then settled per selection, so a list
rendering the same few selections resolves each of them once. cx joins directly while every argument is a string, and
cn is the engine's own, answering a repeated call from its argument cache. The suite prices both ends:
define-only-*, first-render-*, two-renders-* and three-renders-* for a definition and its first renders, the
resolution rows for every render after.
Documentation
- Rendered docs on codefastlabs.com
- ARCHITECTURE.md — the compile-then-resolve design, which parts are load-bearing, and how to measure a change to it
- DECISIONS.md — why the package exists and the choices that fix its API
- CHANGELOG.md — release history
Contributing
Issues and pull requests are welcome. Start with the repository's contributing guide; it covers the toolchain, the test layout, and the release flow.
License
Released under the MIT License.