William-Owen / CN - React Class Name composeor

Last active 2 months ago

Like 0

This is a react utility to concatenate class names, including the ability to support conditional class names

react-utility

Revision e030d760f7884c477958137b1003268f6c9ba142

cn.mdx · 2.1 KiB · Text Raw

import { Meta } from '@storybook/addon-docs/blocks';

# cn (ClassNames) Utility Function

The `cn` utility function is a lightweight, performant solution for combining class names with conditional logic.

## Installation

```typescript
import { cn } from 'motoko/utils'
```

## API

```typescript
type Argument = string | boolean | null | undefined | number

cn(...args: Argument[]): string
```

## Examples

### Basic Usage
```typescript
// Basic conditional classes
cn('btn', true && 'active', false && 'disabled', 'large')
// Result: "btn active large"

// Falsy value filtering
cn('btn', null, undefined, false, 'primary')
// Result: "btn primary"
```

## Performance Notes

- Uses traditional for loops instead of for-of for ~20-40% better performance
- Single-pass algorithm with minimal string operations
- Optimized for common React component patterns

## Common Patterns

### Conditional Classes
```typescript
const className = cn(
  'base-class',
  isActive && 'active',
  isDisabled && 'disabled',
  variant && `variant-${variant}`
)
```

### CSS Modules
```typescript
import styles from './Component.module.scss'

const className = cn(
  styles.base,
  isError && styles.error,
  props.className
)
```

### Component Props
```typescript
interface ButtonProps {
  variant: 'primary' | 'secondary'
  disabled?: boolean
  className?: string
}

const Button = ({ variant, disabled, className, ...props }: ButtonProps) => (
  <button
    className={cn('btn', `btn--${variant}`, disabled && 'btn--disabled', className)}
    {...props}
  />
)
```

## Migration from clsx/classnames

Direct replacement for most use cases:

```typescript
// Before (clsx)
import clsx from 'clsx'
const className = clsx('btn', isActive && 'active')

// After (cn)
import { cn } from 'motoko/utils'
const className = cn('btn', isActive && 'active')
```

## Best Practices

1. **Order matters**: Place base classes first, then conditional classes
2. **Use with CSS Modules**: Perfect for scoped styling
3. **Component composition**: Always accept `className` prop for extensibility
4. **Performance**: Prefer `cn` over template literals for conditional classes

1	import { Meta } from '@storybook/addon-docs/blocks';
2
3	<Meta title="Utils/cn (ClassNames)" />
4
5	# cn (ClassNames) Utility Function
6
7	The `cn` utility function is a lightweight, performant solution for combining class names with conditional logic.
8
9	## Installation
10
11	```typescript
12	import { cn } from 'motoko/utils'
13	```
14
15	## API
16
17	```typescript
18	type Argument = string \| boolean \| null \| undefined \| number
19
20	cn(...args: Argument[]): string
21	```
22
23	## Examples
24
25	### Basic Usage
26	```typescript
27	// Basic conditional classes
28	cn('btn', true && 'active', false && 'disabled', 'large')
29	// Result: "btn active large"
30
31	// Falsy value filtering
32	cn('btn', null, undefined, false, 'primary')
33	// Result: "btn primary"
34	```
35
36	## Performance Notes
37
38	- Uses traditional for loops instead of for-of for ~20-40% better performance
39	- Single-pass algorithm with minimal string operations
40	- Optimized for common React component patterns
41
42	## Common Patterns
43
44	### Conditional Classes
45	```typescript
46	const className = cn(
47	'base-class',
48	isActive && 'active',
49	isDisabled && 'disabled',
50	variant && `variant-${variant}`
51	)
52	```
53
54	### CSS Modules
55	```typescript
56	import styles from './Component.module.scss'
57
58	const className = cn(
59	styles.base,
60	isError && styles.error,
61	props.className
62	)
63	```
64
65	### Component Props
66	```typescript
67	interface ButtonProps {
68	variant: 'primary' \| 'secondary'
69	disabled?: boolean
70	className?: string
71	}
72
73	const Button = ({ variant, disabled, className, ...props }: ButtonProps) => (
74	<button
75	className={cn('btn', `btn--${variant}`, disabled && 'btn--disabled', className)}
76	{...props}
77	/>
78	)
79	```
80
81	## Migration from clsx/classnames
82
83	Direct replacement for most use cases:
84
85	```typescript
86	// Before (clsx)
87	import clsx from 'clsx'
88	const className = clsx('btn', isActive && 'active')
89
90	// After (cn)
91	import { cn } from 'motoko/utils'
92	const className = cn('btn', isActive && 'active')
93	```
94
95	## Best Practices
96
97	1. Order matters: Place base classes first, then conditional classes
98	2. Use with CSS Modules: Perfect for scoped styling
99	3. Component composition: Always accept `className` prop for extensibility
100	4. Performance: Prefer `cn` over template literals for conditional classes
101

