0
# Validation System
1

2
Comprehensive validation functions for different types of Tailwind class values, used in custom configurations and class group definitions.
3

4
## Capabilities
5

6
### Validators Module
7

8
Collection of validation functions used throughout tailwind-merge for validating different types of class values.
9

10
```typescript { .api }
11
/**
12
 * All validators available for use in custom configurations
13
 */
14
interface Validators {
15
  /** Validates length values (numbers, fractions, px, full, screen) */
16
  isLength(value: string): boolean;
17
  /** Validates arbitrary length values like [3%], [4px], [length:var(--my-var)] */
18
  isArbitraryLength(value: string): boolean;
19
  /** Validates numeric strings like '3', '1.5' */
20
  isNumber(value: string): boolean;
21
  /** Validates integer values like '3' */
22
  isInteger(value: string): boolean;
23
  /** Validates percentage values like '12.5%' */
24
  isPercent(value: string): boolean;
25
  /** Validates any arbitrary values enclosed in brackets [something] */
26
  isArbitraryValue(value: string): boolean;
27
  /** Validates T-shirt sizes like 'sm', 'xl', '2xl' */
28
  isTshirtSize(value: string): boolean;
29
  /** Validates arbitrary size values like [size:200px_100px] */
30
  isArbitrarySize(value: string): boolean;
31
  /** Validates arbitrary position values like [position:200px_100px] */
32
  isArbitraryPosition(value: string): boolean;
33
  /** Validates arbitrary image values like [url('/path.png')] */
34
  isArbitraryImage(value: string): boolean;
35
  /** Validates arbitrary number values like [number:var(--value)], [450] */
36
  isArbitraryNumber(value: string): boolean;
37
  /** Validates arbitrary shadow values like [0_35px_60px_-15px_rgba(0,0,0,0.3)] */
38
  isArbitraryShadow(value: string): boolean;
39
  /** Always returns true - catch-all validator (use carefully) */
40
  isAny(): boolean;
41
}
42
```
43

44
### Individual Validators
45

46
#### Length Validators
47

48
Validators for length-related values used in spacing, sizing, and positioning classes.
49

50
```typescript { .api }
51
/**
52
 * Validates length values including numbers, fractions, and special keywords
53
 * @param value - Value to validate
54
 * @returns True if value is a valid length
55
 */
56
function isLength(value: string): boolean;
57

58
/**
59
 * Validates arbitrary length values in bracket notation
60
 * @param value - Value to validate  
61
 * @returns True if value is a valid arbitrary length
62
 */
63
function isArbitraryLength(value: string): boolean;
64
```
65

66
**Usage Examples:**
67

68
```typescript
69
import { validators } from "tailwind-merge";
70

71
// isLength examples
72
validators.isLength('4'); // true - number
73
validators.isLength('1.5'); // true - decimal number
74
validators.isLength('3/4'); // true - fraction
75
validators.isLength('px'); // true - special keyword
76
validators.isLength('full'); // true - special keyword
77
validators.isLength('screen'); // true - special keyword
78
validators.isLength('invalid'); // false
79

80
// isArbitraryLength examples
81
validators.isArbitraryLength('[3%]'); // true
82
validators.isArbitraryLength('[4px]'); // true
83
validators.isArbitraryLength('[length:var(--my-var)]'); // true
84
validators.isArbitraryLength('[calc(100% - 2rem)]'); // true
85
validators.isArbitraryLength('4px'); // false - not in brackets
86
```
87

88
#### Numeric Validators
89

90
Validators for numeric values used in various contexts.
91

92
```typescript { .api }
93
/**
94
 * Validates numeric strings
95
 * @param value - Value to validate
96
 * @returns True if value is a valid number
97
 */
98
function isNumber(value: string): boolean;
99

100
/**
101
 * Validates integer values
102
 * @param value - Value to validate
103
 * @returns True if value is a valid integer
104
 */
105
function isInteger(value: string): boolean;
106

107
/**
108
 * Validates percentage values
109
 * @param value - Value to validate
110
 * @returns True if value is a valid percentage
111
 */
112
function isPercent(value: string): boolean;
113

114
/**
115
 * Validates arbitrary number values for font-weight and stroke-width
116
 * @param value - Value to validate
117
 * @returns True if value is a valid arbitrary number
118
 */
119
function isArbitraryNumber(value: string): boolean;
120
```
121

122
**Usage Examples:**
123

124
```typescript
125
import { validators } from "tailwind-merge";
126

127
// isNumber examples
128
validators.isNumber('3'); // true
129
validators.isNumber('1.5'); // true
130
validators.isNumber('0'); // true
131
validators.isNumber('abc'); // false
132

133
// isInteger examples  
134
validators.isInteger('3'); // true
135
validators.isInteger('1.5'); // false
136
validators.isInteger('0'); // true
137

138
// isPercent examples
139
validators.isPercent('12.5%'); // true
140
validators.isPercent('100%'); // true
141
validators.isPercent('12.5'); // false - no % sign
142

143
// isArbitraryNumber examples
144
validators.isArbitraryNumber('[number:var(--value)]'); // true
145
validators.isArbitraryNumber('[450]'); // true
146
validators.isArbitraryNumber('[number:calc(var(--weight) * 100)]'); // true
147
```
148

149
#### Size and Position Validators
150

151
Validators for size and position-related arbitrary values.
152

