clsx

library0.1.1jsnpmunverified

clsx is a compact (239B gzipped) and highly efficient utility for conditionally constructing `className` strings in JavaScript and TypeScript applications. It offers a faster and smaller alternative to similar libraries like `classnames`. The package is actively maintained, with recent releases like v2.1.1, suggesting a steady cadence of minor features and patches. Key differentiators include its minimal footprint, support for various argument types (strings, objects, arrays, and nested structures), and the `clsx/lite` submodule (140B gzipped) for string-only use cases, particularly beneficial in environments like Tailwind CSS. It ships with TypeScript types and is supported across all Node.js versions and browsers supporting `Array.isArray` (IE9+).

web-framework

npm install clsx

github ↗package ↗

INSTALL

IMPORT

SIG · CLSX

clsx

web-frameworkjavascriptv0.1.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

clsx

✓ import clsx from 'clsx';

✗ const clsx = require('clsx');

The default export for `clsx`. CommonJS `require` works, but ES Module `import` is the standard for modern Node.js and browser environments.

clsx (named)

✓ import { clsx } from 'clsx';

✗ import * as clsx from 'clsx';

Since v1.2.0, `clsx` also provides a named export alias for the default export, which is preferred by TypeScript to avoid `esModuleInterop` issues. Both default and named imports are effectively identical.

clsx/lite

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

✗ import clsx from 'clsx/lite';

The `clsx/lite` submodule (since v2.1.0) is a smaller version, but it *only* accepts string arguments. It also offers both default and named exports.

CommonJS (pre-v2.0.0 or specific environments)

✓ const clsx = require('clsx');

✗ import clsx from 'clsx';

While v2.0.0 added an `exports` map for native ESM, CommonJS `require` is still supported. However, using `import` in a pure CommonJS environment will lead to errors, and `require` cannot dynamically load ESM modules.

This quickstart demonstrates `clsx`'s ability to combine strings, objects, and arrays conditionally to generate a final CSS class string, handling various data types and falsey values.

import { clsx } from 'clsx'; interface MyProps { isActive?: boolean; type: 'primary' | 'secondary' | 'danger'; className?: string; } function getButtonClasses(props: MyProps): string { const { isActive, type, className } = props; return clsx( 'base-button', isActive && 'active-state', { 'button-primary': type === 'primary', 'button-secondary': type === 'secondary', 'button-danger': type === 'danger', }, ['padding-md', 0, false, 'text-center'], // Arrays are flattened className, null, undefined, 0, NaN // Falsey values are discarded ); } console.log(getButtonClasses({ isActive: true, type: 'primary', className: 'custom-class-1' })); // Expected: 'base-button active-state button-primary padding-md text-center custom-class-1' console.log(getButtonClasses({ type: 'secondary', className: 'custom-class-2' })); // Expected: 'base-button button-secondary padding-md text-center custom-class-2'

Debug

Known issues

breakingVersion 2.0.0 introduced an `"exports"` map for native ES Module support, which may affect how bundlers and Node.js resolve the package, particularly in older or mixed CommonJS/ESM environments.

fix

Ensure your build tools (e.g., Webpack, Rollup, Vite) and Node.js version are configured to handle native ESM. You might need to update `tsconfig.json` for TypeScript to `"moduleResolution": "node16"` or `"nodenext"`.

affects: >=2.0.0

breakingVersion 1.1.0 dropped support for Internet Explorer 8 and older due to the adoption of `Array.isArray` for proper array type-checking, which is not available in those browsers.

fix

If IE8 support is critical, use `clsx@1.0.x`. Otherwise, ensure your target browser list (browserslist) reflects IE9+ compatibility.

affects: >=1.1.0

gotchaThe `clsx/lite` submodule (introduced in v2.1.0) is optimized for string-only usage. It silently ignores any non-string arguments (e.g., objects, arrays, booleans), which can lead to unexpected missing classes if used interchangeably with the full `clsx` module.

fix

Only use `clsx/lite` when you are certain all arguments will be strings. For mixed argument types, use the full `clsx` module.

affects: >=2.1.0

gotcha`clsx` discards all falsey values (e.g., `false`, `null`, `undefined`, `0`, `NaN`, `''`) and standalone boolean arguments. This is by design to simplify conditional class logic.

fix

Understand that `clsx(true, false, '', null, undefined, 0, NaN)` will return `''`. Only truthy string or object/array values will contribute to the output string.

affects: >=1.0.0

gotchaThe named `clsx` export is an alias for the default export, primarily for TypeScript users to avoid `esModuleInterop` issues or for specific tooling preferences. It does not imply a different functionality.

fix

Feel free to use `import { clsx } from 'clsx';` if preferred, but be aware it's functionally identical to `import clsx from 'clsx';`. Choose one style for consistency within your project.

affects: >=1.2.0

Errors

Common errors & fixes

TypeError: clsx is not a function

Attempting to `require` a named export from a module that uses native ES Module `exports` map, or incorrect `import` syntax in an ES Module context.

fix

Ensure you are using the correct import/require syntax for your project's module system. For ES Modules, use `import clsx from 'clsx'` or `import { clsx } from 'clsx'`. For CommonJS, use `const clsx = require('clsx');`. If using a bundler, verify its configuration for module resolution.

Classes not applying when using `clsx/lite` with objects or arrays.

The `clsx/lite` submodule ignores non-string arguments, leading to classes from objects or arrays not being included in the output string.

fix

If you need to pass objects or arrays for conditional class logic, use the full `clsx` module: `import { clsx } from 'clsx';` instead of `import { clsx } from 'clsx/lite';`.

Tailwind CSS IntelliSense not working with `clsx`.

The Tailwind CSS IntelliSense extension might not automatically recognize `clsx` function calls within `className` attributes without explicit configuration.

fix

Add a `tailwindCSS.experimental.classRegex` configuration to your VS Code `settings.json` to include `clsx` patterns. Refer to the `clsx` README for the recommended configuration.

Upgrade

Version history

0.1.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

14 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/lukeed/clsx ↗

packagehttps://www.npmjs.com/package/clsx ↗