Semantic UI
ctrl+k
Enter a search term above to see results...
On This Page
On
off
one
onNext
trigger
dispatchEvent
focus
blur
submit
ready
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)| Name | Type | Description |
|---|---|---|
| eventName | string | One or more space-separated event types and optional namespaces |
| handler | function | object | The event handler function, or additional options |
| options | object | An object containing additional options |
Event Delegation
$(target).on(eventName, selector, handler, options)| Name | Type | Description |
|---|---|---|
| eventName | string | One or more space-separated event types and optional namespaces |
| selector | string | A selector string to filter the descendants of the selected elements that trigger the event, or the event handler function |
| handler | function | The event handler function, or additional options |
| options | object | An object containing additional options |
Options
| Name | Type | Default | Description |
|---|---|---|---|
| returnHandler | boolean | false | If true, returns the event handler object instead of the Query object |
| abortController | AbortController | new AbortController() | Custom AbortController for the event listener |
| capture | boolean | false | Use capture phase for event listener |
| once | boolean | false | Remove listener after it executes once |
| passive | boolean | false | Indicates that the function will never call preventDefault() |
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:
| Property | Type | Description |
|---|---|---|
| el | Element | The DOM element the event is attached to |
| eventName | string | The name of the event |
| eventListener | function | The actual function attached as the event listener |
| abortController | AbortController | The AbortController for this event listener |
| delegated | boolean | Whether this is a delegated event listener |
| handler | function | The original handler function provided |
| abort | function | A function to abort (remove) this event listener |
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
thisset 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
onmethod automatically handles delegation targets across shadow boundaries like wbe components usingevent.composedandevent.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();Example
Event Delegation Example
Example of using event delegation with dynamic content:
// This event handler will work for buttons added later$('#container').on('click', 'button', function(event) { console.log('Button clicked!', this);});Example
Abort Controller Example
Example of using AbortController for event management:
const controller = new AbortController();
$('button').on('click', function() { console.log('Button clicked!');}, { abortController: controller });
// Later, to remove the event listener:controller.abort();Example
Callback Handler Example
Example of using the callback handler pattern:
const handler = $('button').on('click', function() { console.log('Button clicked!');}, { returnHandler: true });
// Later, to remove the event listener:handler.abort();Example
off
Removes event handlers that were attached with .on().
Syntax
$('selector').off(eventName, handler)Parameters
| Name | Type | Description |
|---|---|---|
| eventName | string | One or more space-separated event types |
| handler | function | The function to remove from the event handlers |
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);Example
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
| Name | Type | Description |
|---|---|---|
| eventName | string | One or more space-separated event types |
| handler | function | The function to execute when the event occurs |
Returns
Query object (for chaining).
Usage
$('button').one('click', function(event) { console.log('This will only fire once!');});Example
onNext
Returns a Promise that resolves when the next occurrence of the specified event fires. This provides a modern async/await alternative to callback-based event handling.
Syntax
Wait for Event
await $('selector').onNext(eventName)Wait for Event with Delegation
await $('selector').onNext(eventName, targetSelector)Wait for Event with Timeout
await $('selector').onNext(eventName, { timeout: 5000 })Parameters
| Name | Type | Description |
|---|---|---|
| eventName | string | One or more space-separated event types |
| targetSelector | string | Optional CSS selector for event delegation |
| options | object | Optional configuration object |
| options.timeout | number | Timeout in milliseconds (throws error if event doesn’t fire) |
Returns
Promise - Resolves with the event object when the event fires.
Usage
Basic Event Waiting
// Wait for a button clickawait $('.button').onNext('click');console.log('Button was clicked!');
// Wait for multiple possible events (first one wins)await $('.element').onNext('animationend, transitionend');Event Delegation
// Wait for click on dynamically added elementsawait $('#container').onNext('click', '.dynamic-button');With Timeout
try { await $('.modal').onNext('modal:closed', { timeout: 5000 }); console.log('Modal closed within 5 seconds');} catch (error) { console.log('Modal did not close within 5 seconds');}Async/Await Patterns
async function animateSequence() { $('.element').addClass('fade-in'); await $('.element').onNext('animationend');
$('.element').addClass('slide-up'); await $('.element').onNext('animationend');
console.log('Animation sequence complete!');}Notes
- The promise resolves with the native Event object
- Event listeners are automatically cleaned up after the event fires
- Supports the same event delegation as
one() - If timeout is specified and exceeded, the promise rejects with an error
- For comma-separated events, resolves when the first event fires
trigger
Executes all handlers attached to the matched elements for the given event type.
Syntax
$('selector').trigger(eventName)Parameters
| Name | Type | Description |
|---|---|---|
| eventName | string | The type of event to trigger |
Returns
Query object (for chaining).
Usage
$('button').trigger('click');Example
dispatchEvent
Creates and dispatches a custom event on the matched elements.
dispatchEventis integrated into component callbacks, see component events
Syntax
$('selector').dispatchEvent(eventName, eventData, eventSettings)Parameters
| Name | Type | Description |
|---|---|---|
| eventName | string | The name of the custom event to create |
| eventData | object | Custom data to pass with the event |
| eventSettings | object | Additional event settings |
Returns
Query object (for chaining).
Usage
Passing Custom Metadata
const eventData = { delta: getResizeDelta() // pass along resize delta with event}$('.container').dispatchEvent('resize', eventData);Example
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();Example
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();Example
## click
Triggers click event for all elements
### Syntax```javascript$('selector').click()Returns
Query object (for chaining).
Usage
// Trigger click on all buttons$('button').click();Example
submit
Triggers submit event for all elements
Syntax
$('selector').submit()Returns
Query object (for chaining).
Usage
// Submit all forms$('form').submit();Example
ready
Executes a function when the DOM is fully loaded.
Syntax
$(document).ready(handler)Parameters
| Name | Type | Description |
|---|---|---|
| handler | function | The function to execute when DOM is ready |
Returns
Query object (for chaining).
Usage
// Execute code when DOM is ready$(document).ready(function() { console.log('DOM is ready!'); // Initialize your application here});