jQuery selectors, extensions and native queries

$(':checkbox') finds the two checkboxes of a shop’s checkout form; document.querySelectorAll(':checkbox') on the same page throws a SyntaxError. jQuery’s documentation files 26 selectors under “jQuery Extensions”, and legacy code is full of them: each one works until the day the code moves to the browser’s own querySelectorAll().

Every example below is that checkout page, run in jsdom (a browser-like DOM for Node.js) under jQuery 4.0.0 and then 3.7.1, and its scripts log which selectors the DOM’s querySelectorAll() accepted and which ones jQuery matched. You will rewrite extensions as standard selectors or methods that find the same elements, avoid the traps in :text, :checked, :contains() and :even, escape ids such as price.total, and keep custom pseudo-selectors working on jQuery 4.

jQuery asks the browser first, and matches the rest itself

The checkout page has a form with two checkboxes, two lists of dishes and a line with the total. Its script, engine.js, puts a spy on the document’s querySelectorAll(): a wrapper that passes every call on to the real method and notes each selector the method accepted and each one it refused. Then it asks jQuery for five selectors and logs how many elements came back and which engine found them:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>Checkout</title>
  </head>
  <body>
    <h1>Checkout</h1>
    <form id="checkout">
      <input name="name" placeholder="Your name">
      <input type="text" name="city" placeholder="City">
      <label><input type="checkbox" name="gift" checked> Gift wrap</label>
      <label><input type="checkbox" name="express"> Express delivery</label>
      <select name="slot">
        <option>Morning</option>
        <option selected>Evening</option>
      </select>
      <textarea name="note"></textarea>
      <button type="submit">Place order</button>
      <input type="button" value="Clear">
    </form>
    <ul class="menu" id="meals">
      <li data-stock="0">Thali</li>
      <li data-stock="4">Biryani</li>
      <li data-stock="0">Dosa</li>
    </ul>
    <ul class="menu" id="snacks">
      <li data-stock="12">Samosa</li>
      <li data-stock="0">Vada pav</li>
    </ul>
    <p class="total">Total due: ₹420</p>
    <div id="price.total">420</div>
    <div id="order:42">Order 42</div>
    <div id="1st-visit">Welcome back</div>
    <script src="https://code.jquery.com/jquery-4.0.0.min.js" integrity="sha256-OaVG6prZf4v69dPg6PhVattBXkcOWQB62pdZ3ORyrao=" crossorigin="anonymous"></script>
    <script src="engine.js"></script>
  </body>
</html>

// engine.js: which selectors querySelectorAll() accepted, and which ones jQuery matched with its own engine.
// A spy wraps the document's querySelectorAll() and notes every selector it accepted and every one it refused.
const accepted = new Set();
const refused = new Set();
const native = Document.prototype.querySelectorAll;
Document.prototype.querySelectorAll = function (selector) {
  try {
    const found = native.call(this, selector);
    accepted.add(selector);
    return found;
  } catch (error) {
    refused.add(selector);
    throw error;
  }
};

for (const selector of ['input[type=checkbox]', ':checkbox', 'ul:has(li)', 'li:first', 'p:contains(Total)']) {
  const found = $(selector).length;
  const by = refused.has(selector) ? "jQuery's own engine" : accepted.has(selector) ? 'querySelectorAll()' : 'a lookup without querySelectorAll()';
  console.log(`${selector}: ${found} found by ${by}`);
}

try {
  document.querySelectorAll(':checkbox');
} catch (error) {
  console.log(`document.querySelectorAll(':checkbox') throws ${error.name}`);
}

// Prints what checkout/engine.js logged in jsdom, with jQuery 4.0.0 and then 3.7.1 (recorded.mjs).
import { show } from './show.mjs';

show('checkout/engine.html');

input[type=checkbox]: 2 found by querySelectorAll()
:checkbox: 2 found by jQuery's own engine
ul:has(li): 2 found by querySelectorAll()
li:first: 1 found by jQuery's own engine
p:contains(Total): 1 found by jQuery's own engine
document.querySelectorAll(':checkbox') throws SyntaxError
(jQuery 3.7.1 logged the same 6 lines)

