clsx

A tiny (239B) utility for constructing className strings conditionally.
Also serves as a faster & smaller drop-in replacement for the classnames module.

This module is available in three formats:

• ES Module: dist/clsx.mjs
• CommonJS: dist/clsx.js
• UMD: dist/clsx.min.js

Install

$ npm install --save clsx

Usage

1import clsx from 'clsx';
2// or
3import { clsx } from 'clsx';
4
5// Strings (variadic)
6clsx('foo', true && 'bar', 'baz');
7//=> 'foo bar baz'
8
9// Objects
10clsx({ foo:true, bar:false, baz:isTrue() });
11//=> 'foo baz'
12
13// Objects (variadic)
14clsx({ foo:true }, { bar:false }, null, { '--foobar':'hello' });
15//=> 'foo --foobar'
16
17// Arrays
18clsx(['foo', 0, false, 'bar']);
19//=> 'foo bar'
20
21// Arrays (variadic)
22clsx(['foo'], ['', 0, false, 'bar'], [['baz', [['hello'], 'there']]]);
23//=> 'foo bar baz hello there'
24
25// Kitchen sink (with nesting)
26clsx('foo', [1 && 'bar', { baz:false, bat:null }, ['hello', ['world']]], 'cya');
27//=> 'foo bar hello world cya'

API

clsx(...input)

Returns: String

input

Type: Mixed

The clsx function can take any number of arguments, each of which can be an Object, Array, Boolean, or String.

Important: Any falsey values are discarded!
Standalone Boolean values are discarded as well.

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

Modes

There are multiple "versions" of clsx available, which allows you to bring only the functionality you need!

clsx

Size (gzip): 239 bytes
Availability: CommonJS, ES Module, UMD

The default clsx module; see API for info.

1import { clsx } from 'clsx';
2// or
3import clsx from 'clsx';

clsx/lite

Size (gzip): 140 bytes
Availability: CommonJS, ES Module
CAUTION: Accepts ONLY string arguments!

Ideal for applications that only use the string-builder pattern.

Any non-string arguments are ignored!

1import { clsx } from 'clsx/lite';
2// or
3import clsx from 'clsx/lite';
4
5// string
6clsx('hello', true && 'foo', false && 'bar');
7// => "hello foo"
8
9// NOTE: Any non-string input(s) ignored
10clsx({ foo: true });
11//=> ""

Benchmarks

For snapshots of cross-browser results, check out the bench directory~!

Support

All versions of Node.js are supported.

All browsers that support Array.isArray are supported (IE9+).

Note: For IE8 support and older, please install clsx@1.0.x and beware of #17.

Tailwind Support

Here some additional (optional) steps to enable classes autocompletion using clsx with Tailwind CSS.

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

You may find the clsx/lite module useful within Tailwind contexts. This is especially true if/when your application only composes classes in this pattern:

1clsx('text-base', props.active && 'text-primary', props.className);

Related

• obj-str - A smaller (96B) and similiar utility that only works with Objects.

License

MIT © Luke Edwards