cn.test.ts · 6.2 KiB · TypeScript Raw

/** biome-ignore-all lint/correctness/noUnusedFunctionParameters: Required for Testing */
/** biome-ignore-all lint/complexity/useSimplifiedLogicExpression: Required for Testing */
import { describe, expect, it } from "vitest"
import { cn } from "./"

describe("bcn utility", () => {
	describe("basic functionality", () => {
		it("joins string arguments with spaces", () => {
			expect(cn("button", "primary", "large")).toBe("button primary large")
		})

it("handles single string argument", () => {
			expect(cn("button")).toBe("button")
		})

it("returns empty string when no arguments", () => {
			expect(cn()).toBe("")
		})

it("handles empty string arguments", () => {
			expect(cn("", "button", "")).toBe("button")
		})
	})

describe("falsy value filtering", () => {
		it("filters out false values", () => {
			expect(cn("button", false, "active")).toBe("button active")
		})

it("filters out null values", () => {
			expect(cn("button", null, "active")).toBe("button active")
		})

it("filters out undefined values", () => {
			expect(cn("button", undefined, "active")).toBe("button active")
		})

it("filters out all falsy values", () => {
			expect(cn("button", false, null, undefined, "active")).toBe("button active")
		})

it("returns empty string when all arguments are falsy", () => {
			expect(cn(false, null, undefined)).toBe("")
		})
	})

describe("conditional expressions", () => {
		it("handles boolean && string expressions (truthy)", () => {
			const isActive = true
			expect(cn("button", isActive && "active")).toBe("button active")
		})

it("handles boolean && string expressions (falsy)", () => {
			const isActive = false
			expect(cn("button", isActive && "active")).toBe("button")
		})

it("handles complex conditional logic", () => {
			const isDisabled = false
			const isPrimary = true
			const size = "large"

expect(
				cn(
					"button",
					isPrimary && "button-primary",
					isDisabled && "button-disabled",
					size === "large" && "button-large",
				),
			).toBe("button button-primary button-large")
		})
	})

describe("space-separated string flattening", () => {
		it("flattens single space-separated string", () => {
			expect(cn("button primary large")).toBe("button primary large")
		})

it("flattens multiple space-separated strings", () => {
			expect(cn("button primary", "large disabled")).toBe("button primary large disabled")
		})

it("handles mixed single and space-separated strings", () => {
			expect(cn("button", "primary large", "disabled")).toBe("button primary large disabled")
		})

it("handles multiple spaces within strings", () => {
			expect(cn("button  primary", "large   disabled")).toBe("button primary large disabled")
		})

it("handles leading and trailing spaces", () => {
			expect(cn(" button primary ", " large disabled ")).toBe("button primary large disabled")
		})

it("handles tabs and other whitespace", () => {
			expect(cn("button\tprimary", "large\ndisabled")).toBe("button primary large disabled")
		})
	})

describe("real-world usage patterns", () => {
		it("works with React component className patterns", () => {
			const isActive = true
			const isDisabled = false
			const variant = "primary"
			const size = "large"

expect(
				cn(
					"button",
					`button--${variant}`,
					`button--${size}`,
					isActive && "button--active",
					isDisabled && "button--disabled",
				),
			).toBe("button button--primary button--large button--active")
		})

it("works with CSS modules pattern", () => {
			const styles = {
				button: "button_abc123",
				primary: "primary_def456",
				active: "active_ghi789",
			}
			const isActive = true

expect(cn(styles.button, styles.primary, isActive && styles.active)).toBe(
				"button_abc123 primary_def456 active_ghi789",
			)
		})

it("handles utility class combinations", () => {
			expect(cn("flex items-center", "px-4 py-2", "bg-blue-500 text-white")).toBe(
				"flex items-center px-4 py-2 bg-blue-500 text-white",
			)
		})
	})

describe("edge cases", () => {
		it("handles strings with only whitespace", () => {
			expect(cn("   ", "button", "  ")).toBe("button")
		})

it("handles very long class lists", () => {
			const longClassList = Array(100).fill("class").join(" ")
			expect(cn(longClassList)).toBe(Array(100).fill("class").join(" "))
		})

it("handles special characters in class names", () => {
			expect(cn("button-primary_large", "icon:before")).toBe("button-primary_large icon:before")
		})

it("handles numbers in class names", () => {
			expect(cn("col-12", "mt-4", "z-10")).toBe("col-12 mt-4 z-10")
		})

it("handles unicode characters", () => {
			expect(cn("button-🚀", "icon-✨")).toBe("button-🚀 icon-✨")
		})
	})

describe("performance considerations", () => {
		it("handles large number of arguments efficiently", () => {
			const manyArgs = Array(1000)
				.fill(null)
				.map((_, i) => (i % 2 === 0 ? `class-${i}` : false))
			const result = cn(...manyArgs)

// Should contain only even-indexed classes
			expect(result).toContain("class-0")
			expect(result).toContain("class-998")
			expect(result).not.toContain("undefined")
		})

it("handles empty arrays and complex nested conditionals", () => {
			const conditions = [
				true && "a", // "a" (truthy)
				false && "b", // false (falsy)
				null, // null (falsy)
				undefined, // undefined (falsy)
				"" as string, // "" (falsy - empty string)
				0 as number, // 0 (falsy - zero)
				"valid-class", // "valid-class" (truthy)
			]
			expect(cn(...conditions)).toBe("a valid-class")
		})
	})

describe("type safety", () => {
		it("maintains type safety with proper arguments", () => {
			// These should not cause TypeScript errors
			const validUsages = [
				cn("string"),
				cn(true && "conditional"),
				cn(false && "wont-show"),
				cn(null),
				cn(undefined),
				cn("multiple", "classes", true && "conditional"),
			]

validUsages.forEach(usage => {
				expect(typeof usage).toBe("string")
			})
		})
	})

describe("documentation examples", () => {
		it("matches first documentation example", () => {
			const isActive = true
			expect(cn("button", isActive && "active", "large")).toBe("button active large")
		})

it("matches second documentation example", () => {
			expect(cn("button primary", false, null, "disabled")).toBe("button primary disabled")
		})
	})
})

