class-glue 💫

A lightweight (< 450B) yet powerful utility for dynamic class name generation in JavaScript applications. Perfect for React, React Native, Vue.js, and any JavaScript project where you need flexible class name handling with type safety.

Introduction

class-glue solves the common challenge of managing dynamic class names in modern web applications. Whether you're toggling classes based on state, merging CSS modules, or handling complex conditional styling, class-glue provides an elegant and performant solution.

Why class-glue?

🪶 Lightweight: Entire core is just 425B (minified + gzipped), with modular utilities each under 540B
🔍 Type-Safe: Built with TypeScript for robust type checking and excellent IDE support
🌐 Framework Agnostic: Works seamlessly with React, React Native/Expo, Vue, Angular, or vanilla JavaScript
🧩 Modular Design: Import only what you need - each utility can be used standalone
🎯 Zero Dependencies: No external dependencies means no bloat in your project
🌳 Tree-Shakeable: Modern bundlers can eliminate unused code for optimal bundle size
⚡ Performance Focused: Optimized internals with minimal runtime overhead

Core Features

🎯 Multiple API Styles

Main API (class-glue): Full-featured class name generation
String Only (join-strings): Optimized for simple string concatenation
Object Keys (keys-to-strings): Efficient object-based class generation
CSS Modules (merge-module-strings): First-class CSS Modules support
Style Objects (merge-styles): React Native and style object handling

💡 Smart Type System

Full TypeScript support with detailed type definitions
Intelligent type inference for better development experience
Strict type checking to catch errors early

🛠 Developer Experience

Comprehensive source maps for easy debugging
Detailed error messages in development
Extensive documentation with real-world examples

🔋 Production Ready

Thoroughly tested with 100% coverage
Used in production by numerous projects
Active maintenance and community support

Quick Examples

Basic Usage

import classGlue from 'class-glue';

classGlue('btn', { active: true }, ['primary']);
// => 'btn active primary'

String-Only Operations

import classGlueString from 'class-glue/join-strings';

classGlueString('card', isActive && 'card-active');
// => 'card card-active' (if isActive is true)

Object-Based Operations

import keysToStrings from 'class-glue/keys-to-strings';

keysToStrings({
  btn: true,
  'btn-active': isActive
});
// => 'btn btn-active' (if isActive is true)

CSS Modules Support

import createModuleGlue from 'class-glue/merge-module-strings';
import styles from './Button.module.css';

const moduleGlue = createModuleGlue(styles);
moduleGlue('button', { active: isActive });
// => 'Button_button_x7d Button_active_d4f'

React Native Style Handling

import createStyleGlue from 'class-glue/merge-styles';

const styleGlue = createStyleGlue({
  base: { padding: 10 },
  active: { backgroundColor: 'blue' }
});
styleGlue('base', { active: isActive });
// => { padding: 10, backgroundColor: 'blue' }

Installation

Package Managers

NPM

npm install class-glue

Yarn

yarn add class-glue

PNPM

pnpm add class-glue

Bun

bun add class-glue

CDN Usage

<!-- Global: window.classG -->
<script src="https://unpkg.com/class-glue"></script>

<!-- Individual utilities -->
<script src="https://unpkg.com/class-glue/dist/umd/join-strings.min.js"></script>        <!-- window.classGJoinStrings -->
<script src="https://unpkg.com/class-glue/dist/umd/keys-to-strings.min.js"></script>     <!-- window.classGKeysToStrings -->
<script src="https://unpkg.com/class-glue/dist/umd/merge-module-strings.min.js"></script> <!-- window.classGMergeModuleStrings -->
<script src="https://unpkg.com/class-glue/dist/umd/merge-styles.min.js"></script>        <!-- window.classGMergeStyles -->

When using via CDN, the utilities are available as:

window.classG (main)

window.classGJoinStrings

window.classGKeysToStrings

window.classGMergeModuleStrings

window.classGMergeStyles

Import Formats

class-glue ships with multiple build formats:

Format	Entry Point	Usage
CommonJS	`dist/index.js`	Node.js, Webpack, etc.
ES Module	`dist/esm/index.js`	Modern bundlers
UMD	`dist/umd/index.min.js`	Direct browser usage

Each utility is available in all formats above. Import the one that best suits your needs:

// ES Modules (Recommended)
import classGlue from 'class-glue';

// CommonJS
const classGlue = require('class-glue');

// Individual utilities
import joinStrings from 'class-glue/join-strings';
import keysToStrings from 'class-glue/keys-to-strings';
import createModuleGlue from 'class-glue/merge-module-strings';
import createStyleGlue from 'class-glue/merge-styles';

Usage Examples

Basic Usage Example

import classGlue from 'class-glue';

// Simple strings
classGlue('btn', 'primary');  // => 'btn primary'

// Conditionals
classGlue('btn', {
  'btn-primary': true,
  'btn-disabled': false
});  // => 'btn btn-primary'

// Arrays
classGlue('btn', ['primary', 'disabled']);  // => 'btn primary disabled'

// Ignored values
classGlue('btn', undefined, null, false);  // => 'btn'

// Mixed values (strings, objects, arrays, etc.)
classGlue('btn', 'primary', { active: true }, ['disabled']);  // => 'btn primary active disabled'

React Integration

import classGlue from 'class-glue';