Every one of the five selectors went to querySelectorAll() first. The DOM’s engine knows only the selectors of the CSS standard, so it answered input[type=checkbox] and ul:has(li), and threw for :checkbox, li:first and p:contains(Total). jQuery caught each error and matched the selector with its own engine: the code of the Sizzle project, which jQuery 3.7 moved into jQuery itself (3.7.0 release notes). Both versions logged the same lines. Step through one standard selector and one extension:

The two engines also explain jQuery’s own advice. Queries that use an extension “cannot take advantage of the performance boost” of querySelectorAll(), so the documentation suggests selecting with standard CSS first and narrowing the result with .filter() (jQuery Extensions). The document.querySelectorAll(':checkbox') line of the output is the other consequence: code that calls document.querySelectorAll() itself has no second engine to fall back on, and every extension in it becomes an exception.

Form and text extensions have standard rewrites, with traps

Most selector extensionsselector extension: A selector that jQuery understands but CSS does not, such as :checkbox, :first or :contains(). jQuery matches it with its own engine; the browser's querySelectorAll() throws a SyntaxError for it. in legacy code name kinds of form field: :checkbox, :text, :input, :button, :selected. Each has a standard equivalent, but a word-for-word swap is wrong for some of them. rewrites.js runs on the same page; it logs each extension, then its rewrite, and says whether both found the same elements:

// rewrites.js: each jQuery extension next to the standard selector that replaces it, and the elements each one finds.
// A short name for each element: a form field's name, a button's text, an option's text, else its tag.
function label(el) {
  if (el.name) return el.name;
  if (el.localName === 'input') return `"${el.value}"`;
  if (el.localName === 'button' || el.localName === 'option') return `"${el.textContent.trim()}"`;
  return el.localName;
}

function compare(extension, standard) {
  const ours = $(extension).toArray().map(label);
  const theirs = [...document.querySelectorAll(standard)].map(label);
  console.log(`${extension} -> ${ours.length}: ${ours.join(', ')}`);
  const same = ours.join() === theirs.join();
  console.log(`  ${standard} -> ${theirs.length}${same ? ', the same elements' : `: ${theirs.join(', ')}`}`);
}

compare(':checkbox', 'input[type=checkbox]');
compare(':text', 'input[type=text]');
compare(':text', 'input[type=text], input:not([type])');
compare(':input', 'input, select, textarea, button');
compare(':button', 'button, input[type=button]');
compare(':header', 'h1, h2, h3, h4, h5, h6');
compare(':selected', 'option:checked');

// :checked is standard CSS, and it matches a selected option as well as a ticked box.
console.log(`:checked -> ${$(':checked').toArray().map(label).join(', ')}`);

// :contains() has no CSS equivalent: it matches every element whose text holds the words, ancestors included.
console.log(`:contains(Total) -> ${$(':contains(Total)').toArray().map(label).join(', ')}`);
const paragraphs = [...document.querySelectorAll('p')].filter((p) => p.textContent.includes('Total'));
console.log(`  p elements whose text includes Total -> ${paragraphs.map(label).join(', ')}`);

// Prints what checkout/rewrites.js logged in jsdom, with jQuery 4.0.0 and then 3.7.1 (recorded.mjs).
import { show } from './show.mjs';

show('checkout/rewrites.html');

:checkbox -> 2: gift, express
  input[type=checkbox] -> 2, the same elements
:text -> 2: name, city
  input[type=text] -> 1: city
:text -> 2: name, city
  input[type=text], input:not([type]) -> 2, the same elements
:input -> 8: name, city, gift, express, slot, note, "Place order", "Clear"
  input, select, textarea, button -> 8, the same elements
:button -> 2: "Place order", "Clear"
  button, input[type=button] -> 2, the same elements
:header -> 1: h1
  h1, h2, h3, h4, h5, h6 -> 1, the same elements
