Query - Events

The Event methods in Query provide tools for attaching event listeners, triggering custom events, removing them, and triggering events.

On

on provides various methods to attach event listeners to DOM elements. It supports standard event binding, event delegation, and special handling for shadow DOM.

Syntax

Normal Event Binding

$(target).on(eventName, handler, options)

Event Delegation

$(target).on(eventName, selector, handler, options)

Options

Returns

Standard

Query object (for chaining).

Return Handler

When returnHandler in options is set to true, the on method returns an event handler object (or an array of objects for multiple elements) with the following properties:

Usage

Standard Event Binding

Attach a click event to all div elements:

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

$('div').on('click', function(event) {
  console.log('Div clicked!', this);
});

Event Delegation

Attach a click event to all current and future buttons within a container

When using event delegation, the handler is called with this set to the target element that matched the selector, not the element the listener was attached to.

Event Delegation Event delegation allow you to add or remove elements from the DOM and still have them trigger the event so long as the parent element remains in the page.

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

$('#container').on('click', 'button', function(event) {
  console.log('Button clicked!', this);
});

Event Delegation with Shadow DOM

When working with Shadow DOM, use the $$ function to pierce shadow boundaries:

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

$$('my-custom-element').on('click', 'button', function(event) {
  console.log('Shadow DOM button clicked!', this);
});

Composed Events: The on method automatically handles delegation targets across shadow boundaries like wbe components using event.composed and event.composedPath() for events that cross shadow DOM boundaries. This allows the delegation to work correctly even when the target element is within a shadow root.

Using Event Options

You can pass additional options to the underlying addEventListener method:

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

$('div').on('click', {
  capture: true,
  once: true
}, function(event) {
  console.log('This will only fire once, and in the capture phase');
});

Using Returned Handler with Abort Signal

You can get a reference to the event handler, which includes an abort method:

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

const handler = $('button').on('click', function() {
  console.log('Button clicked!');
}, { returnHandler: true });

// Later, to remove the event listener:
handler.abort();

Listening to a Custom Event

Here’s an example of dispatching a custom event from one element and listening to it on another:

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

// listen to a custom event
$('my-component').on('customEvent', function(event) {
  console.log('Custom event fired!', event.detail);
});

// Dispatch the custom event
$('my-component').dispatchEvent('customEvent', { detail: 'Hello from custom event!' });

Using Custom Abort Controller

You can provide your own AbortController for more fine-grained control:

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

const controller = new AbortController();

$('button').on('click', function() {
  console.log('Button clicked!');
}, { abortController: controller });

// Later, to remove the event listener:
controller.abort();

off

Removes event handlers that were attached with .on().

Syntax

$('selector').off(eventName, handler)

Parameters

Returns

Query object (for chaining).

Usage

function clickHandler(event) {
  console.log('Clicked!');
}

$('button').on('click', clickHandler);
// Later, to remove the event listener
$('button').off('click', clickHandler);

one

Attaches a handler to an event for the elements. The handler is executed at most once per element per event type.

Syntax

$('selector').one(eventName, handler)

Parameters

Returns

Query object (for chaining).

Usage

$('button').one('click', function(event) {
    console.log('This will only fire once!');
});

trigger

Executes all handlers attached to the matched elements for the given event type.

Syntax

$('selector').trigger(eventName)

Parameters

Returns

Query object (for chaining).

Usage

$('button').trigger('click');

dispatchEvent

Creates and dispatches a custom event on the matched elements.

dispatchEvent is integrated into component callbacks, see component events

Syntax

$('selector').dispatchEvent(eventName, eventData, eventSettings)

Parameters

Returns

Query object (for chaining).

Usage

Passing Custom Metadata

const eventData = {
  delta: getResizeDelta() // pass along resize delta with event
}
$('.container').dispatchEvent('resize', eventData);

focus

Gives focus to the first element in the set of matched elements.

Syntax

$('selector').focus()

Returns

Query object (for chaining).

Usage

// Focus on an input element
$('input.username').focus();

blur

Removes focus from the first element in the set of matched elements.

Syntax

$('selector').blur()

Returns

Query object (for chaining).

Usage

// Remove focus from whatever is focused
$(document.activeElement).blur();