Cls-mate

This library is built by cursor using Composer 1

A fast, minimal utility for constructing className strings conditionally.

Features

• Tiny: ~260 bytes gzipped
• Fast: Competitive with clsx, faster than classnames
• TypeScript: Full type support included
• Compatible: Supports strings, objects, arrays, and nested arrays

Installation

npm install cls-mate

Usage

import { cn } from "cls-mate";

// Strings
cn("foo", "bar"); // => 'foo bar'

// Objects (keys with truthy values)
cn({ foo: true, bar: false, baz: true }); // => 'foo baz'

// Arrays
cn(["foo", "bar"]); // => 'foo bar'

// Mixed
cn("foo", { bar: true }, ["baz"]); // => 'foo bar baz'

// Nested arrays
cn(["foo", ["bar", ["baz"]]]); // => 'foo bar baz'

// Falsy values are ignored
cn("foo", null, undefined, false, "", "bar"); // => 'foo bar'

Real-world examples

// Conditional classes
cn("btn", {
  "btn-primary": isPrimary,
  "btn-disabled": isDisabled,
});

// Tailwind CSS composition
cn("px-4 py-2 rounded", "bg-blue-500 text-white", {
  "opacity-50 cursor-not-allowed": isDisabled,
});

API

cn(...args: ClassValue[]): string

Accepts any number of arguments and returns a space-separated string of class names.

Supported argument types:

| Type | Behavior | | ---------------------------------- | --------------------------------- | | string | Added directly if truthy | | object | Keys with truthy values are added | | array | Flattened recursively | | false, null, undefined, '' | Ignored |

Benchmarks

Benchmarks run with 1,000,000 iterations per test:

| Test Case | cls-mate | clsx | classnames | | ------------------ | -------- | -------- | ---------- | | Strings only | 34ms | 37ms | 38ms | | Object only | 28ms | 28ms | 29ms | | Mixed | 47ms | 47ms | 49ms | | Arrays | 46ms | 44ms | 49ms | | Nested arrays | 64ms | 123ms | 74ms | | Complex real-world | 90ms | 93ms | 94ms |

Summary: cls-mate is +15.3% faster than clsx and +6.3% faster than classnames.

Run benchmarks locally:

npm run bench

Bundle Size

| Library | Min | Min + Gzip | | ---------- | ---- | ---------- | | cls-mate | 508B | 260B | | clsx | 330B | 228B | | classnames | 454B | 289B |

Note: cls-mate does not support numbers (rarely used in practice), which helps keep the bundle size small.