🎨 joinclass

LIVE EXAMPLE

A tiny utility for composing and transforming CSS class names.

joinclass merges classes from multiple input types and supports prefix/suffix transformation, making it ideal for Tailwind, CSS Modules, or standard class names.

Why joinclass

Writing class names in modern UI often requires:

• conditional logic
• CSS Modules mapping
• array merging
• deduplication
• dynamic generation

joinclass provides a single deterministic utility to normalize class inputs.

• ✅ Conditional classes
• ✅ Array / object / function support
• ✅ Set / Map support
• ✅ CSS Modules mapping
• ✅ Prefix / suffix transformation
• ✅ Automatic deduplication
• ✅ Works with Tailwind / CSS Modules
• ✅ Tiny footprint

Installation

npm install joinclass

Import

import joinclass from "joinclass"

Basic Usage

joinclass("btn", "active")

// → "btn active"

Falsy values are ignored automatically.

joinclass("btn", false && "hidden", null)

// → "btn"

Input Types

joinclass accepts multiple input formats.

1️⃣ String

joinclass("btn", "btn-primary")

// → "btn btn-primary"

2️⃣ Array

joinclass(["btn", "btn-large", null])

// → "btn btn-large"

Arrays are flattened automatically.

3️⃣ Object (Conditional Classes)

joinclass({
  primary: true,
  disabled: false
})

// → "primary"

Only truthy keys are included.

4️⃣ Function

joinclass(() => "dynamic-class")

// → "dynamic-class"

Functions allow lazy class evaluation.

5️⃣ Set

joinclass(new Set(["btn", "active", "btn"]))
// → "btn active" (deduplicated)

6️⃣ Map

joinclass(
  new Map([
    ["visible", true],
    ["hidden", false]
  ])
)

// → "visible"

Map keys behave like object conditional classes.

CSS Modules Support

joinclass can map class names through CSS Modules.

import styles from "./Button.module.css"

joinclass("btn", "active", {
  styles
})

// → "Button_btn__abc Button_active__xyz"

Prefix / Suffix

joinclass("btn", "large", {
  prefix: "ui-"
})

// → "ui-btn ui-large"

Suffix example:

joinclass("btn", {
  suffix: "-active"
})

// → "btn-active"

Deduplication

Duplicate classes are removed automatically.

joinclass("btn", "btn", ["btn"])

// → "btn"

Combined

import styles from "./Button.module.css"

joinclass(
  "btn",
  ["btn-large", null, "active"],
  { primary: true, disabled: false },
  () => "dynamic-class",
  new Set(["set-class"]),
  new Map([["map-class", true]]),
  {
    prefix: "ui-",
    styles
  }
)

API

joinclass(...inputs)

| Input Type | Description | |-------------|---------------------- | | string | Direct class name | | number | Converted to string | | array | Flattened recursively | | object | Conditional classes | | function | Returns class name | | Set | Converted to array | | Map | Conditional key-value |

Options

| Option | Description | |----------|--------------------------| | prefix | Add prefix to each class | | suffix | Add suffix to each class | | styles | CSS Modules mapping |

Example:

joinclass("btn", {
  prefix: "ui-",
  suffix: "-x"
})

Use Cases

joinclass is useful for:

• React components
• Tailwind UI logic
• CSS Modules integration
• Dynamic class generation
• Utility-first CSS workflows

Philosophy

Class composition should be deterministic and flexible.

joinclass focuses on normalizing class inputs rather than adding framework-specific behavior.

LISCENSE

MIT