joinclass
A tiny utility for composing and transforming CSS class names.
joinclassmerges 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.
String
joinclass("btn", "btn-primary")
// → "btn btn-primary"
Array
joinclass(["btn", "btn-large", null])
// → "btn btn-large"
Arrays are flattened automatically.
Object (Conditional Classes)
joinclass({
primary: true,
disabled: false
})
// → "primary"
Only truthy keys are included.
Function
joinclass(() => "dynamic-class")
// → "dynamic-class"
Functions allow lazy class evaluation.
Set
joinclass(new Set(["btn", "active", "btn"]))
// → "btn active" (deduplicated)
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