:selected -> 1: "Evening"
  option:checked -> 1, the same elements
:checked -> gift, "Evening"
:contains(Total) -> html, body, p
  p elements whose text includes Total -> p
(jQuery 3.7.1 logged the same 17 lines)

Three traps hide among these rewrites. The name field has no type attribute, and :text has matched such inputs since jQuery 1.5.2, because their type is text by default (:text), so input[type=text] found one field where :text found two. :checked is not an extension at all: it is CSS, and it matches a selected option as well as a ticked box, which is why $(':checked') returned the gift-wrap box and the Evening option. To count ticked boxes, write input:checked.

:visible needs a word of its own. Since jQuery 3, an element is :visible when it has a layout box, even one of zero width and height, and elements with visibility: hidden or opacity: 0 count as visible because they still take up space (:visible). jQuery’s definition is one line of its source, !!(elem.offsetWidth || elem.offsetHeight || elem.getClientRects().length) (hiddenVisibleSelectors.js). The closest native test is el.checkVisibility(), which returns false for an element without a box, such as one with display: none (MDN). jsdom lays nothing out, so the page does not run :visible: there, every element would count as hidden. Try it in a real browser with the playground at the end of this lesson.

Positional selectors count across the whole set

:first, :last, :eq(), :even, :odd, :lt() and :gt() are positional selectorspositional selector: A jQuery selector extension that picks elements by their position in the whole matched set, counted from 0: :first, :last, :eq(), :even, :odd, :lt() and :gt(). They are deprecated since jQuery 3.4 in favour of methods such as .first() and .eq().: they pick elements by their position in everything the selector found, counted from 0 across the whole page. CSS’s :first-child and :nth-child() count from 1 inside each parent. The two kinds look alike in code and part ways as soon as a page has more than one list, as the checkout page has: three meals and two snacks. Step through the selectors on the five items:

The page’s script runs the same selectors, each next to its CSS look-alike or its method:

// positions.js: positional selectors count across every element the selector found; CSS counts inside each parent.
const texts = ($set) => $set.toArray().map((li) => li.textContent).join(', ') || 'nothing';
const show = (what, $set) => console.log(`${what} -> ${texts($set)}`);

show('li:first', $('li:first'));
show('li:first-child', $('li:first-child'));
show(".first() of $('li')", $('li').first());
show('li:last', $('li:last'));
show('li:last-child', $('li:last-child'));
show('li:even', $('li:even'));
show('li:nth-child(odd)', $('li:nth-child(odd)'));
show(".even() of $('li')", $('li').even());
show('li:eq(1)', $('li:eq(1)'));
show(".eq(1) of $('li')", $('li').eq(1));
show('li:gt(2)', $('li:gt(2)'));
show(".slice(3) of $('li')", $('li').slice(3));

// Prints what checkout/positions.js logged in jsdom, with jQuery 4.0.0 and then 3.7.1, and what jQuery Migrate 4.0.2
// added when the same page loaded it (recorded.mjs).
import { show, showAgainst } from './show.mjs';

show('checkout/positions.html');
console.log('With jQuery Migrate 4.0.2 on the page:');
showAgainst('checkout/positions-migrate.html', 'checkout/positions.html');

li:first -> Thali
li:first-child -> Thali, Samosa
.first() of $('li') -> Thali
li:last -> Vada pav
li:last-child -> Dosa, Vada pav
li:even -> Thali, Dosa, Vada pav
li:nth-child(odd) -> Thali, Dosa, Samosa
.even() of $('li') -> Thali, Dosa, Vada pav
li:eq(1) -> Biryani
.eq(1) of $('li') -> Biryani
li:gt(2) -> Samosa, Vada pav
.slice(3) of $('li') -> Samosa, Vada pav
(jQuery 3.7.1 logged the same 12 lines)
With jQuery Migrate 4.0.2 on the page:
JQMIGRATE: Migrate is installed with logging active, version 4.0.2
(and the same 12 lines as before)

