{"id":12972,"library":"clsx","title":"clsx: Conditional Classname Utility","description":"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+).","status":"active","version":"2.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/lukeed/clsx","tags":["javascript","classes","classname","classnames","typescript"],"install":[{"cmd":"npm install clsx","lang":"bash","label":"npm"},{"cmd":"yarn add clsx","lang":"bash","label":"yarn"},{"cmd":"pnpm add clsx","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The default export for `clsx`. CommonJS `require` works, but ES Module `import` is the standard for modern Node.js and browser environments.","wrong":"const clsx = require('clsx');","symbol":"clsx","correct":"import clsx from 'clsx';"},{"note":"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.","wrong":"import * as clsx from 'clsx';","symbol":"clsx (named)","correct":"import { clsx } from 'clsx';"},{"note":"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.","wrong":"import clsx from 'clsx/lite';","symbol":"clsx/lite","correct":"import { clsx } from 'clsx/lite';"},{"note":"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.","wrong":"import clsx from 'clsx';","symbol":"CommonJS (pre-v2.0.0 or specific environments)","correct":"const clsx = require('clsx');"}],"quickstart":{"code":"import { clsx } from 'clsx';\n\ninterface MyProps {\n  isActive?: boolean;\n  type: 'primary' | 'secondary' | 'danger';\n  className?: string;\n}\n\nfunction getButtonClasses(props: MyProps): string {\n  const { isActive, type, className } = props;\n\n  return clsx(\n    'base-button',\n    isActive && 'active-state',\n    {\n      'button-primary': type === 'primary',\n      'button-secondary': type === 'secondary',\n      'button-danger': type === 'danger',\n    },\n    ['padding-md', 0, false, 'text-center'], // Arrays are flattened\n    className,\n    null, undefined, 0, NaN // Falsey values are discarded\n  );\n}\n\nconsole.log(getButtonClasses({\n  isActive: true,\n  type: 'primary',\n  className: 'custom-class-1'\n}));\n// Expected: 'base-button active-state button-primary padding-md text-center custom-class-1'\n\nconsole.log(getButtonClasses({\n  type: 'secondary',\n  className: 'custom-class-2'\n}));\n// Expected: 'base-button button-secondary padding-md text-center custom-class-2'","lang":"typescript","description":"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."},"warnings":[{"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\"`.","message":"Version 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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"If IE8 support is critical, use `clsx@1.0.x`. Otherwise, ensure your target browser list (browserslist) reflects IE9+ compatibility.","message":"Version 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.","severity":"breaking","affected_versions":">=1.1.0"},{"fix":"Only use `clsx/lite` when you are certain all arguments will be strings. For mixed argument types, use the full `clsx` module.","message":"The `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.","severity":"gotcha","affected_versions":">=2.1.0"},{"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.","message":"`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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=1.2.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"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.","error":"TypeError: clsx is not a function"},{"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';`.","cause":"The `clsx/lite` submodule ignores non-string arguments, leading to classes from objects or arrays not being included in the output string.","error":"Classes not applying when using `clsx/lite` with objects or arrays."},{"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.","cause":"The Tailwind CSS IntelliSense extension might not automatically recognize `clsx` function calls within `className` attributes without explicit configuration.","error":"Tailwind CSS IntelliSense not working with `clsx`."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}