1	/** biome-ignore-all lint/correctness/noUnusedFunctionParameters: Required for Testing */
2	/** biome-ignore-all lint/complexity/useSimplifiedLogicExpression: Required for Testing */
3	import { describe, expect, it } from "vitest"
4	import { cn } from "./"
5
6	describe("bcn utility", () => {
7	describe("basic functionality", () => {
8	it("joins string arguments with spaces", () => {
9	expect(cn("button", "primary", "large")).toBe("button primary large")
10	})
11
12	it("handles single string argument", () => {
13	expect(cn("button")).toBe("button")
14	})
15
16	it("returns empty string when no arguments", () => {
17	expect(cn()).toBe("")
18	})
19
20	it("handles empty string arguments", () => {
21	expect(cn("", "button", "")).toBe("button")
22	})
23	})
24
25	describe("falsy value filtering", () => {
26	it("filters out false values", () => {
27	expect(cn("button", false, "active")).toBe("button active")
28	})
29
30	it("filters out null values", () => {
31	expect(cn("button", null, "active")).toBe("button active")
32	})
33
34	it("filters out undefined values", () => {
35	expect(cn("button", undefined, "active")).toBe("button active")
36	})
37
38	it("filters out all falsy values", () => {
39	expect(cn("button", false, null, undefined, "active")).toBe("button active")
40	})
41
42	it("returns empty string when all arguments are falsy", () => {
43	expect(cn(false, null, undefined)).toBe("")
44	})
45	})
46
47	describe("conditional expressions", () => {
48	it("handles boolean && string expressions (truthy)", () => {
49	const isActive = true
50	expect(cn("button", isActive && "active")).toBe("button active")
51	})
52
53	it("handles boolean && string expressions (falsy)", () => {
54	const isActive = false
55	expect(cn("button", isActive && "active")).toBe("button")
56	})
57
58	it("handles complex conditional logic", () => {
59	const isDisabled = false
60	const isPrimary = true
61	const size = "large"
62
63	expect(
64	cn(
65	"button",
66	isPrimary && "button-primary",
67	isDisabled && "button-disabled",
68	size === "large" && "button-large",
69	),
70	).toBe("button button-primary button-large")
71	})
72	})
73
74	describe("space-separated string flattening", () => {
75	it("flattens single space-separated string", () => {
76	expect(cn("button primary large")).toBe("button primary large")
77	})
78
79	it("flattens multiple space-separated strings", () => {
80	expect(cn("button primary", "large disabled")).toBe("button primary large disabled")
81	})
82
83	it("handles mixed single and space-separated strings", () => {
84	expect(cn("button", "primary large", "disabled")).toBe("button primary large disabled")
85	})
86
87	it("handles multiple spaces within strings", () => {
88	expect(cn("button primary", "large disabled")).toBe("button primary large disabled")
89	})
90
91	it("handles leading and trailing spaces", () => {
92	expect(cn(" button primary ", " large disabled ")).toBe("button primary large disabled")
93	})
94
95	it("handles tabs and other whitespace", () => {
96	expect(cn("button\tprimary", "large\ndisabled")).toBe("button primary large disabled")
97	})
98	})
99
100	describe("real-world usage patterns", () => {
101	it("works with React component className patterns", () => {
102	const isActive = true
103	const isDisabled = false
104	const variant = "primary"
105	const size = "large"
106
107	expect(
108	cn(
109	"button",
110	`button--${variant}`,
111	`button--${size}`,
112	isActive && "button--active",
113	isDisabled && "button--disabled",
114	),
115	).toBe("button button--primary button--large button--active")
116	})
117
118	it("works with CSS modules pattern", () => {
119	const styles = {
120	button: "button_abc123",
121	primary: "primary_def456",
122	active: "active_ghi789",
123	}
124	const isActive = true
125
126	expect(cn(styles.button, styles.primary, isActive && styles.active)).toBe(
127	"button_abc123 primary_def456 active_ghi789",
128	)
129	})
130
131	it("handles utility class combinations", () => {
132	expect(cn("flex items-center", "px-4 py-2", "bg-blue-500 text-white")).toBe(
133	"flex items-center px-4 py-2 bg-blue-500 text-white",
134	)
135	})
136	})
137
138	describe("edge cases", () => {
139	it("handles strings with only whitespace", () => {
140	expect(cn(" ", "button", " ")).toBe("button")
141	})
142
143	it("handles very long class lists", () => {
144	const longClassList = Array(100).fill("class").join(" ")
145	expect(cn(longClassList)).toBe(Array(100).fill("class").join(" "))
146	})
147
148	it("handles special characters in class names", () => {
149	expect(cn("button-primary_large", "icon:before")).toBe("button-primary_large icon:before")
150	})
151
152	it("handles numbers in class names", () => {
153	expect(cn("col-12", "mt-4", "z-10")).toBe("col-12 mt-4 z-10")
154	})
155
156	it("handles unicode characters", () => {
157	expect(cn("button-🚀", "icon-✨")).toBe("button-🚀 icon-✨")
158	})
159	})
160
161	describe("performance considerations", () => {
162	it("handles large number of arguments efficiently", () => {
163	const manyArgs = Array(1000)
164	.fill(null)
165	.map((_, i) => (i % 2 === 0 ? `class-${i}` : false))
166	const result = cn(...manyArgs)
167
168	// Should contain only even-indexed classes
169	expect(result).toContain("class-0")
170	expect(result).toContain("class-998")
171	expect(result).not.toContain("undefined")
172	})
173
174	it("handles empty arrays and complex nested conditionals", () => {
175	const conditions = [
176	true && "a", // "a" (truthy)
177	false && "b", // false (falsy)
178	null, // null (falsy)
179	undefined, // undefined (falsy)
180	"" as string, // "" (falsy - empty string)
181	0 as number, // 0 (falsy - zero)
182	"valid-class", // "valid-class" (truthy)
183	]
184	expect(cn(...conditions)).toBe("a valid-class")
185	})
186	})
187
188	describe("type safety", () => {
189	it("maintains type safety with proper arguments", () => {
190	// These should not cause TypeScript errors
191	const validUsages = [
192	cn("string"),
193	cn(true && "conditional"),
194	cn(false && "wont-show"),
195	cn(null),
196	cn(undefined),
197	cn("multiple", "classes", true && "conditional"),
198	]
199
200	validUsages.forEach(usage => {
201	expect(typeof usage).toBe("string")
202	})
203	})
204	})
205
206	describe("documentation examples", () => {
207	it("matches first documentation example", () => {
208	const isActive = true
209	expect(cn("button", isActive && "active", "large")).toBe("button active large")
210	})
211
212	it("matches second documentation example", () => {
213	expect(cn("button primary", false, null, "disabled")).toBe("button primary disabled")
214	})
215	})
216	})
217

