Guide · Open source
How to use classnames: join CSS class names conditionally
Updated · written with AI from the project's own documentation and checked against our catalogue data
Classnames is a small JavaScript utility that joins class names into one string. You pass it strings, arrays or objects, and object keys are included only when their values are truthy. This guide shows you how to install it, how its arguments behave, and how to use it in React components and with css-modules.
classnamesJedWatson/classnames · ★ 17.8k · MIT Install options & downloads Quick start
- 1Install the package. Run npm install classnames in your project folder.
- 2Import the function. Load classNames with require or an import, depending on your setup with Node.js, webpack or Browserify.
- 3Pass strings and objects. List your fixed class names as strings and your conditional classes as object keys with true or false values.
- 4Add an optional className. Pass a className prop from a parent as one argument so only truthy values are included.
- 5Switch to dedupe if needed. Use classnames/dedupe if you need duplicate classes removed, accepting that it is slower.
Install classnames with npm
Install classnames from the npm registry with your package manager. The README's example uses npm.
To use it in Node.js, Browserify or webpack, load it with require. The README notes that you need Node.js or a bundler such as webpack or Browserify for module use.
npm install classnamesUnderstand how classNames builds a string
The classNames function takes any number of arguments, which can be strings or objects. The string 'foo' is short for { foo: true }. If the value for a key is falsy, that key is left out of the output.
Other falsy values such as null, false, undefined, 0 and empty strings are ignored. Arrays are flattened recursively using the same rules.
- Strings are added as class names.
- An object key is added only when its value is truthy.
- Falsy arguments such as null, false, undefined, 0 and '' are skipped.
- Arrays are flattened, so their contents follow the same rules.
const classNames = require('classnames');
classNames('foo', 'bar'); // => 'foo bar'
classNames({ 'foo-bar': false }); // => ''
classNames('a', ['b', { c: true, d: false }]); // => 'a b c'Use classnames in React components
One of the main uses is making conditional className props simpler. Instead of building a string by hand with if statements, you write an object where each key is a class name and each value is a condition.
classnames also handles an optional className passed in from a parent. Because only truthy arguments are included, you can pass the prop directly alongside your own classes.
const btnClass = classNames('btn', this.props.className, {
'btn-pressed': isPressed,
'btn-over': !isPressed && isHovered,
});Use the dedupe version when you need unique classes
The standard version does not remove duplicate classes. The alternate dedupe version does remove duplicates and makes sure falsy classes in later arguments are excluded. The README says it is about 5x slower, so it is offered as an opt-in.
Load it from the classnames/dedupe path.
const classNames = require('classnames/dedupe');
classNames('foo', 'foo', 'bar'); // => 'foo bar'
classNames('foo', { foo: false, bar: true }); // => 'bar'Use the bind version with css-modules
If you use css-modules, or a similar approach that maps class names in your code to the real values output to the DOM, use the bind variant. You bind it to your styles object, then call the returned function with your class names.
The README notes that in ES2015 environments, the dynamic class names approach may be a better fit.
const classNames = require('classnames/bind');
const styles = { foo: 'abc', bar: 'def', baz: 'xyz' };
const cx = classNames.bind(styles);
cx('foo', ['bar'], { baz: true }); // => 'abc def xyz'Use computed keys for dynamic class names
In environments that support computed keys, available in ES2015 and Babel, you can build a class name from a variable. The key is written inside square brackets.
const buttonType = 'primary';
classNames({ [`btn-${buttonType}`]: true });What people use it for
- Toggling a button's classes when it is pressed or hovered in a React component.
- Merging a base class, a parent-supplied className and state-based modifiers in one call.
- Mapping class names to generated values with the bind helper when using css-modules.
- Building a class string for HTML from a list of conditions without manual concatenation.
Frequently asked questions
Is classnames free to use?
Yes. The project is licensed under the MIT licence, as shown in the README and the item details. Check the licence file in the repository for the full terms.
What do I need to use classnames?
The README lists Node.js or a bundler such as webpack or Browserify for module use. You can also include index.js with a standalone script tag, which exports a global classNames method.
How do I install classnames?
Run npm install classnames with your package manager. The package is published on the npm registry.
Does classnames remove duplicate class names?
Not in the standard version. Use classnames/dedupe if you need duplicates removed and falsy classes in later arguments excluded. The README says this version is about 5x slower.
What are the alternatives to classnames?
The item details list clsx, classcat and classnames/dedupe as comparable projects. The source here does not compare their speed or features, so check each one's documentation before choosing.
Can I use classnames with css-modules?
Yes. Use the classnames/bind variant, bind it to your styles object, and call the returned function. The README gives an example that maps 'foo' to 'abc'.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Classnames suits front-end developers, especially React developers, who want to build class strings from state and optional props without manual concatenation. If you do not write HTML or JavaScript class names, or you need duplicates removed by default, look at the dedupe variant or another library such as clsx.
Install options & downloads