clsx

Install the clsx utility to construct className strings conditionally. It is a tiny, fast, and small drop-in replacement for the classnames module.

$ npm install --save clsx

To enable class autocompletion when using clsx with Tailwind CSS in Visual Studio Code:

1. Install the Tailwind CSS IntelliSense extension.
2. Add the following configuration to your settings.json:

{
  "tailwindCSS.experimental.classRegex": [
    ["clsx\\(([^)]*)\\)", "(?:'|\"|`)([^']*)(?:'|\"|`)"]
  ]
}

The clsx function allows you to conditionally compose class names using strings, objects, and arrays. Any falsey values (including standalone Booleans) are discarded from the resulting string.

import clsx from 'clsx';
// or
import { clsx } from 'clsx';

// Strings (variadic)
clsx('foo', true && 'bar', 'baz');
//=> 'foo bar baz'

// Objects
clsx({ foo:true, bar:false, baz:isTrue() });
//=> 'foo baz'

// Objects (variadic)
clsx({ foo:true }, { bar:false }, null, { '--foobar':'hello' });
//=> 'foo --foobar'

// Arrays
clsx(['foo', 0, false, 'bar']);
//=> 'foo bar'

// Arrays (variadic)
clsx(['foo'], ['', 0, false, 'bar'], [['baz', [['hello'], 'there']]]);
//=> 'foo bar baz hello there'

// Kitchen sink (with nesting)
clsx('foo', [1 && 'bar', { baz:false, bat:null }, ['hello', ['world']]], 'cya');
//=> 'foo bar hello world cya'

The clsx/lite module is a smaller version (140 bytes gzip) of the utility. It is ideal for applications that only use the string-builder pattern.

CAUTION: It accepts ONLY string arguments. Any non-string arguments are ignored.

import { clsx } from 'clsx/lite';
// or
import clsx from 'clsx/lite';

// string
clsx('hello', true && 'foo', false && 'bar');
// => "hello foo"

// NOTE: Any non-string input(s) ignored
clsx({ foo: true });
//=> ""

The clsx function accepts any number of arguments of type Mixed (Object, Array, Boolean, or String). It returns a String containing the concatenated class names.

Important: Any falsey values are discarded, including standalone Boolean values.

clsx(true, false, '', null, undefined, 0, NaN);
//=> ''

Node.js

All versions of Node.js are supported.

Browsers

• All browsers that support Array.isArray are supported (IE9+).
• For IE8 support and older, please install clsx@1.0.x.

The clsx function is used to conditionally join class names together. It accepts any number of arguments and processes them to return a single space-separated string.

Supported input types:

• Strings and Numbers: Added directly to the result.
• Arrays: Elements are processed recursively. Falsy values are ignored.
• Objects: The keys are added to the result if their corresponding values are truthy.

Falsy values (like null, undefined, false, 0, or '') are automatically ignored.

The following types are exported within the clsx namespace:

type ClassValue = ClassArray | ClassDictionary | string | number | bigint | null | boolean | undefined;
type ClassDictionary = Record<string, any>;
type ClassArray = ClassValue[];

A ClassValue is any of the following types that can be passed to clsx:

• string or number or bigint
• ClassArray: An array of ClassValues
• ClassDictionary: An object where keys are class names and values are truthy/falsy triggers (e.g., { 'is-active': true })
• null, boolean, or undefined (these are ignored in the output)