@nick/clsx

This is a utility for constructing conditional class names in JavaScript and TypeScript from a set of mixed inputs. It's based on the popular clsx package by Luke Edwards, re-written and enhanced by Nicholas Berlette in 100% TypeScript using modern language features.

In addition to being a drop-in replacement for the original, this package also introduces an advanced type-level implementation of the clsx function. It leverages nearly identical logic as the runtime function, at a purely type level.

That type-level implementation affords you with a compile-time preview of the className strings that clsx expects to generate at runtime, without ever leaving your editor. This is quite useful for catching typos and errors before they occur.

Usage

📦 Install

This package is distributed through JSR, NPM, and Deno.

It can be installed using your package manager of choice:

deno add @nick/clsx

npx jsr add @nick/clsx

bun add @nberlette/clsx
# or
pnpm add @nberlette/clsx
# or
yarn add @nberlette/clsx
# or
npm install @nberlette/clsx

📜 Import

The package exports a single function, clsx, which can be imported as follows:

import { clsx } from "@nick/clsx";

const className = clsx("foo", "bar", "baz");

If you're using the NPM package:

import { clsx } from "@nberlette/clsx";

const className = clsx("foo", "bar", "baz");

Or, if you're importing from deno.land:

import { clsx } from "https://deno.land/x/clsx/mod.ts";

const className = clsx("foo", "bar", "baz");

API

clsx

Constructs a composite className string from a given set of mixed inputs.

Signature

function clsx<T extends ClassInputs>(...classes: T): Clsx<T>;

Parameters

| Name | Info | | :------------ | :---------------------------------------- | | classes | The class names to compile into a string. |

Returns

| Type | Info | | :----------------------------------- | :--------------------------------------------------- | | Clsx<T, string> | Composite className string generated from the input. |

Clsx<T, Fallback>

type Clsx<T, Fallback = string> = T extends ClassInputs
  ? T["length"] extends 0 ? Fallback
  : IsValidwInput<
    T,
    MergeValues<T, Fallback> extends infer S ? S extends "" ? Fallback : S
      : Fallback,
    Fallback
  >
  : Fallback;

The type-level equivalent of the clsx function, which is used to render a compile-time preview of the className string expected to be generated.

For your convenience, an optional Fallback type parameter can be specified, which will be used in an event where a suitable type cannot be inferred. The default fallback type is the generic string type, since the clsx function will always return a string at runtime.

Type Parameters

| Name | Extends | Default | | :--------- | :------ | :------- | | T | -- | -- | | Fallback | -- | string |

Examples

import { clsx } from "@nick/clsx";

const cn = clsx("foo", "bar", "baz");
//     ^? const cn: "foo bar baz"

const cn2 = clsx("foo", { bar: true, baz: false });
//     ^? const cn2: "foo bar"

const cn3 = clsx("nested", ["deep", { no: null }, ["yuh"]]);
//     ^? const cn3: "nested deep yuh"

import { clsx } from "@nick/clsx";

const dark = matchMedia("(prefers-color-scheme: dark)").matches;

const bgs = ["bg-white", "bg-black"] as const;

// This type is correctly inferred as a union of two possible class names:
const cn = clsx("w-1/2", "h-full", bgs[+dark]);
//     ^? const cn: "w-1/2 h-full bg-white" | "w-1/2 h-full bg-black"

For more examples, refer to the test suite.

Further Reading

🧑🏽‍💻 Contributing

This project is open-source, and I welcome contributions of any kind. Feel free to open an issue or pull request in the GitHub Repository if you have any suggestions, bug reports, or feature requests.

🐛 Bugs and Issues

If you encounter any bugs or unexpected behavior, please open an issue in the GitHub Repository so it can be addressed promptly. Thank you!

MIT © Nicholas Berlette. All rights reserved.

GitHub · JSR · NPM · Deno · Docs