Query Basics Getting started with Query's core functionality search Guide

Query Basics

Core Functionality

Query provides a fluent, chaining API for letting you get values from and update the DOM.

API Reference For a full look at available APIs in query please see the query API docs

Query Elements

Query elements can either be retrieved from the DOM using selectors, passed through from other query collections, DOM fragments, Nodelists, or just generated on the fly from stringified html.

CSS Selectors

You can use any valid selector that would work in document.querySelector

// basic
const $buttons = $('ui-button');


// standard
const $primaryButtons = $('ui-button.primary');
const $requiredInputs = $('input[required]');


// complex
const $navLinks = $('nav.main-nav a:not(.disabled)');

Creating Elements

You can specify stringified html to generate new HTML nodes on the fly to insert or manipulate.

// simple
const $div = $('<div>');


// advanced
const $card = $(`
  <div class="card">
    <div class="body">
      <p>This feature helps you do amazing things.</p>
      <button class="primary">Learn More</button>
    </div>
  </div>
`);

Esoteria

You can use nodeList, DocumentFragment and other more advanced collections with Query

DOM Fragment
const fragment = document.createDocumentFragment();
fragment.appendChild(document.createElement('div'));
const $fragmentContent = $(fragment);
Nodelist
const nodeList = document.querySelectorAll('p');
const $paragraphs = $(nodeList);

Globals

Query can also work with globals in a memory efficient way

const $window = $(window); // we dont store a copy of window

Existing Query Collections

You can pass query collections back into $ to create new selectors.

const $div = $('div');
const $copy = $($div);

Traversing the DOM

Query provides standard methods for querying up and down the DOM to find related DOM elements to thee one that matches a query.

Moving Down

Find elements within the current selection:

// Find direct children
$('ul').children(); // All direct children
$('ul').children('li.active'); // Only active list items


// Find any descendants matching a selector
$('.container').find('button'); // All buttons inside containers

Moving Up

Navigate to parent elements:

// Get direct parent
$('button').parent();


// Find closest ancestor matching a selector
$('button').closest('.card'); // Nearest card ancestor

Moving Sideways

Find elements at the same level:

// Get adjacent siblings
$('.tab').next(); // Next sibling
$('.tab').prev(); // Previous sibling


// Get all siblings
$('.tab').siblings(); // All siblings
$('.tab').siblings('.active'); // Only active siblings

Manipulating Elements

Query provides intuitive methods for modifying elements:

Content Manipulation

Get or set content with simple methods:

// Text content
$('.greeting').text('Hello, world!');
const message = $('.message').text(); // Get text content


// HTML content
$('.content').html('<span>New content with <em>emphasis</em></span>');
const htmlContent = $('.content').html(); // Get HTML content

Class Manipulation

Work with CSS classes effortlessly:

// Add classes
$('.item').addClass('active highlighted');


// Remove classes
$('.item').removeClass('loading disabled');


// Toggle classes
$('.panel').toggleClass('expanded');


// Check for class
if ($('.user').hasClass('admin')) {
  // Special handling for admin users
}

Attributes and Properties

Manage element attributes and properties:

// Get attribute value
const href = $('.link').attr('href');


// Set a single attribute
$('.image').attr('alt', 'Product thumbnail');


// Set multiple attributes
$('.video').attr({
  src: 'video.mp4',
  controls: true,
  autoplay: false,
  muted: true
});


// Remove attributes
$('.draft').removeAttr('data-published-date');

Working with Events

Query makes event handling straightforward:

Adding Event Listeners

Respond to user interactions:

// Basic click handling
$('.button').on('click', function() {
  console.log('Button clicked!');
});


// Multiple events with the same handler
$('.input').on('focus blur', function(event) {
  console.log('Input', event.type);
});


// Event with data
$('.item').on('click', { id: 123 }, function(event) {
  console.log('Item clicked with ID:', event.data.id);
});

Event Delegation

Handle events for current and future elements:

// Handle clicks on any current or future list items
$('.list').on('click', 'li', function() {
  $(this).toggleClass('selected');
});

Removing Event Listeners

Clean up when you no longer need listeners:

// Remove specific handler
$('.button').off('click', specificHandler);


// Remove all click handlers
$('.button').off('click');


// Remove all handlers
$('.button').off();

Understanding $ vs $$

Query provides two main functions with different capabilities:

  • $() - Queries the standard DOM tree (like querySelectorAll)
  • $$() - Queries across Shadow DOM boundaries recursively

When to Use $

Use $ for most cases when you’re working with regular DOM elements:

// Regular DOM queries
$('button.primary').addClass('highlighted');
$('.sidebar').find('.widget').addClass('visible');

The $ function is fast and efficient, as it leverages native DOM APIs under the hood. When you don’t need to access shadow DOM content, this should be your go-to tool.

Performance Considerations

The standard $ function is highly optimized:

// Typically fractions of a millisecond
$('li.item');

When you need to work with shadow DOM, switch to $$, but be aware that it involves more processing:

// May take 1-5ms for complex DOM structures
$$('ui-component .item');

Next Steps

Now that you’ve mastered the basics of Query, explore these advanced topics:
Previous
Query
Next
Shadow DOM