index.ts · 1.6 KiB · TypeScript Raw

type Argument = string | boolean | null | undefined | number

/**
 *
 * Combines multiple class name arguments, automatically filtering out falsy values
 * (false, null, undefined) and normalizing any extra whitespace within or between
 * class names. Supports conditionally joining class names into a single string.
 *
 * @param args - Class name strings or conditional expressions that resolve to strings/booleans
 * @returns A single normalized class name string with no extra whitespace
 *
 * @example
 * Basic usage with conditional classes:
 * ```typescript
 * cn('btn', isActive && 'active', 'large')
 * // Returns: "btn active large" (when isActive is true)
 * // Returns: "btn large" (when isActive is false)
 * ```
 *
 * @example
 * Handling multiple spaces and falsy values:
 * ```typescript
 * cn('btn  primary', false, null, 'disabled')
 * // Returns: "btn primary disabled"
 * ```
 *
 * @example
 * Component usage pattern:
 * ```typescript
 * const Button = ({ variant, disabled, className }) => (
 *   <button className={cn('btn', `btn--${variant}`, disabled && 'btn--disabled', className)}>
 *     Click me
 *   </button>
 * )
 * ```
 *
 * @example
 * CSS Modules usage:
 * ```typescript
 * import styles from './Component.module.scss'
 *
 * const className = cn(styles.base, isError && styles.error, props.className)
 * ```
 *
 * @since 0.1.0
 * @category Utilities
 */
