0
# Core DOM Manipulation
1

2
Core DOM operations including element selection, traversal, manipulation, and utility functions. This forms the foundation of all Zepto functionality and is always included in builds.
3

4
## Capabilities
5

6
### Main Constructor
7

8
The primary Zepto function for creating collections from selectors, DOM elements, or HTML.
9

10
```javascript { .api }
11
/**
12
 * Create a Zepto collection from CSS selector, DOM elements, or HTML
13
 * @param selector - CSS selector string, DOM element, HTML string, or array
14
 * @param context - Optional context element for selector queries
15
 * @returns Zepto collection
16
 */
17
function $(selector, context);
18
function Zepto(selector, context);
19
```
20

21
**Usage Examples:**
22

23
```javascript
24
// CSS selectors
25
$('#myId');
26
$('.myClass');
27
$('div.container p');
28

29
// DOM elements
30
$(document.body);
31
$(document.getElementById('myElement'));
32

33
// HTML creation
34
$('<div class="new-element">Content</div>');
35
$('<p>', {text: 'Hello', class: 'greeting'});
36

37
// Arrays of elements
38
$([element1, element2, element3]);
39

40
// With context
41
$('.item', '#container'); // Find .item within #container
42
```
43

44
### Utility Functions
45

46
Global utility functions available on the `$` object.
47

48
```javascript { .api }
49
/**
50
 * Extend objects with properties from source objects
51
 * @param target - Target object to extend
52
 * @param source - Source object(s) to copy properties from
53
 * @param deep - Whether to perform deep merge
54
 * @returns Extended target object
55
 */
56
$.extend(target, ...sources);
57
$.extend(deep, target, ...sources);
58

59
/**
60
 * Get the type of an object
61
 * @param obj - Object to check type of
62
 * @returns Type string ('string', 'number', 'array', 'object', etc.)
63
 */
64
$.type(obj);
65

66
/**
67
 * Check if value is a function
68
 * @param value - Value to test
69
 * @returns True if value is function
70
 */
71
$.isFunction(value);
72

73
/**
74
 * Check if value is an array
75
 * @param obj - Value to test
76
 * @returns True if value is array
77
 */
78
$.isArray(obj);
79

80
/**
81
 * Check if value is a plain object
82
 * @param obj - Value to test
83
 * @returns True if value is plain object
84
 */
85
$.isPlainObject(obj);
86

87
/**
88
 * Check if object is empty (has no enumerable properties)
89
 * @param obj - Object to test
90
 * @returns True if object is empty
91
 */
92
$.isEmptyObject(obj);
93

94
/**
95
 * Check if value is numeric
96
 * @param val - Value to test  
97
 * @returns True if value is numeric
98
 */
99
$.isNumeric(val);
100

101
/**
102
 * Check if value is a window object
103
 * @param obj - Value to test
104
 * @returns True if value is window
105
 */
106
$.isWindow(obj);
107

108
/**
109
 * Find index of element in array
110
 * @param elem - Element to find
111
 * @param array - Array to search
112
 * @param i - Optional starting index
113
 * @returns Index of element or -1 if not found
114
 */
115
$.inArray(elem, array, i);
116

117
/**
118
 * Convert dash-separated string to camelCase
119
 * @param str - String to convert
120
 * @returns CamelCase string
121
 */
122
$.camelCase(str);
123

124
/**
125
 * Remove whitespace from beginning and end of string
126
 * @param str - String to trim
127
 * @returns Trimmed string
128
 */
129
$.trim(str);
130

131
/**
132
 * Test if parent element contains child element
133
 * @param parent - Parent element
134
 * @param child - Child element
135
 * @returns True if parent contains child
136
 */
137
$.contains(parent, child);
138

139
/**
140
 * Parse JSON string into object
141
 * @param str - JSON string to parse
142
 * @returns Parsed object
143
 */
144
$.parseJSON(str);
145

146
/**
147
 * Empty function (does nothing)
148
 * @returns undefined
149
 */
150
$.noop();
151
```
152

