0
# Effects
1

2
jQuery UI effects provide enhanced animation capabilities beyond standard jQuery animations. The effects system includes 15+ built-in effects and enhanced versions of jQuery's core animation methods.
3

4
## Capabilities
5

6
### Enhanced Animation Methods
7

8
jQuery UI extends jQuery's core animation methods to accept effect names and options:
9

10
```javascript { .api }
11
/**
12
 * Hides element with specified effect
13
 * @param {string} effect - Effect name (e.g., 'blind', 'slide', 'fade')
14
 * @param {object|number} options - Effect options or duration
15
 * @param {number} duration - Duration in milliseconds
16
 * @param {Function} callback - Completion callback
17
 */
18
$(element).hide(effect, options, duration, callback);
19

20
/**
21
 * Shows element with specified effect
22
 * @param {string} effect - Effect name
23
 * @param {object|number} options - Effect options or duration
24
 * @param {number} duration - Duration in milliseconds
25
 * @param {Function} callback - Completion callback
26
 */
27
$(element).show(effect, options, duration, callback);
28

29
/**
30
 * Toggles element visibility with specified effect
31
 * @param {string} effect - Effect name
32
 * @param {object|number} options - Effect options or duration
33
 * @param {number} duration - Duration in milliseconds
34
 * @param {Function} callback - Completion callback
35
 */
36
$(element).toggle(effect, options, duration, callback);
37
```
38

39
### Class Animation Methods
40

41
Animated CSS class manipulation with effects:
42

43
```javascript { .api }
44
/**
45
 * Adds CSS class with animation
46
 * @param {string} className - Class name to add
47
 * @param {number} duration - Animation duration
48
 * @param {string} easing - Easing function name
49
 * @param {Function} callback - Completion callback
50
 */
51
$(element).addClass(className, duration, easing, callback);
52

53
/**
54
 * Removes CSS class with animation
55
 * @param {string} className - Class name to remove
56
 * @param {number} duration - Animation duration
57
 * @param {string} easing - Easing function name
58
 * @param {Function} callback - Completion callback
59
 */
60
$(element).removeClass(className, duration, easing, callback);
61

62
/**
63
 * Toggles CSS class with animation
64
 * @param {string} className - Class name to toggle
65
 * @param {number} duration - Animation duration
66
 * @param {string} easing - Easing function name
67
 * @param {Function} callback - Completion callback
68
 */
69
$(element).toggleClass(className, duration, easing, callback);
70

71
/**
72
 * Switches from one class to another with animation
73
 * @param {string} removeClassName - Class to remove
74
 * @param {string} addClassName - Class to add
75
 * @param {number} duration - Animation duration
76
 * @param {string} easing - Easing function name
77
 * @param {Function} callback - Completion callback
78
 */
79
$(element).switchClass(removeClassName, addClassName, duration, easing, callback);
80
```
81

82
## Individual Effects
83

84
### Blind
85

86
Blinds element up/down or left/right like a window blind:
87

88
```javascript { .api }
89
$(element).hide('blind', { direction: 'vertical' }, 1000);
90
$(element).show('blind', { direction: 'horizontal' }, 1000);
91
```
92

93
**Options:**
94
- `direction`: `'up'` | `'vertical'` | `'down'` | `'left'` | `'horizontal'` | `'right'` (default: `'up'`)
95

96
### Bounce
97

98
Bounces element multiple times with decreasing intensity:
99

100
```javascript { .api }
101
$(element).hide('bounce', { times: 5, distance: 200 }, 1000);
102
$(element).show('bounce', { times: 3 }, 1000);
103
```
104

105
**Options:**
106
- `distance`: Distance in pixels for bounce (default: 20)
107
- `times`: Number of bounces (default: 5)
108

109
### Clip
110

111
Clips element from specified edges inward:
112

113
```javascript { .api }
114
$(element).hide('clip', { direction: 'vertical' }, 1000);
115
$(element).show('clip', { direction: 'horizontal' }, 1000);
116
```
117

118
**Options:**
119
- `direction`: `'vertical'` | `'horizontal'` (default: `'vertical'`)
120

121
### Drop
122

123
Drops element in/out from specified direction:
124

125
```javascript { .api }
126
$(element).hide('drop', { direction: 'left' }, 1000);
127
$(element).show('drop', { direction: 'up' }, 1000);
128
```
129

130
**Options:**
131
- `direction`: `'up'` | `'down'` | `'left'` | `'right'` (default: `'left'`)
132

133
### Explode
134

135
Explodes element into configurable number of pieces:
136

137
```javascript { .api }
138
$(element).hide('explode', { pieces: 16 }, 1000);
139
$(element).show('explode', { pieces: 9 }, 1000);
140
```
141

142
**Options:**
143
- `pieces`: Number of pieces (default: 9)
144

145
### Fade
146

147
Fades element opacity to specified level:
148

