classnames

library0.1.0jsnpmunverified

The `classnames` utility simplifies the conditional joining of CSS class names in JavaScript and TypeScript applications. It accepts any number of arguments, including strings, objects (where keys are class names and values are booleans), and arrays, intelligently combining them into a single, space-separated string. The package is currently at version 2.5.1, following the SemVer standard, indicating a strong commitment to stability and backwards compatibility for minor and patch releases. It is widely adopted, especially within the React ecosystem, due to its robust performance and minimalist API. Its key differentiators include its extreme stability, thorough test suite, and focus on performance, ensuring it reliably handles class name generation in high-frequency scenarios across browsers and Node.js environments. The project's philosophy emphasizes speed and stability, with updates thoroughly reviewed for performance implications.

web-framework

npm install classnames

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CLASSNAMES

classnames

web-frameworkjavascriptv0.1.0

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.

classNames

✓ import classNames from 'classnames';

✗ import { classNames } from 'classnames';

The `classnames` function is a default export for ESM. Using named import `import { classNames } }` will result in a `TypeError`.

classNames

✓ const classNames = require('classnames');

This is the correct CommonJS import. This pattern works in Node.js environments. As of v2.5.0, the package includes an 'exports' field for better ESM compatibility.

classNames

✓ if (window.classNames) { /* use window.classNames */ }

For standalone browser usage, including `index.js` via a `<script>` tag exposes `classNames` as a global variable. This method is less common in modern module-driven frontends.

Demonstrates various ways to combine class names, including static strings, conditional objects, arrays, and dynamic class names, handling falsy values gracefully.

import classNames from 'classnames'; const isActive = true; const hasError = false; const theme = 'dark'; // Basic usage with strings const classes1 = classNames('container', 'header'); console.log(classes1); // Expected: 'container header' // Conditional classes using objects const classes2 = classNames('button', { 'button--primary': isActive, 'button--danger': hasError, [`theme-${theme}`]: true // Dynamic class name based on variable }); console.log(classes2); // Expected: 'button button--primary theme-dark' // Mixing strings, objects, and arrays const classes3 = classNames( 'card', { 'card--active': isActive }, ['shadow', 'rounded'], null, undefined, { 'card--hidden': !isActive } ); console.log(classes3); // Expected: 'card card--active shadow rounded'

Debug

Known issues

breakingVersion 2.0.0 introduced ES6 module export. While existing CommonJS `require` statements continued to work, modern ESM `import` syntax changed how `classnames` should be imported. Incorrect import patterns (e.g., named imports for a default export) can lead to runtime errors.

fix

For ESM, use `import classNames from 'classnames';`. For CommonJS, use `const classNames = require('classnames');`. Avoid `import { classNames } from 'classnames';` as it is a default export.

affects: >=2.0.0

gotchaPrior to v2.5.0, module resolution for hybrid CJS/ESM projects, especially in Node.js environments with `"type": "module"` set, could be inconsistent. Version 2.5.0 added the `exports` field to `package.json` to improve module interoperability.

fix

Upgrade to `classnames@2.5.0` or newer to leverage the `exports` field for more reliable module resolution. Ensure your bundler/Node.js version supports `package.json` `exports`.

affects: <2.5.0

deprecatedThe `component-classes` dependency was removed in v2.0.0, streamlining the package. While not a direct breaking change for users, it signifies a move towards a leaner, dependency-free utility.

fix

No direct fix needed, but be aware that older code relying on `component-classes` (if it was somehow exposed) would break. `classnames` itself does not expose this internally anymore.

affects: >=2.0.0

gotchaThere is an alternate `dedupe` version of `classNames` available that offers more robust deduplication for complex scenarios but is significantly slower (up to 10x slower). It is offered as an opt-in for specific use cases.

fix

By default, `classnames` is optimized for speed. Only use the `dedupe` variant if you have a specific need for its deduplication behavior and have benchmarked its performance impact in your application. The core `classnames` function should be preferred for general use.

affects: >=2.1.0

Errors

Common errors & fixes

TypeError: classNames is not a function

Attempting to use `classNames` after an incorrect ES module import (e.g., `import { classNames } from 'classnames';` instead of `import classNames from 'classnames';`). This happens because `classnames` exports a default function, not a named one.

fix

Change your import statement to `import classNames from 'classnames';` for ES modules. If using CommonJS, ensure you are using `const classNames = require('classnames');`.

ERR_REQUIRE_ESM (or similar module resolution errors in Node.js ESM projects)

In a Node.js project configured as an ES module (`"type": "module"` in `package.json`), trying to `require('classnames')` might fail if Node.js resolves `classnames` as an ES module due to its `exports` field. This is a common interoperability issue.

fix

Prefer `import classNames from 'classnames';` in ES module contexts. If you *must* use `require` in an ESM file (e.g., for conditional loading), consider Node.js's `createRequire` utility: `import { createRequire } from 'module'; const require = createRequire(import.meta.url); const classNames = require('classnames');`.

Class names being returned as `[object Object]` as of v2.3.0

This issue could arise in specific bundling scenarios (e.g., Rollup/Babel) when `classnames` introduced support for custom `toString()` methods on arguments in v2.3.0, potentially leading to objects not being stringified as expected.

fix

Review your bundler configuration and ensure proper handling of objects passed to `classnames`. If you encounter this, consider simplifying the arguments passed or upgrading your bundling tools. This issue was largely addressed in subsequent patch releases. Ensure `classnames` is at least v2.3.2.

Upgrade

Version history

0.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

14 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/JedWatson/classnames ↗

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

homepagenull ↗