Query - DOM Traversal API reference for Query methods related to DOM traversal navigation API Reference
Categories

Query - DOM Traversal

The DOM Traversal methods allow you to get from one element to another based off their relationship. Query supports piercing shadow DOM boundaries when using $$

find

Finds descendant elements that match the specified selector.

Syntax

$('selector').find(childSelector)

Parameters

NameTypeDescription
childSelectorstringA selector to match descendant elements

Returns

Query object containing the matched elements.

Usage

Standard

// Find all paragraphs within a div
$('div').find('p').addClass('highlight');

Shadow DOM

$$('my-component').find('p').addClass('highlight');

Example

parent

Gets the parent of each element in the current set of matched elements.

Syntax

$('selector').parent(parentSelector)

Parameters

NameTypeDescription
parentSelectorstring(Optional) A selector to filter parent elements

Returns

Query object containing the parent elements.

Usage

Standard

// Get the parent of a button
$('button').parent().addClass('button-group');

Shadow DOM

$$('my-component menu-item').parent().addClass('menu-styling');

Example

children

Gets the children of each element in the set of matched elements.

Syntax

$('selector').children(childSelector)

Parameters

NameTypeDescription
childSelectorstring(Optional) A selector to filter children elements

Returns

Query object containing the child elements.

Usage

// Get all direct child list items of an unordered list
$('ul').children('li').css('color', 'red');

Example

siblings

Gets the siblings of each element in the set of matched elements.

Syntax

$('selector').siblings(siblingSelector)

Parameters

NameTypeDescription
siblingSelectorstring(Optional) A selector to filter sibling elements

Returns

Query object containing the sibling elements.

Usage

Standard

// Get all siblings of a selected element
$('.selected').siblings().addClass('dimmed');

Shadow DOM

$$('my-component').find('.shadow-selected').siblings().addClass('shadow-dimmed');

Example

closest

Finds the closest ancestor element that matches the selector, or optionally all matching ancestors.

Syntax

Get Closest Ancestor

$('selector').closest(ancestorSelector)

Get All Matching Ancestors

$('selector').closest(ancestorSelector, { returnAll: true })

Parameters

NameTypeDescription
ancestorSelectorstringA selector to match ancestor elements
optionsobject(Optional) Options to control behavior
options.returnAllbooleanIf true, returns all matching ancestors instead of just the closest

Returns

Query object containing the closest matching ancestor, or all matching ancestors if returnAll: true.

Usage

Standard - Closest Ancestor

// Find the closest form ancestor
$('input').closest('form').submit();

Get All Matching Ancestors

// Find all div ancestors
$('span').closest('div', { returnAll: true }).addClass('ancestor');

Shadow DOM

$$('my-component').find('input').closest('.shadow-form').addClass('validated');

Example

closestAll

Gets all ancestor elements that match the selector, traversing up the entire DOM tree. This is a convenient alias for closest(selector, { returnAll: true }).

Syntax

$('selector').closestAll(ancestorSelector)

Parameters

NameTypeDescription
ancestorSelectorstringA selector to match ancestor elements

Returns

Query object containing all matching ancestor elements.

Usage

Basic Usage

// Find all container ancestors
$('span').closestAll('.container').addClass('highlight');

Working with Multiple Elements

// Find all form ancestors for all inputs
$('input').closestAll('form').addClass('has-inputs');

Shadow DOM Aware

// Find all shadow DOM containers
$$('input').closestAll('.shadow-container').addClass('shadow-highlight');

Notes

  • Returns elements in DOM order (closest to farthest)
  • Automatically removes duplicates when multiple elements share the same ancestor
  • Respects the pierceShadow option for shadow DOM traversal

next

Gets the immediately following sibling of each element in the set of matched elements.

Syntax

$('selector').next(nextSelector)

Parameters

NameTypeDescription
nextSelectorstring(Optional) A selector to filter the next element

Returns

Query object containing the next sibling elements.

Usage

Standard

// Get the next sibling of a paragraph
$('p').next().css('margin-top', '20px');

Shadow DOM