149
```javascript { .api }
150
$(element).hide('fade', 1000);
151
$(element).show('fade', 1000);
152
$(element).toggle('fade', { to: 0.5 }, 1000);
153
```
154

155
**Options:**
156
- `to`: Target opacity (default: 0 for hide, 1 for show)
157

158
### Fold
159

160
Folds element by shrinking opposite borders:
161

162
```javascript { .api }
163
$(element).hide('fold', { size: 50, horizFirst: true }, 1000);
164
$(element).show('fold', { size: 20 }, 1000);
165
```
166

167
**Options:**
168
- `size`: Size in pixels or percentage (default: 15)
169
- `horizFirst`: Fold horizontal first (default: false)
170

171
### Highlight
172

173
Highlights element with background color change:
174

175
```javascript { .api }
176
$(element).show('highlight', { color: '#ffff99' }, 1000);
177
$(element).effect('highlight', { color: 'red' }, 1000);
178
```
179

180
**Options:**
181
- `color`: Highlight color (default: '#ffff99')
182

183
### Puff
184

185
Element grows while fading out (like smoke puff):
186

187
```javascript { .api }
188
$(element).hide('puff', { percent: 150 }, 1000);
189
$(element).show('puff', { percent: 120 }, 1000);
190
```
191

192
**Options:**
193
- `percent`: Scale percentage (default: 150)
194

195
### Pulsate
196

197
Pulsates element opacity in configurable intervals:
198

199
```javascript { .api }
200
$(element).show('pulsate', { times: 3 }, 1000);
201
$(element).effect('pulsate', { times: 5 }, 2000);
202
```
203

204
**Options:**
205
- `times`: Number of pulses (default: 5)
206

207
### Scale
208

209
Scales element to specified percentage:
210

211
```javascript { .api }
212
$(element).hide('scale', { percent: 0, origin: ['middle', 'center'] }, 1000);
213
$(element).show('scale', { percent: 100, direction: 'both' }, 1000);
214
```
215

216
**Options:**
217
- `percent`: Target scale percentage (default: 0 for hide, 100 for show)
218
- `direction`: `'both'` | `'vertical'` | `'horizontal'` (default: `'both'`)
219
- `origin`: Origin point for scaling (default: `['middle', 'center']`)
220

221
### Shake
222

223
Shakes element back and forth horizontally or vertically:
224

225
```javascript { .api }
226
$(element).effect('shake', { direction: 'horizontal', times: 3, distance: 20 }, 1000);
227
```
228

229
**Options:**
230
- `direction`: `'horizontal'` | `'vertical'` (default: `'horizontal'`)
231
- `times`: Number of shakes (default: 3)
232
- `distance`: Shake distance in pixels (default: 20)
233

234
### Size
235

236
Animates element to specified width/height dimensions:
237

238
```javascript { .api }
239
$(element).effect('size', { 
240
  to: { width: 200, height: 60 },
241
  origin: ['top', 'left']
242
}, 1000);
243
```
244

245
**Options:**
246
- `to`: Target dimensions `{ width: number, height: number }`
247
- `origin`: Origin point for resizing (default: `['top', 'left']`)
248

249
### Slide
250

251
Slides element in/out from specified direction:
252

253
```javascript { .api }
254
$(element).hide('slide', { direction: 'left' }, 1000);
255
$(element).show('slide', { direction: 'up' }, 1000);
256
```
257

258
**Options:**
259
- `direction`: `'up'` | `'down'` | `'left'` | `'right'` (default: `'left'`)
260

261
### Transfer
262

263
Transfers element outline to another element:
264

265
```javascript { .api }
266
$(element).effect('transfer', { 
267
  to: '#target-element',
268
  className: 'ui-effects-transfer'
269
}, 1000);
270
```
271

272
**Options:**
273
- `to`: Target element selector or jQuery object
274
- `className`: CSS class for transfer outline (default: `'ui-effects-transfer'`)
275

276
## Effect Utilities
277

278
### Direct Effect Method
279

280
Apply effects without show/hide state changes:
281

282
```javascript { .api }
283
/**
284
 * Applies effect without changing element visibility
285
 * @param {string} effect - Effect name
286
 * @param {object} options - Effect options
287
 * @param {number} duration - Duration in milliseconds
288
 * @param {Function} callback - Completion callback
289
 */
290
$(element).effect(effect, options, duration, callback);
291
```
292

293
### Effects Core API
294

295
Access to the effects system internals:
296

297
```javascript { .api }
298
/**
299
 * Global effects namespace
300
 */
301
$.effects;
302

303
/**
304
 * Effects version
305
 */
306
$.effects.version; // "1.13.3"
307

308
/**
309
 * Registry of all available effects
310
 */
311
$.effects.effect; // Object containing all effect definitions
312

313
/**
314
 * Define a new custom effect
315
 * @param {string} name - Effect name
316
 * @param {string} mode - Effect mode ('show', 'hide', 'toggle', 'effect')
317
 * @param {Function} effect - Effect implementation function
318
 */
319
$.effects.define(name, mode, effect);
320
```
321