li:even returned Thali, Dosa and Vada pav, the positions 0, 2 and 4 of the set, and no CSS selector gives that: :nth-child(odd) starts counting again in the snacks list and picks Samosa instead. The documentation itself warns that the count from 0 means, counter-intuitively, that :even selects the first, third and fifth element (:even).

jQuery 3.4 deprecated these selectors because “anything you can do with positional selectors, you can do with positional methods instead” (3.4.0 release notes):

On 4.0.0 the selectors still work, and jQuery Migrate 4.0.2 logged nothing about them, only its start-up line. Migrate will not find them for you; the code has to be searched, which is what this lesson’s exercise does.

An id with a dot or a colon must be escaped

Ids made by templates and form builders often hold characters that mean something in CSS: price.total, order:42, item[3]. Written into a selector, #price.total means an element whose id is price and whose class is total. escape.js selects the page’s two such ids, and one that begins with a digit, in three ways:

// escape.js: ids with characters that mean something in CSS, selected three ways.
const count = (what, n) => console.log(`${what} -> ${n} found`);

count("$('#price.total')", $('#price.total').length);
const price = $.escapeSelector('price.total');
console.log(`$.escapeSelector('price.total') -> ${price}`);
count(`$('#${price}')`, $(`#${price}`).length);
count(`document.querySelectorAll('#${price}')`, document.querySelectorAll(`#${price}`).length);
count("document.getElementById('price.total')", document.getElementById('price.total') ? 1 : 0);

const order = $.escapeSelector('order:42');
console.log(`$.escapeSelector('order:42') -> ${order}`);
count(`$('#${order}')`, $(`#${order}`).length);

// An id that starts with a digit is not a valid CSS identifier.
count("$('#1st-visit')", $('#1st-visit').length);
try {
  document.querySelectorAll('#1st-visit');
} catch (error) {
  console.log(`document.querySelectorAll('#1st-visit') throws ${error.name}`);
}
count("document.getElementById('1st-visit')", document.getElementById('1st-visit') ? 1 : 0);
console.log(`$.escapeSelector('1st-visit') -> ${$.escapeSelector('1st-visit')}`);

// Prints what checkout/escape.js logged in jsdom, with jQuery 4.0.0 and then 3.7.1 (recorded.mjs).
import { show } from './show.mjs';

show('checkout/escape.html');

$('#price.total') -> 0 found
$.escapeSelector('price.total') -> price\.total
$('#price\.total') -> 1 found
document.querySelectorAll('#price\.total') -> 1 found
document.getElementById('price.total') -> 1 found
$.escapeSelector('order:42') -> order\:42
$('#order\:42') -> 1 found
$('#1st-visit') -> 1 found
document.querySelectorAll('#1st-visit') throws SyntaxError
document.getElementById('1st-visit') -> 1 found
$.escapeSelector('1st-visit') -> \31 st-visit
(jQuery 3.7.1 logged the same 11 lines)

$('#price.total') found nothing. $.escapeSelector(), added in jQuery 3.0, puts a backslash before every character with a special meaning in CSS, and the escaped selector found the element both in jQuery and in querySelectorAll(). Browsers have the same function, CSS.escape(): jQuery’s documentation calls $.escapeSelector() “essentially a shim” for it, and MDN’s example turns .foo#bar into \.foo\#bar (CSS.escape()). jsdom has no CSS.escape(), so the page shows jQuery’s.

An id that begins with a digit is not a valid name in CSS, so document.querySelectorAll('#1st-visit') threw a SyntaxError. $('#1st-visit') found the element anyway, because a selector that is a lone id takes jQuery’s shortcut through getElementById(), the first branch of the figure in the first section: the code works with jQuery and breaks without it. Escaping writes the digit as its code point, \31 .

Custom pseudo-selectors need createPseudo() in jQuery 4