$$('my-component').find('.shadow-paragraph').next().css('margin-top', '10px');

Example

prev

Gets the immediately preceding sibling of each element in the set of matched elements.

Syntax

$('selector').prev(prevSelector)

Parameters

NameTypeDescription
prevSelectorstring(Optional) A selector to filter the previous element

Returns

Query object containing the previous sibling elements.

Usage

Standard

// Get the previous sibling of a heading
$('h2').prev().css('color', 'red');

Shadow DOM

$$('my-component').find('.shadow-heading').prev().css('margin-bottom', '5px');

Example

end

Returns to the previous set of elements in the traversal chain.

Syntax

$('selector').find('childSelector').end()

Parameters

None

Returns

Query object that was active before the last traversal method was used.

Usage

// Allows working with different levels in the DOM without making multiple selections
$('.card')
.addClass('highlighted') // Add class to cards
.find('.title') // Switch to titles within cards
.css('font-weight', 'bold') // Bold the titles
.end() // Go back to the card selection
.find('.content') // Now find content within cards
.html('<p>New content</p>'); // Change the HTML

Example

filter

Reduce the set of matched elements to those that match the selector or pass the function’s test.

Syntax

$('selector').filter(filterSelector)
$('selector').filter(function)

Parameters

NameTypeDescription
filterSelectorstringA selector to filter elements
functionfunctionA function to test each element against

Returns

Query object containing the filtered elements.

Usage

Using Selector

// Filter paragraphs to only those with class 'highlight'
$('p').filter('.highlight').css('background', 'yellow');

Using Function

// Filter list items to only those with text containing 'important'
$('li').filter(function() {
return $(this).text().includes('important');
}).addClass('priority');

Example

not

Remove elements from the set of matched elements that match the selector or pass the function’s test.

Syntax

$('selector').not(notSelector)
$('selector').not(function)

Parameters

NameTypeDescription
notSelectorstringA selector to exclude elements
functionfunctionA function to test each element against

Returns

Query object containing the remaining elements.

Usage

Using Selector

// Select all paragraphs except those with class 'exclude'
$('p').not('.exclude').css('color', 'blue');

Using Function

// Select all list items except empty ones
$('li').not(function() {
return $(this).text().trim() === '';
}).addClass('visible');

Example

is

Check if any of the matched elements match the given selector.

Syntax

$('selector').is(testSelector)
$('selector').is(function)

Parameters

NameTypeDescription
testSelectorstringA selector to test elements against
functionfunctionA function to test each element against

Returns

true if at least one element matches, false otherwise.

Usage

Using Selector

// Check if any paragraph has class 'active'
if ($('p').is('.active')) {
console.log('At least one paragraph is active');
}

Using Function

// Check if any input is empty
if ($('input').is(function() {
return $(this).val() === '';
})) {
console.log('At least one input is empty');
}

Example

index

Return the position of the first element within the jQuery object relative to its sibling elements.

Syntax

$('selector').index()
$('selector').index(element)

Parameters

NameTypeDescription
elementstring/element/jQuery(Optional) Element to find index of

Returns

The index position of the element(s).

Usage

Get Index of First Element

// Get the index of the first selected element
const index = $('li.selected').index();
console.log(`Selected item is at index: ${index}`);

Get Index of Specific Element

// Get the index of a specific element within the selection
const specificIndex = $('li').index($('li.highlight'));
console.log(`Highlighted item is at index: ${specificIndex}`);

Example

contains

Check if the first element contains the given element.

Syntax

$('selector').contains(element)

Parameters

NameTypeDescription
elementDOM elementThe element to check for containment

Returns

true if the element is contained, false otherwise.

Usage

Basic Containment Check

// Check if a div contains a specific paragraph
const $div = $('#container');
const $paragraph = $('#content-para');
if ($div.contains($paragraph[0])) {
console.log('Container holds the paragraph');
}

Dynamic Containment Check

// Check if any card contains clicked element
$('.card').each(function() {
if ($(this).contains(event.target)) {
console.log('Click happened inside this card');
}
});

Example

Previous
DOM Manipulation
Next
Events