function Button({ isActive, isDisabled, size, children }) {
  return (
    <button
      className={classGlue(
        'btn',
        {
          'btn-active': isActive,
          'btn-disabled': isDisabled,
        },
        size && `btn-${size}`
      )}
    >
      {children}
    </button>
  );
}

CSS Modules

import createModuleGlue from 'class-glue/merge-module-strings';
import styles from './Card.module.css';

const clgl = createModuleGlue(styles);

function Card({ isHighlighted }) {
  return (
    <div className={clgl('card', { cardHighlighted: isHighlighted })}>
      {/* Resolves to actual CSS Module classes like "Card_card_x7d Card_cardHighlighted_f3j" */}
    </div>
  );
}

Style Objects (React Native)

import createStyleGlue from 'class-glue/merge-styles';

const styles = {
  container: { padding: 16, borderRadius: 8 },
  active: { backgroundColor: 'blue' },
  disabled: { opacity: 0.5 }
};

const clgl = createStyleGlue(styles);

function Card({ isActive, isDisabled }) {
  return (
    <View style={clgl('container', {
      active: isActive,
      disabled: isDisabled
    })}>
      {/* Merges styles based on conditions */}
    </View>
  );
}

Conditional Classes

import keysToStrings from 'class-glue/keys-to-strings';

// Object syntax for multiple conditions
keysToStrings({
  base: true,                    // always included
  active: isActive,              // included if isActive is true
  disabled: isDisabled,          // included if isDisabled is true
  [`size-${size}`]: size,       // included if size is truthy
  [styles.custom]: hasCustom     // CSS Module class names work too
});

TypeScript Usage

import classGlue from 'class-glue';
import type { ClassValue } from 'class-glue';

// All utilities are fully typed
function Button<T extends string>({ className, variant }: {
  className?: ClassValue;
  variant?: T;
}) {
  return (
    <button
      className={classGlue(
        'btn',
        className,           // safely accepts ClassValue type
        variant && `btn-${variant}`
      )}
    />
  );
}

API Reference

class-glue (Main)

import classGlue from 'class-glue';

classGlue(...args: ClassValue[]): string;

type ClassValue =
  | string
  | number
  | boolean
  | undefined
  | null
  | { [key: string]: boolean | undefined | null }
  | ClassValue[];

// Full featured class name generation
classGlue(
  'string',           // plain strings
  { active: true },   // object keys with boolean values
  ['array', 'of', 'classes'],  // arrays
  undefined,          // ignored
  null,              // ignored
  false              // ignored
);

join-strings

import joinStrings from 'class-glue/join-strings';

joinStrings(...args: Array<string | undefined | null | boolean>): string;

// Optimized for string-only operations
joinStrings(
  'button',
  isActive && 'active',    // conditional strings
  undefined,               // ignored
  null,                    // ignored
  isPrimary && 'primary'
);

keys-to-strings

import keysToStrings from 'class-glue/keys-to-strings';

keysToStrings(obj: { [key: string]: boolean | undefined | null }): string;

// Efficient object-based class generation
keysToStrings({
  btn: true,              // always included
  'btn-primary': isPrimary,  // included if isPrimary is true
  'btn-active': isActive,    // included if isActive is true
  'btn-disabled': false      // never included
});

merge-module-strings

import createModuleGlue from 'class-glue/merge-module-strings';
import type { ClassValue } from 'class-glue';

createModuleGlue(styleModule: { [key: string]: string }): 
  (...args: ClassValue[]) => string;

// CSS Modules integration
import styles from './Button.module.css';
const clgl = createModuleGlue(styles);

clgl(
  'button',           // looks up 'button' in styles object
  { active: true },   // looks up 'active' in styles object
  styles.custom      // used as-is
);

merge-styles

import createStyleGlue from 'class-glue/merge-styles';
import type { ClassValue } from 'class-glue';

createStyleGlue(styles: { [key: string]: any }): 
  (...args: ClassValue[]) => { [key: string]: any };

// Style object merging (React Native)
const styles = {
  base: { padding: 16 },
  active: { backgroundColor: 'blue' }
};
const clgl = createStyleGlue(styles);

clgl(
  'base',             // includes base styles
  { active: true },   // merges active styles
  customStyles       // merges custom styles
);

Each utility is designed for specific use cases:

class-glue: Full-featured, handles all types
join-strings: Optimized for string-only operations
keys-to-strings: Efficient object-based class generation
merge-module-strings: CSS Modules integration
merge-styles: Style object merging (React Native)

Contributing

Contributions are always welcome! Please read the contribution guidelines before getting started.

Reporting Issues

If you encounter any issues while using class-glue, please open an issue on the GitHub repository. Make sure to include a clear description, steps to reproduce the issue, and any relevant code snippets or error messages.

Author

Rahul Shetty

_{Lead Engineer & Open Source Enthusiast}

GitHub ・ Twitter ・ LinkedIn

Support

If you find class-glue useful, please consider:

Starring the repository ⭐
Supporting the project 💖
Contributing to the project 🤝
Sharing your feedback and ideas 💭
Referring to the project in your blog posts or articles 📝
Sharing the project with your friends and colleagues 👫

Thank you for your support! 🙏

Acknowledgements

class-glue is inspired by clsx, but with added features for TypeScript, CSS Modules, and React Native styles.

License

_{Built with ❤️ by Rahul Shetty and contributors}

Files

README.md

Latest commit

History