0
# Configuration
1

2
Advanced configuration system for extending or customizing tailwind-merge behavior with custom class groups, theme scales, and conflict resolution rules.
3

4
## Capabilities
5

6
### extendTailwindMerge
7

8
Function to create merge function with custom config that extends the default config. Use this if you use the default Tailwind config and just modified it in some places.
9

10
```typescript { .api }
11
/**
12
 * Create merge function with custom config which extends the default config
13
 * @param configExtension - Configuration extension object
14
 * @param createConfig - Additional config transformation functions
15
 * @returns Custom tailwind merge function
16
 */
17
function extendTailwindMerge<
18
  AdditionalClassGroupIds extends string = never,
19
  AdditionalThemeGroupIds extends string = never,
20
>(
21
  configExtension: ConfigExtension<
22
    DefaultClassGroupIds | AdditionalClassGroupIds,
23
    DefaultThemeGroupIds | AdditionalThemeGroupIds
24
  >,
25
  ...createConfig: CreateConfigSubsequent[]
26
): TailwindMerge;
27

28
/**
29
 * Create merge function using only config transformation functions
30
 */
31
function extendTailwindMerge<
32
  AdditionalClassGroupIds extends string = never,
33
  AdditionalThemeGroupIds extends string = never,
34
>(...createConfig: CreateConfigSubsequent[]): TailwindMerge;
35
```
36

37
**Usage Examples:**
38

39
```typescript
40
import { extendTailwindMerge, validators } from "tailwind-merge";
41

42
// Basic extension with custom class groups
43
type AdditionalClassGroupIds = 'aspect-w' | 'aspect-h' | 'aspect-reset';
44

45
const customTwMerge = extendTailwindMerge<AdditionalClassGroupIds>({
46
  // Override cache size (0 disables caching)
47
  cacheSize: 100,
48
  // Custom prefix from Tailwind config
49
  prefix: 'tw-',
50
  // Custom separator from Tailwind config  
51
  separator: '_',
52
  
53
  extend: {
54
    // Add custom class groups
55
    classGroups: {
56
      'aspect-w': [{ 'aspect-w': [(value) => Boolean(value) && !isNaN(value)] }],
57
      'aspect-h': [{ 'aspect-h': [(value) => Boolean(value) && !isNaN(value)] }],
58
      'aspect-reset': ['aspect-none'],
59
      // Use built-in validators
60
      'prose-size': [{ prose: ['base', validators.isTshirtSize] }],
61
    },
62
    // Define conflicts between class groups
63
    conflictingClassGroups: {
64
      'aspect-reset': ['aspect-w', 'aspect-h'],
65
    },
66
    // Extend theme scales
67
    theme: {
68
      spacing: ['sm', 'md', 'lg'],
69
    },
70
  },
71
  
72
  override: {
73
    // Override existing class groups completely
74
    classGroups: {
75
      shadow: [{ shadow: ['100', '200', '300', '400', '500'] }],
76
    },
77
    // Override theme scales
78
    theme: {
79
      colors: ['black', 'white', 'yellow-500'],
80
    },
81
  },
82
});
83

84
// Using custom merge function
85
customTwMerge('aspect-w-16 aspect-h-9', 'aspect-none');
86
// → 'aspect-none' (conflict resolved)
87
```
88

89
### createTailwindMerge
90

91
Function to create merge function with completely custom config. Use this instead of `extendTailwindMerge` if you don't need the default config or want more control.
92

93
```typescript { .api }
94
/**
95
 * Create merge function with completely custom config
96
 * @param createConfigFirst - Function returning the base config
97
 * @param createConfigRest - Additional config transformation functions
98
 * @returns Custom tailwind merge function
99
 */
100
function createTailwindMerge(
101
  createConfigFirst: () => AnyConfig,
102
  ...createConfigRest: CreateConfigSubsequent[]
103
): TailwindMerge;
104
```
105

106
**Usage Examples:**
107

108
```typescript
109
import { createTailwindMerge, getDefaultConfig } from "tailwind-merge";
110

111
// Create custom merge function from scratch
112
const customTwMerge = createTailwindMerge(() => ({
113
  cacheSize: 0,
114
  separator: ':',
115
  theme: {},
116
  classGroups: {
117
    foo: ['foo', 'foo-2', { 'bar-baz': ['', '1', '2'] }],
118
    bar: [{ qux: ['auto', (value) => Number(value) >= 1000] }],
119
    baz: ['baz-sm', 'baz-md', 'baz-lg'],
120
  },
121
  conflictingClassGroups: {
122
    foo: ['bar'],
123
  },
124
  conflictingClassGroupModifiers: {
125
    baz: ['bar'],
126
  },
127
}));
128

129
// Extend from default config
130
const extendedTwMerge = createTailwindMerge(
131
  getDefaultConfig,
132
  (config) => ({
133
    ...config,
134
    classGroups: {
135
      ...config.classGroups,
136
      mySpecialClassGroup: [{ special: ['1', '2'] }],
137
    },
138
  })
139
);
140
```
141

142
### getDefaultConfig
143