153
### Collection Iteration
154

155
Methods for iterating and transforming collections.
156

157
```javascript { .api }
158
/**
159
 * Iterate over collection elements
160
 * @param callback - Function called for each element
161
 * @returns Original collection for chaining
162
 */
163
$.fn.each(callback);
164

165
/**
166
 * Transform collection elements into new array
167
 * @param callback - Function to transform each element
168
 * @returns New Zepto collection with transformed elements
169
 */
170
$.fn.map(callback);
171

172
/**
173
 * Iterate over elements or objects
174
 * @param elements - Collection or object to iterate
175
 * @param callback - Function called for each item
176
 * @returns Original elements
177
 */
178
$.each(elements, callback);
179

180
/**
181
 * Transform elements into new array
182
 * @param elements - Collection to transform
183
 * @param callback - Function to transform each element
184
 * @returns Flattened array of results
185
 */
186
$.map(elements, callback);
187

188
/**
189
 * Filter array elements
190
 * @param elements - Array to filter
191
 * @param callback - Predicate function
192
 * @returns Filtered array
193
 */
194
$.grep(elements, callback);
195
```
196

197
### DOM Traversal
198

199
Methods for navigating the DOM tree.
200

201
```javascript { .api }
202
/**
203
 * Find descendant elements matching selector
204
 * @param selector - CSS selector or element
205
 * @returns New collection with matching descendants
206
 */
207
$.fn.find(selector);
208

209
/**
210
 * Get parent elements, optionally filtered by selector
211
 * @param selector - Optional CSS selector to filter parents
212
 * @returns Collection of parent elements
213
 */
214
$.fn.parent(selector);
215

216
/**
217
 * Get all ancestor elements, optionally filtered by selector
218
 * @param selector - Optional CSS selector to filter ancestors
219
 * @returns Collection of ancestor elements
220
 */
221
$.fn.parents(selector);
222

223
/**
224
 * Find closest ancestor element matching selector
225
 * @param selector - CSS selector to match
226
 * @param context - Optional context to limit search
227
 * @returns Collection with closest matching ancestor
228
 */
229
$.fn.closest(selector, context);
230

231
/**
232
 * Get child elements, optionally filtered by selector
233
 * @param selector - Optional CSS selector to filter children
234
 * @returns Collection of child elements
235
 */
236
$.fn.children(selector);
237

238
/**
239
 * Get sibling elements, optionally filtered by selector
240
 * @param selector - Optional CSS selector to filter siblings
241
 * @returns Collection of sibling elements
242
 */
243
$.fn.siblings(selector);
244

245
/**
246
 * Get next sibling element, optionally filtered by selector
247
 * @param selector - Optional CSS selector to filter
248
 * @returns Collection with next sibling
249
 */
250
$.fn.next(selector);
251

252
/**
253
 * Get previous sibling element, optionally filtered by selector
254
 * @param selector - Optional CSS selector to filter
255
 * @returns Collection with previous sibling
256
 */
257
$.fn.prev(selector);
258

259
/**
260
 * Get contents including text nodes
261
 * @returns Collection of content nodes
262
 */
263
$.fn.contents();
264
```
265

266
### Collection Filtering
267

268
Methods for filtering and selecting specific elements from collections.
269

270
```javascript { .api }
271
/**
272
 * Filter collection by selector or function
273
 * @param selector - CSS selector or predicate function
274
 * @returns Filtered collection
275
 */
276
$.fn.filter(selector);
277

278
/**
279
 * Remove elements matching selector from collection
280
 * @param selector - CSS selector or predicate function
281
 * @returns Collection without matching elements
282
 */
283
$.fn.not(selector);
284

285
/**
286
 * Test if any element matches selector
287
 * @param selector - CSS selector to test
288
 * @returns True if any element matches
289
 */
290
$.fn.is(selector);
291

292
/**
293
 * Filter to elements containing descendants matching selector
294
 * @param selector - CSS selector or element
295
 * @returns Collection of elements with matching descendants
296
 */
297
$.fn.has(selector);
298

299
/**
300
 * Get element at specific index
301
 * @param index - Zero-based index (-1 for last element)
302
 * @returns Collection containing element at index
303
 */
304
$.fn.eq(index);
305

306
/**
307
 * Get first element in collection
308
 * @returns Collection containing first element
309
 */
310
$.fn.first();
311

312
/**
313
 * Get last element in collection
314
 * @returns Collection containing last element
315
 */
316
$.fn.last();
317

318
/**
319
 * Add elements to collection
320
 * @param selector - Selector, elements, or HTML to add
321
 * @param context - Optional context for selector
322
 * @returns Combined collection
323
 */
324
$.fn.add(selector, context);
325
```
326

