DOM Elements API

$()

Selects matched DOM elements based on a passed selector.

Accepts a selector argument as a string.
The search for elements starts from the document root, but it can also be initiated based on a matched element.
Supports all standard CSS selectors and includes additional built-in selectors such as:

Selector

Description

@

Is supported only inside "data-*" attributes and can only be placed at the beginning of a selector.
It indicates that the element search starts from the current element.
If just "@" is specified, it will return the current element itself.

..

Finds the immediate parent element in the DOM.
If a selector is specified as "..{*}" (where "*" can be any valid CSS selector), it traverses the element and its ancestors (moving toward the document root) until it finds an element that matches the specified CSS selector.

<<

Finds the element that is immediately before the current element on the same level in the DOM hierarchy.
If a selector is specified as "<<{*}" (where "*" can be any valid CSS selector), it traverses the elements at the same level above the current element until it finds one that matches the specified CSS selector, or an element that has a descendant matching that CSS selector.

>>

Finds the element that is immediately after the current element on the same level in the DOM hierarchy.
If a selector is specified as ">>{*}" (where "*" can be any valid CSS selector), it traverses the elements at the same level below the current element until it finds one that matches the specified CSS selector, or an element that has a descendant matching that CSS selector.

::

Finds all child elements that match the current element.
If a selector is specified as "::{*}" (where "*" can be any valid CSS selector), it finds child elements that match the specified CSS selector or elements that have descendants matching that CSS selector.
If the selector is followed by additional selectors, it finds the first matching child element.

~~

Finds all elements at the current level in the DOM hierarchy, including the current element.
If a selector is specified as "~~{*}" (where "*" can be any valid CSS selector), it finds elements at the current level in the DOM hierarchy that match the specified CSS selector or elements that have descendants matching that CSS selector.
If the selector is followed by additional selectors, it finds the first matching element at the current level in the DOM hierarchy.

{{ }}

Finds all elements that contain the specified HTML contents, ignoring case.
If a selector is specified before searching by HTML contents, it finds exactly those elements that match the selector and have the specified HTML contents.
If a selector is not specified before searching by HTML contents, it finds all elements that contain the specified content starting from the document root.

?

Finds all elements.
If a selector is specified before, it finds only elements that match that selector.
After "?", you can specify exactly which elements need to be selected by their indexes, if necessary, using the following rules:

Rule

Example

List the indexes separated by commas to select specific elements.

? 1, 3, 5

Use negative values to select elements starting from the end of the list.

? -1, -3, -5

Append "%" to select all elements before or after the specified index.
You can also specify it between indexes to select a range of elements.

? 1%, %-3, 5-%, 5%10

Specify indexes in square brackets "[ ]" to exclude elements from the selection.
You can use both positive and negative indexes, and append "%" to exclude all elements before or after the specified index.

? [4, 9%15, -1], [7, %3%]
If the selector does not use "?" or specifies a selection of only one element, such as "? 3", it returns the first DOM element found that matches the specified selector, or null if no match is found.
If the selector uses "?" and does not specify indexes to select, or specifies multiple indexes, such as "? 3, 4", it returns an array with all found DOM elements matching the specified selector, or an empty array if no matches are found.

Example:

$(true);
// Returns the current document.
// document

$();
$('');
$('div.classDoesNotExist');
// No matches found for the selector.
// null

$('*');
// Returns the first element found.
// <html>

$('div');
// Returns the first <div> element found.
// <div>

$('div').$('span');
// Returns the first <span> element found that is within the matched <div>.
// <span>

$('div span ?');
// Returns all <span> elements found that are contained within any <div> element.
// [<span>, <span>, <span>, <span>,...]

$('div').$('span ?');
// Returns all found <span> elements that are in the matched <div>.
// [<span>, <span>]

$('?');
// Returns all existing elements in the current document.
// [<html>, <head>, <meta>, <title>,...]

$('? 0');
// Returns the first existing element in the current document.
// <html>

$('div, span ? 1');
// Returns the second element found, which will be a <div> or <span>.
// <div>

$('div ? 0, 1');
// Returns the first and second <div> elements found.
// [<div>, <div>]

$('div ?');
// Returns all found <div> elements.
// [<div>, <div>, <div>, <div>,...]

$('div *');
// Returns the first child of the first <div> element found.
// <span>

$('div * ?');
// Returns all descendants of any nesting level for all <div> elements.
// [<span>, <div>, <div>, <div>,...]

$('div > * ?');
// Returns all immediate descendants of all <div> elements.
// [<span>, <span>, <span>, <span>,...]

$('div.book:has(.cat) span ?');
/*
   Select the <div> with the class 'book' that has an element with the class 'cat' inside it, 
   and then return all the <span> elements inside those <div> elements. 
*/
// [<span>, <span>, <span>, <span>,...]

$('div').$('..');
// Returns the parent of the matched <div>.
// <main>

$('div').$('..{body}');
// Returns the parent element of the matched <div> that also matches the specified selector.
// <body>

$('div ..{body} main');
/*
   Selects a <div>, then finds its parent that matches the specified selector, 
   and returns the <main> element inside that parent.
*/
// <main>

$('div ? 1').$('<<');
// Returns the element that is immediately before the matched element on the same level in the DOM hierarchy.
// <div>

$('div >>{ul}');
/*
   Returns the element that follows the <div> element at the same level in the DOM hierarchy, 
   matching the specified selector, even if separated by other elements.
*/
// <ul>

$('div').$(':: ?');
// Returns all child elements of the matched element.
// [<span>, <span>]

$('main ::{div, ul} ?');
// Returns all child elements of the <main> element that match the specified selector.
// [<div>, <div>, <ul>]

$('div').$('~~ ?');
// Returns all elements that are at the same DOM hierarchy level as the matched element.
// [<div>, <div>, <div>, <ul>]

$('div ~~{ul} ?');
// Returns all elements that are at the same DOM hierarchy level as <div> element and match the specified selector.
// [<ul>]

$('div{{book}} ?');
// Returns all <div> elements that contain the content 'book'.
// [<div>, <div>]

$('div{{<span>book</span>}}');
// Returns the <div> element that contains the <span> element with the text content 'book'.
// <div>

// Selectors can be combined freely according to your preferences.
$('#book').$('span.cat ..{div.book} >> :: [name="cat"] ..{form} > input ? 0%5, [2, 3]');
/*
   Select the <span> element with the class 'cat' in the matched element.
   Select the parent <div> with the class 'book'.
   Select the next element at the same level.
   Select the first child element.
   Select the element with the attribute 'name="cat"'.
   Select the parent <form> element.
   Return all <input> elements directly inside the <form> with indexes 0, 1, 4, and 5.
*/

Example of selecting elements via "data-*" attributes in HTML markup and passing them to a specified component:

<!-- Pass the first <div> element found. -->
<button data-click="component_1: $('div')"></button>

<!-- Pass all the <div> elements found. -->
<button data-click="component_1: $('div ?')"></button>

<!-- Pass the parent element <div>. -->
<button data-click="component_1: $('.. div')"></button>

<!-- Pass the first <span> element found inside the current element. -->
<button data-click="component_1: $('@ span')">
   <span></span>
</button>

<!-- Pass an array of elements. -->
<button data-click="
   component_1: [
      $('div ? 0'), 
      $('div ? 2')
   ]
"></button>

<!-- Pass an object of elements. -->
<button data-click="
   component_1: {
      book: $('<<'),
      cat: $('@ span')
   }
"></button>

Previous Overview Next $.create()