1 | # clsx [![CI](https://github.com/lukeed/clsx/workflows/CI/badge.svg)](https://github.com/lukeed/clsx/actions?query=workflow%3ACI) [![codecov](https://badgen.net/codecov/c/github/lukeed/clsx)](https://codecov.io/gh/lukeed/clsx) [![licenses](https://licenses.dev/b/npm/clsx)](https://licenses.dev/npm/clsx)
|
2 |
|
3 | > A tiny (239B) utility for constructing `className` strings conditionally.<Br>Also serves as a [faster](bench) & smaller drop-in replacement for the `classnames` module.
|
4 |
|
5 | This module is available in three formats:
|
6 |
|
7 | * **ES Module**: `dist/clsx.mjs`
|
8 | * **CommonJS**: `dist/clsx.js`
|
9 | * **UMD**: `dist/clsx.min.js`
|
10 |
|
11 |
|
12 | ## Install
|
13 |
|
14 | ```
|
15 | $ npm install --save clsx
|
16 | ```
|
17 |
|
18 |
|
19 | ## Usage
|
20 |
|
21 | ```js
|
22 | import clsx from 'clsx';
|
23 | // or
|
24 | import { clsx } from 'clsx';
|
25 |
|
26 | // Strings (variadic)
|
27 | clsx('foo', true && 'bar', 'baz');
|
28 | //=> 'foo bar baz'
|
29 |
|
30 | // Objects
|
31 | clsx({ foo:true, bar:false, baz:isTrue() });
|
32 | //=> 'foo baz'
|
33 |
|
34 | // Objects (variadic)
|
35 | clsx({ foo:true }, { bar:false }, null, { '--foobar':'hello' });
|
36 | //=> 'foo --foobar'
|
37 |
|
38 | // Arrays
|
39 | clsx(['foo', 0, false, 'bar']);
|
40 | //=> 'foo bar'
|
41 |
|
42 | // Arrays (variadic)
|
43 | clsx(['foo'], ['', 0, false, 'bar'], [['baz', [['hello'], 'there']]]);
|
44 | //=> 'foo bar baz hello there'
|
45 |
|
46 | // Kitchen sink (with nesting)
|
47 | clsx('foo', [1 && 'bar', { baz:false, bat:null }, ['hello', ['world']]], 'cya');
|
48 | //=> 'foo bar hello world cya'
|
49 | ```
|
50 |
|
51 |
|
52 | ## API
|
53 |
|
54 | ### clsx(...input)
|
55 | Returns: `String`
|
56 |
|
57 | #### input
|
58 | Type: `Mixed`
|
59 |
|
60 | The `clsx` function can take ***any*** number of arguments, each of which can be an Object, Array, Boolean, or String.
|
61 |
|
62 | > **Important:** _Any_ falsey values are discarded!<br>Standalone Boolean values are discarded as well.
|
63 |
|
64 | ```js
|
65 | clsx(true, false, '', null, undefined, 0, NaN);
|
66 | //=> ''
|
67 | ```
|
68 |
|
69 | ## Modes
|
70 |
|
71 | There are multiple "versions" of `clsx` available, which allows you to bring only the functionality you need!
|
72 |
|
73 | #### `clsx`
|
74 | > **Size (gzip):** 239 bytes<br>
|
75 | > **Availability:** CommonJS, ES Module, UMD
|
76 |
|
77 | The default `clsx` module; see [API](#API) for info.
|
78 |
|
79 | ```js
|
80 | import { clsx } from 'clsx';
|
81 | // or
|
82 | import clsx from 'clsx';
|
83 | ```
|
84 |
|
85 | #### `clsx/lite`
|
86 | > **Size (gzip):** 140 bytes<br>
|
87 | > **Availability:** CommonJS, ES Module<br>
|
88 | > **CAUTION:** Accepts **ONLY** string arguments!
|
89 |
|
90 | Ideal for applications that ***only*** use the string-builder pattern.
|
91 |
|
92 | Any non-string arguments are ignored!
|
93 |
|
94 | ```js
|
95 | import { clsx } from 'clsx/lite';
|
96 | // or
|
97 | import clsx from 'clsx/lite';
|
98 |
|
99 | // string
|
100 | clsx('hello', true && 'foo', false && 'bar');
|
101 | // => "hello foo"
|
102 |
|
103 | // NOTE: Any non-string input(s) ignored
|
104 | clsx({ foo: true });
|
105 | //=> ""
|
106 | ```
|
107 |
|
108 | ## Benchmarks
|
109 |
|
110 | For snapshots of cross-browser results, check out the [`bench`](bench) directory~!
|
111 |
|
112 | ## Support
|
113 |
|
114 | All versions of Node.js are supported.
|
115 |
|
116 | All browsers that support [`Array.isArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/isArray#Browser_compatibility) are supported (IE9+).
|
117 |
|
118 | >**Note:** For IE8 support and older, please install `clsx@1.0.x` and beware of [#17](https://github.com/lukeed/clsx/issues/17).
|
119 |
|
120 | ## Tailwind Support
|
121 |
|
122 | Here some additional (optional) steps to enable classes autocompletion using `clsx` with Tailwind CSS.
|
123 |
|
124 | <details>
|
125 | <summary>
|
126 | Visual Studio Code
|
127 | </summary>
|
128 |
|
129 | 1. [Install the "Tailwind CSS IntelliSense" Visual Studio Code extension](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss)
|
130 |
|
131 | 2. Add the following to your [`settings.json`](https://code.visualstudio.com/docs/getstarted/settings):
|
132 |
|
133 | ```json
|
134 | {
|
135 | "tailwindCSS.experimental.classRegex": [
|
136 | ["clsx\\(([^)]*)\\)", "(?:'|\"|`)([^']*)(?:'|\"|`)"]
|
137 | ]
|
138 | }
|
139 | ```
|
140 | </details>
|
141 |
|
142 | You may find the [`clsx/lite`](#clsxlite) module useful within Tailwind contexts. This is especially true if/when your application **only** composes classes in this pattern:
|
143 |
|
144 | ```js
|
145 | clsx('text-base', props.active && 'text-primary', props.className);
|
146 | ```
|
147 |
|
148 | ## Related
|
149 |
|
150 | - [obj-str](https://github.com/lukeed/obj-str) - A smaller (96B) and similiar utility that only works with Objects.
|
151 |
|
152 | ## License
|
153 |
|
154 | MIT © [Luke Edwards](https://lukeed.com)
|