322
### Effect Helpers
323

324
Utility functions for effect development:
325

326
```javascript { .api }
327
/**
328
 * Creates placeholder element for effects
329
 * @param {jQuery} element - Element to create placeholder for
330
 * @returns {jQuery} Placeholder element
331
 */
332
$.effects.createPlaceholder(element);
333

334
/**
335
 * Removes effect wrapper elements
336
 * @param {jQuery} element - Element to unwrap
337
 * @returns {jQuery} Unwrapped element
338
 */
339
$.effects.removeWrapper(element);
340

341
/**
342
 * Creates wrapper elements for effects
343
 * @param {jQuery} element - Element to wrap
344
 * @returns {jQuery} Wrapper element
345
 */
346
$.effects.createWrapper(element);
347

348
/**
349
 * Gets scaled dimensions for percentage-based effects
350
 * @param {jQuery} element - Element to measure
351
 * @param {number} percent - Scale percentage
352
 * @param {string} direction - Scale direction
353
 * @returns {object} Scaled dimensions
354
 */
355
$.effects.scaledDimensions(element, percent, direction);
356

357
/**
358
 * Gets baseline coordinates for scaling effects
359
 * @param {Array} origin - Origin point array
360
 * @param {object} original - Original element dimensions
361
 * @returns {object} Baseline coordinates
362
 */
363
$.effects.getBaseline(origin, original);
364
```
365

366
## Types
367

368
```javascript { .api }
369
// Common effect options interface
370
interface EffectOptions {
371
  direction?: 'up' | 'down' | 'left' | 'right' | 'horizontal' | 'vertical' | 'both';
372
  duration?: number | string;
373
  easing?: string;
374
  complete?: () => void;
375
}
376

377
// Effect-specific option extensions
378
interface BlindOptions extends EffectOptions {
379
  direction?: 'vertical' | 'horizontal';
380
}
381

382
interface BounceOptions extends EffectOptions {
383
  distance?: number;
384
  times?: number;
385
}
386

387
interface ClipOptions extends EffectOptions {
388
  direction?: 'vertical' | 'horizontal';
389
}
390

391
interface DropOptions extends EffectOptions {
392
  direction?: 'up' | 'down' | 'left' | 'right';
393
}
394

395
interface ExplodeOptions extends EffectOptions {
396
  pieces?: number;
397
}
398

399
interface FadeOptions extends EffectOptions {
400
  to?: number;
401
}
402

403
interface FoldOptions extends EffectOptions {
404
  size?: number | string;
405
  horizFirst?: boolean;
406
}
407

408
interface HighlightOptions extends EffectOptions {
409
  color?: string;
410
}
411

412
interface PuffOptions extends EffectOptions {
413
  percent?: number;
414
}
415

416
interface PulsateOptions extends EffectOptions {
417
  times?: number;
418
}
419

420
interface ScaleOptions extends EffectOptions {
421
  percent?: number;
422
  direction?: 'both' | 'vertical' | 'horizontal';
423
  origin?: [string, string];
424
}
425

426
interface ShakeOptions extends EffectOptions {
427
  direction?: 'horizontal' | 'vertical';
428
  times?: number;
429
  distance?: number;
430
}
431

432
interface SizeOptions extends EffectOptions {
433
  to?: { width?: number, height?: number };
434
  origin?: [string, string];
435
}
436

437
interface SlideOptions extends EffectOptions {
438
  direction?: 'up' | 'down' | 'left' | 'right';
439
}
440

441
interface TransferOptions extends EffectOptions {
442
  to?: string | jQuery;
443
  className?: string;
444
}
445

446
// Effect definition interface for custom effects
447
interface EffectDefinition {
448
  (options: EffectOptions, done: () => void): void;
449
}
450
```
451

452
## Usage Examples
453

454
**Basic effect usage:**
455
```javascript
456
// Simple fade effect
457
$('#element').hide('fade', 1000);
458

459
// Effect with options
460
$('#element').show('slide', { direction: 'up' }, 500);
461

462
// Multiple effects in sequence
463
$('#element')
464
  .hide('slide', { direction: 'left' }, 500)
465
  .delay(1000)
466
  .show('bounce', { times: 3 }, 800);
467
```
468

469
**Class animations:**
470
```javascript
471
// Animate class changes
472
$('#element').addClass('highlighted', 1000);
473
$('#element').removeClass('highlighted', 500);
474

475
// Switch classes smoothly
476
$('#element').switchClass('old-style', 'new-style', 1000);
477
```
478

479
**Effect without state change:**
480
```javascript
481
// Shake element without hiding/showing
482
$('#element').effect('shake', { times: 2 }, 400);
483

484
// Highlight element temporarily
485
$('#element').effect('highlight', { color: 'yellow' }, 1500);
486
```