npm.io
1.1.2 • Published 8 months ago

joinclass

Licence
MIT
Version
1.1.2
Deps
0
Size
10 kB
Vulns
0
Weekly
0

joinclass

NPM Downloads

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.


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

Keywords