327
### DOM Manipulation
328

329
Methods for modifying DOM structure and content.
330

331
```javascript { .api }
332
/**
333
 * Get or set HTML content of elements
334
 * @param html - HTML string to set (optional)
335
 * @returns HTML content (if getting) or collection (if setting)
336
 */
337
$.fn.html(html);
338

339
/**
340
 * Get or set text content of elements
341
 * @param text - Text string to set (optional)
342
 * @returns Text content (if getting) or collection (if setting)
343
 */
344
$.fn.text(text);
345

346
/**
347
 * Append content to end of elements
348
 * @param content - HTML, elements, or collection to append
349
 * @returns Original collection
350
 */
351
$.fn.append(content);
352

353
/**
354
 * Prepend content to beginning of elements
355
 * @param content - HTML, elements, or collection to prepend
356
 * @returns Original collection
357
 */
358
$.fn.prepend(content);
359

360
/**
361
 * Insert content after elements
362
 * @param content - HTML, elements, or collection to insert
363
 * @returns Original collection
364
 */
365
$.fn.after(content);
366

367
/**
368
 * Insert content before elements
369
 * @param content - HTML, elements, or collection to insert
370
 * @returns Original collection
371
 */
372
$.fn.before(content);
373

374
/**
375
 * Append elements to target
376
 * @param target - Target selector or collection
377
 * @returns Original collection
378
 */
379
$.fn.appendTo(target);
380

381
/**
382
 * Prepend elements to target
383
 * @param target - Target selector or collection
384
 * @returns Original collection
385
 */
386
$.fn.prependTo(target);
387

388
/**
389
 * Insert elements after target
390
 * @param target - Target selector or collection
391
 * @returns Original collection
392
 */
393
$.fn.insertAfter(target);
394

395
/**
396
 * Insert elements before target
397
 * @param target - Target selector or collection
398
 * @returns Original collection
399
 */
400
$.fn.insertBefore(target);
401
```
402

403
### Element Manipulation
404

405
Methods for cloning, removing, and wrapping elements.
406

407
```javascript { .api }
408
/**
409
 * Remove elements and their data from DOM
410
 * @returns Original collection
411
 */
412
$.fn.remove();
413

414
/**
415
 * Detach elements from DOM (keeping data)
416
 * @returns Original collection
417
 */
418
$.fn.detach();
419

420
/**
421
 * Empty elements (remove all child nodes)
422
 * @returns Original collection
423
 */
424
$.fn.empty();
425

426
/**
427
 * Clone elements
428
 * @returns Collection of cloned elements
429
 */
430
$.fn.clone();
431

432
/**
433
 * Replace elements with new content
434
 * @param newContent - Content to replace with
435
 * @returns Original collection
436
 */
437
$.fn.replaceWith(newContent);
438

439
/**
440
 * Wrap each element in structure
441
 * @param structure - HTML or element to wrap with
442
 * @returns Original collection
443
 */
444
$.fn.wrap(structure);
445

446
/**
447
 * Wrap all elements in single structure
448
 * @param structure - HTML or element to wrap with
449
 * @returns Original collection
450
 */
451
$.fn.wrapAll(structure);
452

453
/**
454
 * Wrap inner contents of elements
455
 * @param structure - HTML or element to wrap with
456
 * @returns Original collection
457
 */
458
$.fn.wrapInner(structure);
459

460
/**
461
 * Remove wrapper from elements
462
 * @returns Original collection
463
 */
464
$.fn.unwrap();
465
```
466