export const cn = (...args: Argument[]): string => {
	let result = ""

for (let i = 0; i < args.length; i++) {
		const arg = args[i]
		if (arg) {
			if (result) result += " "
			result += arg
		}
	}

return result.split(/\s+/).filter(Boolean).join(" ")
}

1	type Argument = string \| boolean \| null \| undefined \| number
2
3	/**
4	*
5	* Combines multiple class name arguments, automatically filtering out falsy values
6	* (false, null, undefined) and normalizing any extra whitespace within or between
7	* class names. Supports conditionally joining class names into a single string.
8	*
9	* @param args - Class name strings or conditional expressions that resolve to strings/booleans
10	* @returns A single normalized class name string with no extra whitespace
11	*
12	* @example
13	* Basic usage with conditional classes:
14	* ```typescript
15	* cn('btn', isActive && 'active', 'large')
16	* // Returns: "btn active large" (when isActive is true)
17	* // Returns: "btn large" (when isActive is false)
18	* ```
19	*
20	* @example
21	* Handling multiple spaces and falsy values:
22	* ```typescript
23	* cn('btn primary', false, null, 'disabled')
24	* // Returns: "btn primary disabled"
25	* ```
26	*
27	* @example
28	* Component usage pattern:
29	* ```typescript
30	* const Button = ({ variant, disabled, className }) => (
31	* <button className={cn('btn', `btn--${variant}`, disabled && 'btn--disabled', className)}>
32	* Click me
33	* </button>
34	* )
35	* ```
36	*
37	* @example
38	* CSS Modules usage:
39	* ```typescript
40	* import styles from './Component.module.scss'
41	*
42	* const className = cn(styles.base, isError && styles.error, props.className)
43	* ```
44	*
45	* @since 0.1.0
46	* @category Utilities
47	*/
48	export const cn = (...args: Argument[]): string => {
49	let result = ""
50
51	for (let i = 0; i < args.length; i++) {
52	const arg = args[i]
53	if (arg) {
54	if (result) result += " "
55	result += arg
56	}
57	}
58
59	return result.split(/\s+/).filter(Boolean).join(" ")
60	}
61