Query

Introduction

Query is a lightweight (3kb) DOM manipulation library designed to seamlessly work with both standard DOM and Shadow DOM. It provides a familiar, chainable API inspired by jQuery, while addressing the unique challenges of modern web component architecture.

Query excels at traversing and manipulating elements across component boundaries, solving one of the most common pain points when working with web components.

API Reference: For comprehensive documentation of all functions, visit the API reference guide.

The Shadow DOM Challenge

Web components encapsulate their internal structure using Shadow DOM, creating clear boundaries that standard DOM APIs cannot cross. This encapsulation is powerful for building isolated components, but presents challenges when you need to:

• Select elements across multiple component boundaries
• Traverse from one component into another’s shadow DOM
• Access slotted content from parent components

With native DOM APIs, these operations stop at shadow boundaries. Query solves this by providing intuitive tools that work consistently across all DOM boundaries.

// Native APIs stop at shadow boundaries
document.querySelector('ui-dropdown .option'); // Returns null

// Query seamlessly crosses boundaries
$$('ui-dropdown .option'); // Returns all matching elements

Getting Started

Install Query via npm:

npm install @semantic-ui/query

Import and use the core functions:

import { $, $$ } from '@semantic-ui/query';

// Select and manipulate standard DOM elements
$('.content')
  .addClass('active')
  .css('color', 'blue')
  .on('click', function() {
    $(this).removeClass('active');
  });

// Work with elements inside shadow DOM
$$('ui-dropdown .option')
  .filter(':not(.disabled)')
  .on('click', function() {
    console.log('Option selected:', $(this).text());
  });

Core Concepts

Query provides two powerful functions tailored to different use cases:

• $ - Efficiently queries the standard DOM tree using native DOM APIs
• $$ - Seamlessly queries across shadow DOM boundaries

This dual approach gives you optimal performance for your specific needs. Use $ for standard DOM operations (faster), and $$ when you need to work across shadow DOM boundaries.

// Fast standard DOM query
$('.card').addClass('highlighted');

// Cross-boundary shadow DOM query
$$('ui-card .title').text('Updated Title');

Query embraces method chaining, allowing you to perform multiple operations in a fluent, readable sequence:

$('.user-profile')
  .find('.avatar')
    .attr('src', '/images/new-avatar.png')
    .addClass('updated')
  .end()
  .find('.username')
    .text('Updated Username');

Integration with Components

Query is deeply integrated into the Semantic UI component system. Both $ and $$ are automatically available in all component lifecycle methods and event handlers:

const createComponent = ({ $, $$ }) => ({
  initialize() {
    // Handle elements within this component
    $('.tooltip').hide();

    // Access elements across component boundaries
    $$('.global-notification').addClass('visible');
  },

  events: {
    'click .button'({ $, target }) {
      // Easily reference the clicked element
      $(target).addClass('clicked');
    }
  }
});

Explore the Components integration guide to learn more about using Query within Semantic UI components.