Add utilities: the cn() helper
Utility helpers keep className composition predictable when variants, state, and Tailwind strings collide. Nexus UI components use clsx plus tailwind-merge behind a single cn() export, and Framer Motion for animation.
What is cn() in Tailwind?
New to it? The cn() guide explains clsx vs tailwind-merge in depth, with the mistakes that silently drop classes.
cn() is not part of Tailwind CSS — it is a two-line helper that most React + Tailwind codebases (and every shadcn/ui project) keep in lib/utils.ts. It takes any mix of strings, conditionals, arrays, and objects, builds one className with clsx, then removes conflicting Tailwind utilities with tailwind-merge.
clsx vs tailwind-merge
They solve different problems, which is why cn() uses both. clsx only joins class names and drops falsy values — it knows nothing about Tailwind. tailwind-merge knows Tailwind's utility groups, so when two classes target the same property it keeps the last one.
clsx("p-4", isActive && "p-6") // → "p-4 p-6" (both kept)
twMerge("p-4 p-6") // → "p-6" (conflict resolved)
cn("p-4", isActive && "p-6") // → "p-6" (clsx, then twMerge)Try it
This runs the real clsx and tailwind-merge. Switch the props and watch which classes survive.
className comes last, so px-8 and bg-emerald-600 win
clsx only
11 classes- px-4 (removed by tailwind-merge)
- py-2 (removed by tailwind-merge)
- rounded-lg
- bg-zinc-900 (removed by tailwind-merge)
- text-white
- bg-blue-600 (removed by tailwind-merge)
- px-6 (removed by tailwind-merge)
- py-3
- text-lg
- px-8
- bg-emerald-600
cn()
6 kept · 5 removed- rounded-lg
- text-white
- py-3
- text-lg
- px-8
- bg-emerald-600
- base
- isActive
- sizes[size]
- className
cn("px-4 py-2 rounded-lg bg-zinc-…", isActive && "bg-blue-600", sizes[size], className)
// isActive: true · size: "lg" · className: "px-8 bg-emerald-600"
// → "rounded-lg text-white py-3 text-lg px-8 bg-emerald-600"This button's className is the cn() result. Utilities this site's stylesheet doesn't ship merge correctly but won't paint.
Already ran shadcn init?
Then npx shadcn@latest init (step 2 of the Quick Start) already installed clsx and tailwind-merge and created src/lib/utils.ts. Open that file, check it exports cn, and skip to step 3. Follow steps 1 and 2 only if you did not use shadcn, or the file is missing.
1. Install dependencies
Install the two libraries cn() is built from: clsx for conditional class logic and tailwind-merge for conflict resolution. Nexus UI components also animate with framer-motion, so add that too:
npm install clsx tailwind-merge framer-motion2. Create the cn() helper
A new Next.js project has no src/lib folder, so create the folder and the file. In your editor, make a folder named lib inside src, then a file named utils.ts inside it (or run mkdir -p src/lib && touch src/lib/utils.ts on macOS and Linux). Paste this into src/lib/utils.ts. Components import it as @/lib/utils:
import { type ClassValue, clsx } from "clsx";
import { twMerge } from "tailwind-merge";
export function cn(...inputs: ClassValue[]) {
return twMerge(clsx(inputs));
}The cn() function accepts any mix of strings, arrays, and objects (the full clsx API), then runs the result through twMerge so conflicting Tailwind utilities are resolved by last-argument-wins semantics.
3. Use cn() in components
Pass static base classes alongside conditional prop-driven fragments — the helper keeps the final string clean:
import { cn } from "@/lib/utils";
function Card({ className, active }: { className?: string; active?: boolean }) {
return (
<div
className={cn(
// base styles
"rounded-xl border border-border bg-card p-4",
// conditional variant
active && "border-primary ring-2 ring-primary/30",
// consumer override wins
className,
)}
/>
);
}Why tailwind-merge?
Tailwind classes are resolved by the order they appear in your CSS output, not the order they appear in the className string. Concatenating two conflicting utilities — e.g. p-4 p-6 — produces unpredictable results because whichever class was declared last in the stylesheet wins, regardless of string order.
twMerge understands Tailwind's utility groups and strips any earlier arguments that conflict with later ones, so design-system defaults and consumer overrides always compose safely:
// Without twMerge — unpredictable winner
"p-4 p-6" // both classes in DOM; CSS order decides
// With twMerge — later argument always wins
cn("p-4", "p-6") // → "p-6"
cn("p-4", props.className) // consumer override is respectedVerify the setup
Import cn in any component, for example src/app/page.tsx, and log the result:
import { cn } from "@/lib/utils";
// logs: rounded-xl bg-primary text-white px-6
const cls = cn("rounded-xl bg-muted", "bg-primary text-white", "px-4 px-6");
console.log(cls);The editor should show no import error, and the string printed in the terminal running npm run dev should contain only px-6 (not px-4) and bg-primary (not bg-muted). If the imports resolve correctly your utility layer is ready.