0
# Core Functions
1

2
Core functionality for merging and joining Tailwind CSS classes with intelligent conflict resolution and conditional handling.
3

4
## Capabilities
5

6
### twMerge
7

8
Main function to merge Tailwind CSS classes without style conflicts. Uses the default configuration and intelligent conflict resolution.
9

10
```typescript { .api }
11
/**
12
 * Default function to merge Tailwind CSS classes without style conflicts
13
 * @param classLists - Class name values to merge
14
 * @returns Merged class string with conflicts resolved
15
 */
16
function twMerge(...classLists: ClassNameValue[]): string;
17
```
18

19
**Usage Examples:**
20

21
```typescript
22
import { twMerge } from "tailwind-merge";
23

24
// Basic conflict resolution - later classes override earlier ones
25
twMerge('px-2 py-1 bg-red hover:bg-dark-red', 'p-3 bg-[#B91C1C]');
26
// → 'hover:bg-dark-red p-3 bg-[#B91C1C]'
27

28
// Handle conditional classes
29
const isActive = true;
30
const size = 'large';
31
twMerge(
32
  'px-4 py-2 rounded-md',
33
  isActive && 'bg-blue-500 text-white',
34
  !isActive && 'bg-gray-200 text-gray-700',
35
  size === 'large' && 'px-6 py-3 text-lg'
36
);
37

38
// Complex merging with multiple conflicts
39
twMerge('text-sm text-red-500 hover:text-blue-500', 'text-lg hover:text-green-500');
40
// → 'text-lg hover:text-green-500'
41

42
// Handle arrays and nested values
43
twMerge('p-4', ['m-2', null, false, ['text-center', undefined]]);
44
// → 'p-4 m-2 text-center'
45
```
46

47
### twJoin
48

49
Function to join className strings conditionally without resolving conflicts. Similar to clsx but optimized for Tailwind classes.
50

51
```typescript { .api }
52
/**
53
 * Join className strings conditionally without resolving conflicts
54
 * @param classLists - Class name values to join
55
 * @returns Joined class string without conflict resolution
56
 */
57
function twJoin(...classLists: ClassNameValue[]): string;
58
```
59

60
**Usage Examples:**
61

62
```typescript
63
import { twJoin } from "tailwind-merge";
64

65
// Basic joining without conflict resolution
66
twJoin('px-2 py-1 bg-red', 'p-3 bg-blue');
67
// → 'px-2 py-1 bg-red p-3 bg-blue' (no conflicts resolved)
68

69
// Conditional joining
70
const hasBackground = true;
71
const hasLargeText = false;
72
const hasLargeSpacing = true;
73

74
twJoin(
75
  'border border-red-500',
76
  hasBackground && 'bg-red-100',
77
  hasLargeText && 'text-lg',
78
  hasLargeSpacing && ['p-2', hasLargeText ? 'leading-8' : 'leading-7']
79
);
80
// → 'border border-red-500 bg-red-100 p-2 leading-7'
81

82
// Handle falsy values
83
twJoin('base-class', null, undefined, false, 0, '', 'actual-class');
84
// → 'base-class actual-class'
85
```
86

87
### Performance Characteristics
88

89
- **twMerge**: Uses LRU caching for repeated class combinations, optimized for conflict resolution
90
- **twJoin**: Faster than twMerge when no conflict resolution needed, smaller bundle impact
91
- Both functions handle nested arrays and conditional values efficiently
92
- twMerge lazy-initializes configuration on first use for optimal startup performance
93

94
### When to Use Each Function
95

96
**Use `twMerge` when:**
97
- You need intelligent conflict resolution between Tailwind classes
98
- Working with component libraries where class conflicts are common
99
- Building dynamic UIs with conditional styling that may conflict
100
- Performance is important and you benefit from caching repeated combinations
101

102
**Use `twJoin` when:**
103
- You only need conditional class joining without conflict resolution
104
- Bundle size is critical (twJoin is smaller)
105
- You're certain no conflicting classes will be passed
106
- You need clsx-like functionality specifically for Tailwind classes
107

108
## Types
109

110
```typescript { .api }
111
type ClassNameValue = ClassNameArray | string | null | undefined | 0 | 0n | false;
112
type ClassNameArray = ClassNameValue[];
113
type TailwindMerge = (...classLists: ClassNameValue[]) => string;
114
```