Classix

2.2.12 · active · verified Sun Apr 19

classix is a highly optimized utility for conditionally joining CSS class names, focusing on speed and minimal bundle size. It distinguishes itself by exclusively accepting string expressions as arguments, diverging from common patterns in libraries like `clsx` and `classnames` which often support object syntax. This design choice simplifies the API, improves typing experience, and enables better performance and a smaller footprint. The current stable version is 2.2.12. The project maintains a frequent release cadence, primarily issuing patch updates for dependency upgrades and minor improvements, as seen in the recent changelog. It supports both ES Modules and CommonJS environments across all major browsers and Node.js versions, provides full TypeScript typing, and has zero runtime dependencies.

Common errors

```
Argument of type '{ "class-name": boolean; }' is not assignable to parameter of type 'string | boolean | null | undefined | number'.
```
cause Attempting to pass an object literal to the `cx` function in a TypeScript project, which is explicitly not supported by classix's API.

fix Rewrite object-based conditional classes using string expressions. For example, change `cx({ 'class-name': condition })` to `cx(condition && 'class-name')`.
```
Unexpected output containing '[object Object]'
```
cause Passing an object literal to `cx` in a JavaScript environment. The object is implicitly coerced into the string `[object Object]` instead of its keys being evaluated as class names.

fix Refactor object-based class definitions to use conditional string expressions. Instead of `cx({'my-class': someCondition})`, use `cx(someCondition && 'my-class')`.

Warnings

breaking When migrating from libraries like `clsx` or `classnames`, object-based arguments for conditional classes (e.g., `{ 'class-name': boolean }`) are not supported. This is a fundamental design choice in classix for performance and API simplicity.
Fix: Convert object syntax `{'class-name': condition}` to conditional string expressions like `condition && 'class-name'` or `condition ? 'class-name-if-true' : 'class-name-if-false'`.
gotcha Classix is designed to work solely with string expressions, boolean values, and falsy types. Passing other complex types like arrays or objects directly (apart from how they might be stringified) will lead to unexpected results or compilation errors.
Fix: Ensure all arguments passed to `cx` resolve to a string, boolean, null, or undefined. Use conditional string logic instead of object or array patterns found in other libraries.

Install

npm install classix npm
yarn add classix yarn
pnpm add classix pnpm

Imports

cx
wrong:
```
import { cx } from 'classix'
```
correct:
```
import cx from 'classix'
```
The primary export is a default export, though a named export also exists for `cx`.
cx
wrong:
```
import cx from 'classix'
```
correct:
```
import { cx } from 'classix'
```
Both default and named exports for `cx` are supported and commonly used.
cx
```
const cx = require('classix')
```
CommonJS require style for Node.js environments. Classix is fully compatible with both CJS and ESM.

Quickstart

Demonstrates basic class joining, conditional class application, and ternary operator usage for 'if/else' logic with `classix`.

import cx from "classix";

const isPrimary = true;
const isLarge = false;

// Basic usage: join multiple string arguments
console.log(cx("class1", "class2"));
// Expected output: "class1 class2"

// Conditional class application using boolean logic
console.log(cx("base-class", true && "active-class"));
// Expected output: "base-class active-class"

// Ternary operator for if-else class logic
console.log(cx(isPrimary ? "bg-primary-100" : "bg-secondary-100"));
// Expected output: "bg-primary-100"

// Combining static classes with multiple conditional expressions
const result = cx(
  "flex",
  isPrimary ? "bg-primary-100" : "bg-secondary-100",
  isLarge ? "m-4 p-4" : "m-2 p-2"
);
console.log(result);
// Assuming isPrimary is true and isLarge is false:
// Expected output: "flex bg-primary-100 m-2 p-2"

view raw JSON →