0
# Color Modification
1

2
Chainable methods for modifying color properties including lightening, darkening, saturation adjustments, hue rotation, and alpha channel manipulation. All modification methods return a new tinycolor instance, making them chainable.
3

4
## Capabilities
5

6
### Alpha Channel Modification
7

8
#### Set Alpha Value
9

10
Sets the alpha (transparency) value of the color.
11

12
```javascript { .api }
13
/**
14
 * Sets the alpha value and returns this instance
15
 * @param value - Alpha value between 0 (transparent) and 1 (opaque)
16
 * @returns tinycolor instance (chainable)
17
 */
18
setAlpha(value: number): tinycolor;
19
```
20

21
**Usage Examples:**
22

23
```javascript
24
import tinycolor from "tinycolor2";
25

26
const red = tinycolor("red");
27
const semiTransparent = red.setAlpha(0.5);
28
const almostTransparent = red.setAlpha(0.1);
29

30
console.log(red.toRgbString());                    // "rgb(255, 0, 0)"
31
console.log(semiTransparent.toRgbString());        // "rgba(255, 0, 0, 0.5)"
32
console.log(almostTransparent.toRgbString());      // "rgba(255, 0, 0, 0.1)"
33

34
// Chain with other modifications
35
const result = tinycolor("blue")
36
  .lighten(20)
37
  .setAlpha(0.7)
38
  .toRgbString();
39
```
40

41
### Lightness Modification
42

43
#### Lighten Color
44

45
Lightens the color by increasing the lightness value in HSL space.
46

47
```javascript { .api }
48
/**
49
 * Lightens the color by the specified amount
50
 * @param amount - Percentage to lighten (0-100), default is 10
51
 * @returns new tinycolor instance (chainable)
52
 */
53
lighten(amount?: number): tinycolor;
54
```
55

56
**Usage Examples:**
57

58
```javascript
59
const darkBlue = tinycolor("#000080");
60

61
const lightened10 = darkBlue.lighten();    // Default 10%
62
const lightened25 = darkBlue.lighten(25);  // Lighten by 25%
63
const lightened50 = darkBlue.lighten(50);  // Lighten by 50%
64

65
console.log(darkBlue.toHexString());     // "#000080"
66
console.log(lightened10.toHexString());  // "#1a1a99"
67
console.log(lightened25.toHexString());  // "#4040bf"
68
console.log(lightened50.toHexString());  // "#8080ff"
69

70
// Create a lightness scale
71
const baseColor = tinycolor("#2c3e50");
72
const scale = [0, 10, 20, 30, 40, 50].map(amount => 
73
  baseColor.lighten(amount).toHexString()
74
);
75
```
76

77
#### Darken Color
78

79
Darkens the color by decreasing the lightness value in HSL space.
80

81
```javascript { .api }
82
/**
83
 * Darkens the color by the specified amount
84
 * @param amount - Percentage to darken (0-100), default is 10
85
 * @returns new tinycolor instance (chainable)
86
 */
87
darken(amount?: number): tinycolor;
88
```
89

90
**Usage Examples:**
91

92
```javascript
93
const lightGreen = tinycolor("#90EE90");
94

95
const darkened10 = lightGreen.darken();     // Default 10%
96
const darkened25 = lightGreen.darken(25);   // Darken by 25%
97
const darkened50 = lightGreen.darken(50);   // Darken by 50%
98

99
console.log(lightGreen.toHexString());   // "#90ee90"
100
console.log(darkened10.toHexString());   // "#7dd97d"
101
console.log(darkened25.toHexString());   // "#59c359"
102
console.log(darkened50.toHexString());   // "#2d912d"
103

104
// Create hover effects
105
const buttonColor = tinycolor("#3498db");
106
const hoverColor = buttonColor.darken(10);
107
const activeColor = buttonColor.darken(20);
108
```
109

110
### Brightness Modification
111

112
#### Brighten Color
113

114
Brightens the color by adjusting RGB values directly (different from lighten).
115

116
```javascript { .api }
117
/**
118
 * Brightens the color by adjusting RGB values
119
 * @param amount - Percentage to brighten (0-100), default is 10
120
 * @returns new tinycolor instance (chainable)
121
 */
122
brighten(amount?: number): tinycolor;
123
```
124

125
**Usage Examples:**
126

127
```javascript
128
const gray = tinycolor("#808080");
129

130
const brightened = gray.brighten(20);
131

132
console.log(gray.toHexString());        // "#808080"
133
console.log(brightened.toHexString());  // "#b3b3b3"
134

135
// Compare brighten vs lighten
136
const color = tinycolor("#4a90e2");
137
const brightened = color.brighten(20);
138
const lightened = color.lighten(20);
139

140
console.log("Original:", color.toHexString());      // "#4a90e2"
141
console.log("Brightened:", brightened.toHexString()); // Different result
142
console.log("Lightened:", lightened.toHexString());   // Different result
143
```
144

