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.
This package is distributed through JSR, NPM, and Deno.
It can be installed using your package manager of choice:
deno add @nick/clsxnpx jsr add @nick/clsxbun add @nberlette/clsx
# or
pnpm add @nberlette/clsx
# or
yarn add @nberlette/clsx
# or
npm install @nberlette/clsxThe 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");
Constructs a composite className string from a given set of mixed inputs.
function clsx<T extends ClassInputs>(...classes: T): Clsx<T>;| Name | Info |
|---|---|
classes |
The class names to compile into a string. |
| Type | Info |
|---|---|
Clsx<T, string> |
Composite className string generated from the input. |
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.
| Name | Extends | Default |
|---|---|---|
T |
-- |
-- |
Fallback |
-- |
string |
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.
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.
If you encounter any bugs or unexpected behavior, please open an issue in the GitHub Repository so it can be addressed promptly. Thank you!