Conditional CSS Class Composition: classcat vs classnames vs clsx

When building dynamic user interfaces, you often need to toggle CSS classes based on state, props, or context. Manually concatenating strings is error-prone and hard to read. That’s where classcat, classnames, and clsx come in — they provide clean, declarative ways to compose class names. While they solve the same problem, their APIs, performance characteristics, and design philosophies differ in subtle but important ways.

🧩 Core API Design: How You Pass Arguments

All three accept strings, arrays, and objects, but they handle nesting and falsy values differently.

classnames is the most permissive. It recursively flattens nested arrays and ignores falsy values (null, undefined, false, 0, '').

// classnames
import classNames from 'classnames';

const btnClass = classNames(
  'btn',
  { primary: true, disabled: false },
  ['extra', null, 'padding'],
  undefined
);
// → 'btn primary extra padding'

clsx mimics classnames’s behavior almost exactly but skips deep recursion for performance. It flattens only one level of arrays and still ignores falsy values.

// clsx
import clsx from 'clsx';

const btnClass = clsx(
  'btn',
  { primary: true, disabled: false },
  ['extra', null, 'padding'],
  undefined
);
// → 'btn primary extra padding'

classcat uses a stricter, array-only top-level interface. You must pass all arguments inside a single array. It does not support multiple top-level arguments or deep nesting.

// classcat
import cc from 'classcat';

const btnClass = cc([
  'btn',
  { primary: true, disabled: false },
  ['extra', 'padding'] // nested arrays are NOT flattened
]);
// → 'btn primary extra padding' ✅

// But this fails to flatten deeper:
cc(['a', [['b']]]); // → 'a b' in classnames/clsx, but 'a [object Object]' in classcat ❌

💡 Note: classcat does not flatten nested arrays beyond one level. Passing [['b']] results in unintended output.

⚡ Performance and Runtime Behavior

classcat is the fastest because it avoids recursion and uses a simple loop. It’s optimized for the common case: a flat list of strings and objects.

clsx is nearly as fast as classcat but maintains API parity with classnames for shallow inputs. It avoids the overhead of deep flattening, making it ideal for typical React component use cases.

classnames is the slowest due to its recursive flattening logic, which walks through arbitrarily deep arrays. This is rarely needed in practice and adds unnecessary cost.

In real-world apps, you’ll rarely notice the difference — but in hot paths (e.g., rendering thousands of list items), clsx or classcat can reduce CPU time.

📝 Developer Experience and Readability

classnames has the most familiar syntax. Many developers already know it from tutorials or legacy codebases. Its flexibility feels “safe” — you can throw anything at it, and it usually works.

// Feels natural to many
<button className={classNames('btn', props.className, { active: isActive })}>

clsx offers identical DX with better performance. If your team already uses classnames, switching to clsx is often a drop-in replacement.

// Same as above, but faster
<button className={clsx('btn', props.className, { active: isActive })}>

classcat requires wrapping everything in an array, which some find less ergonomic:

// More verbose at call site
<button className={cc(['btn', props.className, { active: isActive }])}>

This can feel unnatural if you’re used to variadic functions. However, it enforces consistency and makes the input structure explicit.

🧪 Edge Case Handling

All three ignore false, null, undefined, 0, and empty strings. But they diverge on edge inputs:

• Numbers: classnames and clsx ignore 0 but include other numbers (e.g., 42 becomes '42'). classcat behaves the same.
• Nested arrays: Only classnames fully flattens them. clsx flattens one level; classcat does not flatten nested arrays at all.
• Objects with non-boolean values: All treat truthy values as “include” and falsy as “exclude.” So { foo: 'bar' } includes 'foo'; { foo: '' } excludes it.

// All produce 'btn 42'
classNames('btn', 42);
clsx('btn', 42);
cc(['btn', 42]);

// Only classnames fully flattens
classNames('a', [[['b']]]); // → 'a b'
clsx('a', [[['b']]]);      // → 'a [object Object]'
cc(['a', [[['b']]]]);     // → 'a [object Object]'

🛠️ When to Use Which?

Use clsx as your default

For most new projects — especially React apps — clsx hits the sweet spot: it’s fast, small, and reads exactly like classnames. If you’re starting fresh, there’s little reason not to choose it.

Stick with classnames for legacy or maximum compatibility

If you’re maintaining a large codebase already using classnames, or if you rely on deep array nesting (rare), migration may not be worth it. It’s stable, well-tested, and won’t break.

Choose classcat for extreme minimalism

If you’re building a design system, library, or performance-critical component where every byte and CPU cycle counts, and you can enforce a flat input structure, classcat delivers the leanest runtime.

✅ Summary Table

💡 Final Thought

These libraries are so small and focused that the “best” choice often comes down to team preference and project constraints. But if you’re starting today, clsx gives you the best balance of speed, clarity, and compatibility — making it the smart default for modern frontend work.