153
```typescript { .api }
154
/**
155
 * Validates T-shirt size values used in various utilities
156
 * @param value - Value to validate
157
 * @returns True if value is a valid T-shirt size
158
 */
159
function isTshirtSize(value: string): boolean;
160

161
/**
162
 * Validates arbitrary size values for background-size classes
163
 * @param value - Value to validate
164
 * @returns True if value is a valid arbitrary size
165
 */
166
function isArbitrarySize(value: string): boolean;
167

168
/**
169
 * Validates arbitrary position values for background-position classes
170
 * @param value - Value to validate
171
 * @returns True if value is a valid arbitrary position
172
 */
173
function isArbitraryPosition(value: string): boolean;
174
```
175

176
**Usage Examples:**
177

178
```typescript
179
import { validators } from "tailwind-merge";
180

181
// isTshirtSize examples
182
validators.isTshirtSize('sm'); // true
183
validators.isTshirtSize('xl'); // true
184
validators.isTshirtSize('2xl'); // true
185
validators.isTshirtSize('3.5xl'); // true
186
validators.isTshirtSize('large'); // false
187

188
// isArbitrarySize examples
189
validators.isArbitrarySize('[size:200px_100px]'); // true
190
validators.isArbitrarySize('[size:cover]'); // true
191
validators.isArbitrarySize('[size:50%_auto]'); // true
192

193
// isArbitraryPosition examples
194
validators.isArbitraryPosition('[position:200px_100px]'); // true
195
validators.isArbitraryPosition('[position:center_top]'); // true
196
validators.isArbitraryPosition('[position:50%_25%]'); // true
197
```
198

199
#### Media and Visual Validators
200

201
Validators for images, shadows, and other visual elements.
202

203
```typescript { .api }
204
/**
205
 * Validates arbitrary image values for background-image classes
206
 * @param value - Value to validate
207
 * @returns True if value is a valid arbitrary image
208
 */
209
function isArbitraryImage(value: string): boolean;
210

211
/**
212
 * Validates arbitrary shadow values matching shadow patterns
213
 * @param value - Value to validate
214
 * @returns True if value is a valid arbitrary shadow
215
 */
216
function isArbitraryShadow(value: string): boolean;
217
```
218

219
**Usage Examples:**
220

221
```typescript
222
import { validators } from "tailwind-merge";
223

224
// isArbitraryImage examples
225
validators.isArbitraryImage("[url('/path-to-image.png')]"); // true
226
validators.isArbitraryImage('[image:var(--bg-image)]'); // true
227
validators.isArbitraryImage('[linear-gradient(to_right,#000,#fff)]'); // true
228
validators.isArbitraryImage('[url(data:image/svg+xml;base64,...)]'); // true
229

230
// isArbitraryShadow examples
231
validators.isArbitraryShadow('[0_35px_60px_-15px_rgba(0,0,0,0.3)]'); // true
232
validators.isArbitraryShadow('[inset_0_2px_4px_rgba(0,0,0,0.1)]'); // true
233
validators.isArbitraryShadow('[0_0_0_1px_theme(colors.gray.300)]'); // true
234
```
235

236
#### Universal Validators
237

238
General-purpose validators for special cases.
239

240
```typescript { .api }
241
/**
242
 * Validates any arbitrary value enclosed in brackets
243
 * @param value - Value to validate
244
 * @returns True if value is enclosed in brackets
245
 */
246
function isArbitraryValue(value: string): boolean;
247

248
/**
249
 * Always returns true - use as catch-all validator
250
 * @returns Always true
251
 */
252
function isAny(): boolean;
253
```
254

255
**Usage Examples:**
256

257
```typescript
258
import { validators } from "tailwind-merge";
259

260
// isArbitraryValue examples
261
validators.isArbitraryValue('[anything]'); // true
262
validators.isArbitraryValue('[color:var(--custom)]'); // true
263
validators.isArbitraryValue('[length:100vh]'); // true
264
validators.isArbitraryValue('not-arbitrary'); // false
265

266
// isAny examples - use carefully!
267
validators.isAny(); // true (always)
268
validators.isAny('anything'); // true (always)
269

270
// Example: Using isAny in class group definition
271
const customTwMerge = extendTailwindMerge({
272
  extend: {
273
    classGroups: {
274
      // Accept any value for custom color classes
275
      'custom-color': [{ 'custom': [validators.isAny] }],
276
    },
277
  },
278
});
279
```
280

281
### Using Validators in Custom Configurations
282

283
Validators are primarily used when defining custom class groups in tailwind-merge configurations.
284

285
**Usage Examples:**
286

287
```typescript
288
import { extendTailwindMerge, validators } from "tailwind-merge";
289

290
const customTwMerge = extendTailwindMerge({
291
  extend: {
292
    classGroups: {
293
      // Use length validator for custom spacing
294
      'custom-spacing': [{ 'space': [validators.isLength] }],
295
      
296
      // Use T-shirt size validator for custom utilities
297
      'custom-size': [{ 'size': [validators.isTshirtSize] }],
298
      
299
      // Combine multiple validators
300
      'flexible-value': [{
301
        'flex-val': [
302
          validators.isNumber,
303
          validators.isArbitraryValue,
304
          validators.isTshirtSize
305
        ]
306
      }],
307
      
308
      // Custom validator function
309
      'even-numbers': [{
310
        'even': [(value) => validators.isInteger(value) && parseInt(value) % 2 === 0]
311
      }],
312
    },
313
  },
314
});
315
```
316

317
## Types
318

319
```typescript { .api }
320
type ClassValidator = (classPart: string) => boolean;
321
```