clsx-react

clsx-react - JSX Super Power for className

Stop importing clsx or classnames manually.

clsx-react is a zero dependency, super tiny, custom React JSX runtime that natively supports arrays and objects in the className prop. It automatically applies clsx logic at the runtime level, keeping your code clean and your imports empty.

The Problem

You need conditional class names in your React components, but importing and using clsx or classnames everywhere leads to repetitive boilerplate code.

// ❌ Old way: Boilerplate everywhere
import clsx from 'clsx'; // or classnames

export const Button = ({ active, disabled }) => (
  <button className={clsx('btn', { 'btn-active': active, 'btn-disabled': disabled })}>Click me</button>
);

The Solution

No more imports or boilerplate. Just use arrays and objects directly in className. Strings still work as usual.

// ✅ New way: Zero imports, native syntax
export const Button = ({ active, disabled }) => (
  <button className={['btn', { 'btn-active': active, 'btn-disabled': disabled }]}>Click me</button>
);

Installation

npm install clsx-react
# or
yarn add clsx-react
# or
pnpm add clsx-react

Note: Requires react >= 17.0.0.

Configuration

To make this work, you need to tell your compiler to use this package as the JSX Import Source instead of the default react. Let me guide you through the setup for various environments.

1. TypeScript (tsconfig.json) / JavaScript (jsconfig.json) - Recommended

This handles both the compilation and the type definitions (so TS won't complain about arrays in className).

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "clsx-react"
  }
}

2. Vite (vite.config.ts) / Esbuild

If you are using Vite, you can set it explicitly in the config:

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  esbuild: {
    jsxImportSource: 'clsx-react',
  },
});

3. Next.js / SWC / Turbopack

Next.js usually respects tsconfig.json or jsconfig.json. Ensure your compilerOptions are set as shown in step 1.

4. Babel / Webpack

If you are using Babel, you can set the jsxImportSource in your Babel config:

{
  "presets": [
    [
      "@babel/preset-react",
      {
        "runtime": "automatic",
        "importSource": "clsx-react"
      }
    ]
  ]
}

Usage Examples

Once configured, you can use className just like you would use the clsx function arguments.

Conditional Classes (Object)

<div className={{ hidden: isHidden, flex: isFlex }}>...</div>

Arrays

<div className={['text-lg', 'font-bold', isError && 'text-red-500']}>...</div>

Mixed & Nested

<div className={['p-4', { 'bg-gray-100': !dark }, ['shadow-md', 'rounded']]}>...</div>

Standard String (Still works)

<div className="just-a-string">...</div>

How it works

This package wraps the standard react/jsx-runtime and react/jsx-dev-runtime. It intercepts the creation of every JSX element:

• Checks if className prop exists.
• Checks if className is not a string (array or object).
• If so, it processes it with a bundled, lightweight version of clsx.
• Passes the processed props to the original React runtime.

It adds negligible overhead (bytes) and eliminates the need to manually import and call class utilities in every single component file.

TypeScript Support

This package includes a global augmentation for React.HTMLAttributes. Once you set "jsxImportSource": "clsx-react" in your tsconfig.json, TypeScript will automatically understand that className accepts arrays and objects. No extra .d.ts configuration needed!

Guidelines

See Code of Conduct, Contributing, and Security Policy.

License

MIT License © 2026 Zsolt Tövis

If you find this project useful, please consider sponsoring me on GitHub, PayPal, or give the repo a star.