Event Api

Direct Binding

The event listener is bound to the element that triggers the event. This is done by using the method bindTo(), which accepts any element, document and window.

Example:

require(['TYPO3/CMS/Core/Event/RegularEvent'], function (RegularEvent) {
  new RegularEvent('click', function (e) {
    // Do something
  }).bindTo(document.querySelector('#my-element'));
});

Event Delegation

The event listener is called if the event was triggered to any matching element inside its bound element.

Example:

require(['TYPO3/CMS/Core/Event/RegularEvent'], function (RegularEvent) {
  new RegularEvent('click', function (e) {
    // Do something
  }).delegateTo(document, 'a[data-action="toggle"]');
});

The event listener is now called every time the element matching the selector a[data-action="toggle"] within document is clicked.

Release an event

Since each event is an object instance, it's sufficient to call release() to detach the event listener.

Example:

require(['TYPO3/CMS/Core/Event/RegularEvent'], function (RegularEvent) {
  const clickEvent = new RegularEvent('click', function (e) {
    // Do something
  }).delegateTo(document, 'a[data-action="toggle"]');

  // Do more stuff

  clickEvent.release();
});

RegularEvent

The RegularEvent attaches a simple event listener to an event and element and has no further tweaks. This is the common use-case for event handling.

Arguments:

• eventName (string) - the event to listen on
• callback (function) - the event listener

Example:

require(['TYPO3/CMS/Core/Event/RegularEvent'], function (RegularEvent) {
  new RegularEvent('click', function (e) {
    e.preventDefault();
    window.location.reload();
  }).bindTo(document.querySelector('#my-element'));
});

DebounceEvent

The DebounceEvent is most suitable if an event is triggered quite often but executing the event listener is called only after a certain wait time.

Arguments:

• eventName (string) - the event to listen on
• callback (function) - the event listener
• wait (number) - the amount of milliseconds to wait before the event listener is called
• immediate (boolean) - if true, the event listener is called right when the event started

Example:

require(['TYPO3/CMS/Core/Event/DebounceEvent'], function (DebounceEvent) {
  new DebounceEvent('mousewheel', function (e) {
    console.log('Triggered once after 250ms!');
  }, 250).bindTo(document);
});

ThrottleEvent

Arguments:

• eventName (string) - the event to listen on
• callback (function) - the event listener
• limit (number) - the amount of milliseconds to wait before the event listener is called

The ThrottleEvent is similar to the DebounceEvent. The important difference is that the event listener is called after the configured wait time during the overall event time.

If an event time is about 2000ms and the wait time is configured to be 100ms, the event listener gets called up to 20 times in total (2000 / 100).

Example:

require(['TYPO3/CMS/Core/Event/ThrottleEvent'], function (ThrottleEvent) {
  new ThrottleEvent('mousewheel', function (e) {
    console.log('Triggered every 100ms!');
  }, 100).bindTo(document);
});

RequestAnimationFrameEvent

The RequestAnimationFrameEvent binds its execution to the browser's RequestAnimationFrame API. It is suitable for event listeners that manipulate the DOM.

Arguments:

• eventName (string) - the event to listen on
• callback (function) - the event listener

Example:

require(['TYPO3/CMS/Core/Event/RequestAnimationFrameEvent'], function (RequestAnimationFrameEvent) {
  new RequestAnimationFrameEvent('mousewheel', function (e) {
    console.log('Triggered every 16ms (= 60 FPS)!');
  });
});