clsx 是一个轻量级工具函数，用于安全高效地拼接条件类名；它自动过滤 falsy 值、扁平化数组、合并对象键，避免手动处理空格、重复和 undefined，体积仅约250B，不依赖 React，与 Tailwind 完全解耦。
clsx 是什么，为什么不用字符串拼接？
直接用 className="bg-blue-500 text-white p-2" 没问题，但一旦涉及条件类名（比如按钮禁用时加 opacity-50 cursor-not-allowed），硬拼字符串很快变得难读、易错、难维护。你得手动处理空格、重复、undefined 值——而 clsx 就是专治这个的：它自动过滤 falsy 值、扁平化数组、合并对象键，最终返回干净的 class 字符串。
它不依赖 React，体积小（~250B），和 Tailwind 完全解耦，只是个纯工具函数。
基础用法：对象写法最常用
绝大多数场景下，你用对象形式控制开关类名，清晰又符合直觉：
import clsx from 'clsx';
function Button({ disabled, variant = 'primary' }) {
return (
<button
className={clsx(
'px-4 py-2 rounded font-medium transition',
{ 'bg-blue-600 text-white': variant === 'primary' },
{ 'bg-gray-200 text-gray-800': variant === 'secondary' },
{ 'opacity-50 cursor-not-allowed': disabled }
)}
disabled={disabled}
>
Click me
</button>
);
}
- 对象的 key 是类名，value 是布尔值；
true时加入，false/undefined/null时跳过 - 多个对象可以并列传入，顺序即生效优先级（后写的会覆盖前面同名类，但 Tailwind 类名本身无 CSS 优先级冲突）
- 字符串字面量（如
'px-4 py-2'）会被原样保留，适合固定样式
进阶组合：嵌套数组与函数返回值
当逻辑更复杂，比如需要根据 props 动态生成一组类名，或复用某段条件逻辑，可以混用数组和函数：
立即学习“前端免费学习笔记（深入）”；
const baseClasses = ['px-4', 'py-2', 'rounded'];
const sizeClasses = (size) => ({
sm: 'text-sm py-1 px-2',
lg: 'text-lg py-3 px-6',
});
function Input({ size = 'md', error }) {
return (
<input
className={clsx(
baseClasses,
sizeClasses(size),
error && 'border-red-500 ring-2 ring-red-200',
'border border-gray-300 focus:outline-none focus:ring-2 focus:ring-blue-500'
)}
/>
);
}
- 数组会被展开，其中的字符串或对象同样参与计算
- 函数调用结果如果是对象或 falsy 值，也会被正确处理（比如
error && 'border-red-500...'在 false 时不产生任何类） - 注意不要传入
undefined或null作为独立参数，虽然clsx能吞掉，但可读性差；显式写成error ? '...' : null更稳妥
常见坑：动态类名失效、服务端渲染警告、TS 类型
三个高频出问题的地方：
-
类名没更新：检查是否把对象写成了字符串，比如
{'bg-blue-500': true}✅，但误写成"{'bg-blue-500': true}"❌ —— 后者是字符串字面量，不会解析为对象 -
SSR 不一致警告：如果类名依赖浏览器 API（如
window.matchMedia），在服务端执行时返回undefined，导致首屏 class 和 CSR 不一致。解决方案是延迟计算（useEffect+useState）或改用useMediaQuery等 SSR-safe hook -
TypeScript 报错：默认
clsx类型对复杂嵌套支持有限。推荐加装@types/clsx，并在 tsconfig 中启用skipLibCheck: false；若仍报错，可用类型断言clsx(...) as string，但应先确认结构是否真复杂到需要它
真正麻烦的不是语法，而是把「视觉状态」准确映射到条件对象里——比如 loading 和 disabled 是否同时存在、variant 有没有遗漏枚举值，这些逻辑错位比 clsx 本身更常导致样式异常。