Plugins and older application code define selectors of their own, such as :soldout, by adding a function to jQuery’s selector engine. jQuery 4 keeps two of the ways legacy code does it and drops the third, without an error. The menu items of the checkout page carry their stock in a data-stock attribute, and pseudos.js defines a pseudo-classpseudo-class: The part of a selector that starts with a colon and tests a state or a position of an element, such as :checked or :first-child in CSS. jQuery adds pseudo-classes of its own and lets code define more on jQuery.expr.pseudos. each way:

// pseudos.js: custom pseudo-selectors, defined the three ways legacy code does it, and a standard rewrite.
const texts = (list) => [...list].map((li) => li.textContent).join(', ') || 'nothing';

// 1. A function on jQuery.expr.pseudos.
jQuery.expr.pseudos.soldout = (el) => el.dataset.stock === '0';
console.log(`li:soldout -> ${texts($('li:soldout'))}`);

// 2. The same, through the old name jQuery.expr[':'].
jQuery.expr[':'].instock = (el) => el.dataset.stock !== '0';
console.log(`li:instock -> ${texts($('li:instock'))}`);

// 3. An argument read from match[3], the way pseudos with an argument were once written.
jQuery.expr.pseudos.stock = function (el, i, match) {
  return el.dataset.stock === match[3];
};
console.log(`li:stock(4) -> ${texts($('li:stock(4)'))}`);

// The supported way to take an argument: createPseudo().
jQuery.expr.pseudos.stockof = jQuery.expr.createPseudo((count) => (el) => el.dataset.stock === count);
console.log(`li:stockof(4) -> ${texts($('li:stockof(4)'))}`);

// No extension needed: a standard attribute selector.
console.log(`li[data-stock="4"] -> ${texts(document.querySelectorAll('li[data-stock="4"]'))}`);

// Prints what checkout/pseudos.js logged in jsdom, with jQuery 4.0.0 and then 3.7.1, and what changed when the same
// page loaded jQuery Migrate 4.0.2 (recorded.mjs).
import { show, showAgainst } from './show.mjs';

show('checkout/pseudos.html');
console.log('With jQuery Migrate 4.0.2 on the page:');
showAgainst('checkout/pseudos-migrate.html', 'checkout/pseudos.html');

li:soldout -> Thali, Dosa, Vada pav
li:instock -> Biryani, Samosa
li:stock(4) -> nothing
li:stockof(4) -> Biryani
li[data-stock="4"] -> Biryani
(jQuery 3.7.1 logged other lines:)
  line 3: li:stock(4) -> Biryani
With jQuery Migrate 4.0.2 on the page:
JQMIGRATE: Migrate is installed with logging active, version 4.0.2
(info) JQMIGRATE: jQuery.expr[':'] is deprecated; use jQuery.expr.pseudos
(info) JQMIGRATE: Pseudos with multiple arguments are deprecated; use jQuery.expr.createPseudo()
li:stock(4) -> Biryani
(and the same 4 lines as before)

li:soldout and li:instock worked on both versions: a function on jQuery.expr.pseudos, or the same through its old name jQuery.expr[':'], which jQuery Migrate reports as deprecated (warnings.md). li:stock(4) is the silent break. Its function reads the argument from match[3], the way custom pseudo-selectors with an argument were once written; jQuery 4 dropped this “legacy custom pseudos” form (4.0 upgrade guide), so match[3] no longer holds the 4, the test is false for every item, and the selector found nothing on 4.0.0 where 3.7.1 found Biryani. Migrate 4.0.2 brought the old behaviour back and logged “Pseudos with multiple arguments are deprecated”.

The fix is jQuery.expr.createPseudo(), which receives the argument once and returns the test; li:stockof(4) found Biryani on both versions. Often no extension is needed at all: the standard li[data-stock="4"] found the same item, and it keeps working once jQuery is gone. These are the releases that shaped the selectors you will meet in old code:

Practise: find the extensions in a codebase

Migrate is silent about positional selectors, so an audit before a migration searches the selector strings themselves. Write the function that does it for one string; the sample tests run in your browser:

/**
 * The jQuery selector extensions a selector string uses, each once, in the order they first appear: ':checkbox',
 * ':first', ':contains' (without its argument), or '[!=]' for an attribute-not-equal selector.
 * @param {string} selector
 * @returns {string[]}
 */
export function findExtensions(selector) {
  return [];
}

import { test, assert } from 'mysmartcopilot:test';
import { findExtensions } from './extensions.mjs';

test('standard selectors use no extension', () => {
  assert.deepEqual(findExtensions('input[type=checkbox]:checked'), []);
  assert.deepEqual(findExtensions('ul > li:nth-child(2), li:first-child, li:last-of-type'), []);
  assert.deepEqual(findExtensions('ul:has(li.sale)'), []);
});

test('form and positional extensions are reported without their argument', () => {
  assert.deepEqual(findExtensions('#checkout :checkbox:checked, li:first'), [':checkbox', ':first']);
  assert.deepEqual(findExtensions('li:eq(2), tr:even'), [':eq', ':even']);
  assert.deepEqual(findExtensions('li:not(:first):visible'), [':first', ':visible']);
});

test('each extension is reported once, in the order it first appears', () => {
  assert.deepEqual(findExtensions(':text, form :text:visible, :input'), [':text', ':visible', ':input']);
});

test('text in quotes and in attribute selectors is not a selector', () => {
  assert.deepEqual(findExtensions('p:contains("Total: 420")'), [':contains']);
  assert.deepEqual(findExtensions('a[href$=":first"]'), []);
  assert.deepEqual(findExtensions("a[title='Help: :hidden']:last"), [':last']);
  assert.deepEqual(findExtensions('a[title="x!=y"]'), []);
});

test('an escaped character belongs to the name it is in', () => {
  assert.deepEqual(findExtensions('#step\\:first, #order\\:42 :checkbox'), [':checkbox']);
  assert.deepEqual(findExtensions('#price\\.total:visible'), [':visible']);
});

test('the attribute-not-equal selector is reported as [!=]', () => {
  assert.deepEqual(findExtensions('input[name!="token"]'), ['[!=]']);
  assert.deepEqual(findExtensions('li:odd, a[rel!="nofollow"], li:odd'), [':odd', '[!=]']);
});

Then practise every idea of the lesson: the questions begin where your answers are weakest, and each choice explains itself as soon as you pick it:

Interview questions

Warm-up (fresher to 2–5 years): why can a selector work in $() and throw in document.querySelectorAll()?

jQuery first hands a selector to the browser’s querySelectorAll(). When the browser refuses it, because it uses a jQuery extension such as :checkbox, :first or :contains(), jQuery catches the SyntaxError and matches the selector with its own engine, so the page never sees an error. document.querySelectorAll() has no such fallback and throws. A lone id is a second case: $('#1st-visit') goes through getElementById(), while querySelectorAll() refuses #1st-visit because a CSS name cannot begin with a digit. Before removing jQuery, rewrite the extensions as standard CSS or methods such as .first(), and escape or look up unusual ids.

The bank of this module holds two harder ones: clearing a whole codebase of extensions, and a custom selector that went quiet after an upgrade. Sketch your own answer first, then compare it with the first step:

Key takeaways

• jQuery tries every selector on querySelectorAll() first and matches extensions with its own engine, so code that calls the DOM directly throws a SyntaxError for each extension it still holds.
• Most form extensions have standard rewrites, but :text also matches inputs without a type, :checked also matches selected options, and :contains() also matches every ancestor of the words.
• Positional selectors such as :first, :even and :gt() count the whole set from 0 and are deprecated since 3.4; .first(), .even(), .eq() and .slice() do the same job, and Migrate does not report them.
• Escape ids that hold dots, colons or a leading digit with $.escapeSelector() or CSS.escape(), or look a lone id up with getElementById().
• A custom pseudo-selector that reads match[3] finds nothing in jQuery 4; write it with jQuery.expr.createPseudo(), or replace it with a standard attribute selector.