467
### Collection Utilities
468

469
Utility methods for working with collections.
470

471
```javascript { .api }
472
/**
473
 * Get raw DOM element(s) from collection
474
 * @param index - Optional index of specific element
475
 * @returns DOM element (if index provided) or array of elements
476
 */
477
$.fn.get(index);
478

479
/**
480
 * Convert collection to plain array
481
 * @returns Array of DOM elements
482
 */
483
$.fn.toArray();
484

485
/**
486
 * Get size of collection
487
 * @returns Number of elements in collection
488
 */
489
$.fn.size();
490

491
/**
492
 * Get index of element within its parent or within another collection
493
 * @param element - Optional element to find index of
494
 * @returns Zero-based index
495
 */
496
$.fn.index(element);
497

498
/**
499
 * Extract property values from all elements
500
 * @param property - Property name to extract
501
 * @returns Array of property values
502
 */
503
$.fn.pluck(property);
504

505
/**
506
 * Slice collection like an array
507
 * @param start - Start index
508
 * @param end - End index (optional)
509
 * @returns New collection with sliced elements
510
 */
511
$.fn.slice(start, end);
512

513
/**
514
 * Concatenate collections or arrays
515
 * @param arrays - Collections or arrays to concatenate
516
 * @returns New collection with concatenated elements
517
 */
518
$.fn.concat(...arrays);
519
```
520

521
### Attributes and Properties
522

523
Methods for managing element attributes and properties.
524

525
```javascript { .api }
526
/**
527
 * Get or set element attributes
528
 * @param name - Attribute name or object of name/value pairs
529
 * @param value - Attribute value (if setting single attribute)
530
 * @returns Attribute value (if getting) or collection (if setting)
531
 */
532
$.fn.attr(name, value);
533

534
/**
535
 * Remove attributes from elements
536
 * @param name - Space-separated attribute names to remove
537
 * @returns Original collection
538
 */
539
$.fn.removeAttr(name);
540

541
/**
542
 * Get or set element properties
543
 * @param name - Property name
544
 * @param value - Property value (if setting)
545
 * @returns Property value (if getting) or collection (if setting)
546
 */
547
$.fn.prop(name, value);
548

549
/**
550
 * Remove properties from elements
551
 * @param name - Property name to remove
552
 * @returns Original collection
553
 */
554
$.fn.removeProp(name);
555

556
/**
557
 * Get or set basic data attributes
558
 * @param name - Data attribute name (without 'data-' prefix)
559
 * @param value - Data value (if setting)
560
 * @returns Data value (if getting) or collection (if setting)
561
 */
562
$.fn.data(name, value);
563

564
/**
565
 * Get or set form element values
566
 * @param value - Value to set (if setting)
567
 * @returns Element value (if getting) or collection (if setting)
568
 */
569
$.fn.val(value);
570
```
571

572
### DOM Ready
573

574
DOM ready event handling.
575

576
```javascript { .api }
577
/**
578
 * Execute callback when DOM is ready
579
 * @param callback - Function to execute when DOM is ready
580
 * @returns Original collection
581
 */
582
$.fn.ready(callback);
583
```
584

585
**Usage Examples:**
586

587
```javascript
588
// DOM ready
589
$(document).ready(function() {
590
  console.log('DOM is ready');
591
});
592

593
// Shorthand
594
$(function() {
595
  console.log('DOM is ready');
596
});
597
```
598

599
### Utility Constants
600

601
```javascript { .api }
602
// Plugin compatibility
603
$.uuid; // Unique counter for plugins
604
$.support; // Feature detection object
605
$.expr; // Selector expression utilities
606
$.noop; // No-operation function
607

608
// Internal API
609
$.fn; // Collection prototype
610
$.zepto; // Internal utilities namespace
611
```