145
### Saturation Modification
146

147
#### Desaturate Color
148

149
Reduces the saturation of the color, making it more gray.
150

151
```javascript { .api }
152
/**
153
 * Desaturates the color by the specified amount
154
 * @param amount - Percentage to desaturate (0-100), default is 10
155
 * @returns new tinycolor instance (chainable)
156
 */
157
desaturate(amount?: number): tinycolor;
158
```
159

160
**Usage Examples:**
161

162
```javascript
163
const vibrantRed = tinycolor("#ff0000");
164

165
const desaturated10 = vibrantRed.desaturate();     // Default 10%
166
const desaturated50 = vibrantRed.desaturate(50);   // 50% less saturated
167
const desaturated100 = vibrantRed.desaturate(100); // Completely desaturated
168

169
console.log(vibrantRed.toHexString());     // "#ff0000"
170
console.log(desaturated10.toHexString());  // "#f20d0d"
171
console.log(desaturated50.toHexString());  // "#bf4040"
172
console.log(desaturated100.toHexString()); // "#808080"
173

174
// Create muted color palette
175
const baseColors = ["#e74c3c", "#3498db", "#2ecc71"];
176
const mutedPalette = baseColors.map(color => 
177
  tinycolor(color).desaturate(30).toHexString()
178
);
179
```
180

181
#### Saturate Color
182

183
Increases the saturation of the color, making it more vibrant.
184

185
```javascript { .api }
186
/**
187
 * Saturates the color by the specified amount
188
 * @param amount - Percentage to saturate (0-100), default is 10
189
 * @returns new tinycolor instance (chainable)
190
 */
191
saturate(amount?: number): tinycolor;
192
```
193

194
**Usage Examples:**
195

196
```javascript
197
const mutedBlue = tinycolor("#6699cc");
198

199
const saturated10 = mutedBlue.saturate();     // Default 10%
200
const saturated30 = mutedBlue.saturate(30);   // Much more vibrant
201
const saturated50 = mutedBlue.saturate(50);   // Very vibrant
202

203
console.log(mutedBlue.toHexString());    // "#6699cc"
204
console.log(saturated10.toHexString());  // "#5fa3d9"
205
console.log(saturated30.toHexString());  // "#4db8f2"
206
console.log(saturated50.toHexString());  // "#3dc7ff"
207

208
// Enhance dull colors
209
function enhanceColor(colorInput, boost = 20) {
210
  return tinycolor(colorInput).saturate(boost);
211
}
212
```
213

214
#### Convert to Grayscale
215

216
Completely removes saturation, converting the color to grayscale.
217

218
```javascript { .api }
219
/**
220
 * Converts the color to grayscale (removes all saturation)
221
 * @returns new tinycolor instance (chainable)
222
 */
223
greyscale(): tinycolor;
224
```
225

226
**Usage Examples:**
227

228
```javascript
229
const rainbow = [
230
  tinycolor("red"),
231
  tinycolor("orange"), 
232
  tinycolor("yellow"),
233
  tinycolor("green"),
234
  tinycolor("blue"),
235
  tinycolor("purple")
236
];
237

238
const grayscale = rainbow.map(color => color.greyscale());
239

240
console.log("Original:", rainbow.map(c => c.toHexString()));
241
console.log("Grayscale:", grayscale.map(c => c.toHexString()));
242

243
// Create grayscale version of image colors
244
function toGrayscale(color) {
245
  return tinycolor(color).greyscale().toHexString();
246
}
247
```
248

249
### Hue Modification
250

251
#### Spin Hue
252

253
Rotates the hue by the specified number of degrees.
254

255
```javascript { .api }
256
/**
257
 * Rotates the hue by the specified degrees
258
 * @param amount - Degrees to rotate hue (-360 to 360)
259
 * @returns new tinycolor instance (chainable)
260
 */
261
spin(amount: number): tinycolor;
262
```
263

264
**Usage Examples:**
265

266
```javascript
267
const red = tinycolor("red");
268

269
const orange = red.spin(30);     // Rotate 30 degrees clockwise
270
const purple = red.spin(-60);    // Rotate 60 degrees counter-clockwise
271
const cyan = red.spin(180);      // Rotate 180 degrees (complement)
272

273
console.log(red.toHexString());    // "#ff0000"
274
console.log(orange.toHexString()); // "#ff8000"
275
console.log(purple.toHexString()); // "#8000ff"
276
console.log(cyan.toHexString());   // "#00ffff"
277

278
// Create color wheel
279
const baseHue = tinycolor("#ff0000");
280
const colorWheel = [];
281
for (let i = 0; i < 12; i++) {
282
  colorWheel.push(baseHue.spin(i * 30).toHexString());
283
}
284

285
// Animate hue rotation
286
function animateHue(startColor, steps = 12) {
287
  const colors = [];
288
  const step = 360 / steps;
289
  for (let i = 0; i < steps; i++) {
290
    colors.push(tinycolor(startColor).spin(i * step).toHexString());
291
  }
292
  return colors;
293
}
294
```
295