144
Function which returns the default config used by tailwind-merge.
145

146
```typescript { .api }
147
/**
148
 * Get the default configuration used by tailwind-merge
149
 * @returns Default configuration object
150
 */
151
function getDefaultConfig(): Config<DefaultClassGroupIds, DefaultThemeGroupIds>;
152
```
153

154
**Usage Examples:**
155

156
```typescript
157
import { getDefaultConfig } from "tailwind-merge";
158

159
const defaultConfig = getDefaultConfig();
160
console.log(defaultConfig.classGroups); // All default class groups
161
console.log(defaultConfig.theme); // Default theme scales
162
console.log(defaultConfig.conflictingClassGroups); // Default conflict rules
163
```
164

165
### mergeConfigs
166

167
Helper function to merge multiple tailwind-merge configurations safely.
168

169
```typescript { .api }
170
/**
171
 * Merge multiple tailwind-merge configurations
172
 * @param baseConfig - Base configuration to merge into (will be mutated)
173
 * @param configExtension - Configuration extension to merge
174
 * @returns Merged configuration
175
 */
176
function mergeConfigs<ClassGroupIds extends string, ThemeGroupIds extends string = never>(
177
  baseConfig: AnyConfig,
178
  configExtension: ConfigExtension<ClassGroupIds, ThemeGroupIds>
179
): AnyConfig;
180
```
181

182
**Usage Examples:**
183

184
```typescript
185
import { createTailwindMerge, getDefaultConfig, mergeConfigs } from "tailwind-merge";
186

187
const customTwMerge = createTailwindMerge(
188
  getDefaultConfig,
189
  (config) => mergeConfigs<'shadow' | 'animate' | 'prose'>(config, {
190
    override: {
191
      classGroups: {
192
        // Override existing class group
193
        shadow: [{ shadow: ['100', '200', '300', '400', '500'] }],
194
      },
195
    },
196
    extend: {
197
      classGroups: {
198
        // Add to existing class group
199
        animate: ['animate-shimmer'],
200
        // Add new class group
201
        prose: [{ prose: ['', validators.isTshirtSize] }],
202
      },
203
    },
204
  })
205
);
206
```
207

208
### fromTheme
209

210
Function to retrieve values from a theme scale, to be used in class group definitions.
211

212
```typescript { .api }
213
/**
214
 * Create theme getter function for accessing theme scale values
215
 * @param key - Theme scale key to access
216
 * @returns Theme getter function with isThemeGetter property
217
 */
218
function fromTheme<
219
  AdditionalThemeGroupIds extends string = never,
220
  DefaultThemeGroupIdsInner extends string = DefaultThemeGroupIds,
221
>(key: NoInfer<DefaultThemeGroupIdsInner | AdditionalThemeGroupIds>): ThemeGetter;
222

223
interface ThemeGetter {
224
  (theme: ThemeObject<AnyThemeGroupIds>): ClassGroup<AnyClassGroupIds>;
225
  isThemeGetter: true;
226
}
227
```
228

229
**Usage Examples:**
230

231
```typescript
232
import { extendTailwindMerge, fromTheme } from "tailwind-merge";
233

234
type AdditionalThemeGroupIds = 'my-scale';
235

236
const customTwMerge = extendTailwindMerge<string, AdditionalThemeGroupIds>({
237
  extend: {
238
    theme: {
239
      'my-scale': ['foo', 'bar'],
240
    },
241
    classGroups: {
242
      'my-group': [{
243
        'my-group': [
244
          fromTheme<AdditionalThemeGroupIds>('my-scale'),
245
          fromTheme('spacing'), // Built-in theme scale
246
        ],
247
      }],
248
    },
249
  },
250
});
251
```
252

253
## Configuration Types
254

255
```typescript { .api }
256
interface Config<ClassGroupIds extends string, ThemeGroupIds extends string>
257
  extends ConfigStaticPart, ConfigGroupsPart<ClassGroupIds, ThemeGroupIds> {}
258

259
interface ConfigStaticPart {
260
  /** Integer indicating size of LRU cache used for memoizing results */
261
  cacheSize: number;
262
  /** Prefix added to Tailwind-generated classes */
263
  prefix?: string;
264
  /** Custom separator for modifiers in Tailwind classes */
265
  separator: string;
266
  /** Experimental function to customize parsing of individual classes */
267
  experimentalParseClassName?(param: ExperimentalParseClassNameParam): ExperimentalParsedClassName;
268
}
269

270
interface ConfigExtension<ClassGroupIds extends string, ThemeGroupIds extends string>
271
  extends Partial<ConfigStaticPart> {
272
  /** Configuration properties to override completely */
273
  override?: PartialPartial<ConfigGroupsPart<ClassGroupIds, ThemeGroupIds>>;
274
  /** Configuration properties to extend/merge */
275
  extend?: PartialPartial<ConfigGroupsPart<ClassGroupIds, ThemeGroupIds>>;
276
}
277

278
type AnyConfig = Config<string, string>;
279
type CreateConfigSubsequent = (config: AnyConfig) => AnyConfig;
280
```