clsx — Tiny Utility for Constructing className Strings

Introduction

clsx is a tiny utility that constructs className strings from conditional values. It accepts strings, objects, and arrays in any combination and returns a single space-separated class string. At 239 bytes it is the smallest and fastest alternative to the classnames package.

What clsx Does

• Joins multiple class name strings into one space-separated value
• Conditionally includes classes based on boolean object values
• Handles nested arrays, flattening them into a single class string
• Ignores falsy values (false, null, undefined, 0, empty string)
• Provides a clsx/lite variant at 140 bytes for string-only use cases

Architecture Overview

clsx is a single pure function with no dependencies. It iterates over its arguments, checking the type of each value. Strings and numbers are appended directly. Objects have their keys appended when the corresponding value is truthy. Arrays are recursively processed. The result is a single joined string. The entire implementation fits in roughly 20 lines of code.

Self-Hosting & Configuration

• Install via npm: npm install clsx
• Import the default export: import clsx from 'clsx'
• For string-only usage, import clsx/lite for the smaller 140-byte variant
• Works with any framework: React, Vue, Svelte, or vanilla JS
• No configuration needed; it is a pure function with no side effects

Key Features

• Only 239 bytes minified and brotlied (140 bytes for clsx/lite)
• 2x faster than classnames in benchmarks across all input types
• Accepts any combination of strings, objects, arrays, and booleans
• Full TypeScript support with accurate return type inference
• Zero dependencies with no runtime configuration

Comparison with Similar Tools

• classnames — the original library; functionally identical API but roughly 2x slower and larger
• tailwind-merge — merges Tailwind classes resolving conflicts; different purpose, much larger
• cn() helper (shadcn/ui) — thin wrapper combining clsx with tailwind-merge
• Template literals — zero dependencies but verbose and error-prone for conditional classes
• clsx/lite — same package, string-only variant at 140 bytes for simpler use cases

FAQ

Q: Should I switch from classnames to clsx? A: Yes. clsx is a drop-in replacement with the same API, smaller bundle size, and better performance.

Q: Does clsx deduplicate class names? A: No. It concatenates classes as-is. If you need deduplication or conflict resolution for Tailwind, use tailwind-merge alongside clsx.

Q: Can I use clsx with Tailwind CSS? A: Yes. clsx is commonly paired with tailwind-merge in a cn() helper function, as popularized by shadcn/ui.

Q: Does clsx support TypeScript? A: Yes. It ships with built-in TypeScript declarations and correctly types the return value as string.

Sources

• https://github.com/lukeed/clsx
• https://www.npmjs.com/package/clsx