296
### Color Cloning
297

298
#### Clone Color
299

300
Creates a new independent copy of the color.
301

302
```javascript { .api }
303
/**
304
 * Creates a new tinycolor instance with the same color values
305
 * @returns new tinycolor instance
306
 */
307
clone(): tinycolor;
308
```
309

310
**Usage Examples:**
311

312
```javascript
313
const original = tinycolor("#3498db");
314
const copy = original.clone();
315

316
// Modify copy independently
317
const modified = copy.lighten(20).saturate(10);
318

319
console.log(original.toHexString()); // "#3498db" (unchanged)
320
console.log(modified.toHexString()); // "#5dade8" (modified copy)
321

322
// Safe color modifications
323
function safeModify(color, modifications) {
324
  let result = color.clone();
325
  
326
  if (modifications.lighten) result = result.lighten(modifications.lighten);
327
  if (modifications.darken) result = result.darken(modifications.darken);
328
  if (modifications.saturate) result = result.saturate(modifications.saturate);
329
  if (modifications.desaturate) result = result.desaturate(modifications.desaturate);
330
  if (modifications.spin) result = result.spin(modifications.spin);
331
  if (modifications.alpha !== undefined) result = result.setAlpha(modifications.alpha);
332
  
333
  return result;
334
}
335
```
336

337
## Chaining Examples
338

339
### Complex Color Transformations
340

341
```javascript
342
// Create a sophisticated color transformation
343
const baseColor = tinycolor("#2c3e50");
344

345
const transformed = baseColor
346
  .lighten(15)        // Make it lighter
347
  .saturate(20)       // Make it more vibrant
348
  .spin(45)           // Shift hue
349
  .setAlpha(0.8);     // Add transparency
350

351
console.log(baseColor.toHexString());   // "#2c3e50"
352
console.log(transformed.toRgbString()); // "rgba(91, 142, 125, 0.8)"
353

354
// Create color variations
355
const primary = tinycolor("#e74c3c");
356
const variations = {
357
  light: primary.clone().lighten(20),
358
  dark: primary.clone().darken(20),
359
  muted: primary.clone().desaturate(30),
360
  bright: primary.clone().saturate(20).brighten(10),
361
  complement: primary.clone().spin(180),
362
  transparent: primary.clone().setAlpha(0.3)
363
};
364
```
365

366
### Responsive Color Themes
367

368
```javascript
369
function createTheme(primaryColor, options = {}) {
370
  const base = tinycolor(primaryColor);
371
  const {
372
    lightAmount = 20,
373
    darkAmount = 20,
374
    mutedAmount = 30,
375
    accentSpin = 180
376
  } = options;
377
  
378
  return {
379
    primary: base.toHexString(),
380
    light: base.clone().lighten(lightAmount).toHexString(),
381
    dark: base.clone().darken(darkAmount).toHexString(),
382
    muted: base.clone().desaturate(mutedAmount).toHexString(),
383
    accent: base.clone().spin(accentSpin).toHexString(),
384
    success: base.clone().spin(120).saturate(10).toHexString(),
385
    warning: base.clone().spin(45).saturate(20).toHexString(),
386
    error: base.clone().spin(-30).saturate(15).toHexString()
387
  };
388
}
389

390
const blueTheme = createTheme("#3498db");
391
const greenTheme = createTheme("#2ecc71");
392
```
393

394
### Animation Sequences
395

396
```javascript
397
function createColorSequence(startColor, endColor, steps = 10) {
398
  const start = tinycolor(startColor);
399
  const end = tinycolor(endColor);
400
  
401
  const sequence = [];
402
  for (let i = 0; i <= steps; i++) {
403
    const progress = i / steps;
404
    const mixed = tinycolor.mix(start, end, progress * 100);
405
    sequence.push(mixed.toHexString());
406
  }
407
  
408
  return sequence;
409
}
410

411
// Pulse effect
412
function createPulse(baseColor, intensity = 30, steps = 20) {
413
  const base = tinycolor(baseColor);
414
  const bright = base.clone().lighten(intensity);
415
  
416
  const sequence = [];
417
  for (let i = 0; i <= steps; i++) {
418
    const progress = Math.sin((i / steps) * Math.PI * 2);
419
    const amount = (progress + 1) / 2 * intensity;
420
    sequence.push(base.clone().lighten(amount).toHexString());
421
  }
422
  
423
  return sequence;
424
}
425
```