Events

How SDK events are named, how to listen and stop listening, and how to send your own.

Read this when part of your theme must react to something the customer did elsewhere on the page.

Every SDK method announces its result as an event: a named message any code on the page can listen to. The cart badge updates on cart::updated, a toast opens on cart::item.added, and an app can track wishlist::added. Salla SDK and events shows the React patterns. This page is the reference.

Event names

A name is the module, two colons, then the event: cart::item.added, auth::logged.in, product::price.updated. A failure has its own event, usually ending in .failed, such as cart::item.added.failed. Each module page in this tab lists its events.

Listen and stop listening

There are two ways to subscribe. Use one way for both on and off.

WaySubscribeUnsubscribe
By nameSalla.event.on('cart::item.added', fn)Salla.event.off('cart::item.added', fn)
HelperSalla.cart.event.onItemAdded(fn)Salla.cart.event.offItemAdded(fn)

The helper names come from the event name: item.added becomes onItemAdded and offItemAdded. The same helpers are on Salla.event.cart.

app/components/cart/CartCount.tsx
import { useEffect, useState } from 'react';

export function CartCount() {
  const [count, setCount] = useState(0);

  useEffect(() => {
    const onUpdated = (...args: unknown[]) => {
      const cart = args[0] as { count?: number } | undefined;
      setCount(Number(cart?.count) || 0);
    };
    const sdk = window.salla;
    sdk?.event?.on?.('cart::updated', onUpdated);
    return () => sdk?.event?.off?.('cart::updated', onUpdated);
  }, []);

  return <span>{count}</span>;
}

Listen once

MethodRuns
Salla.event.once(name, fn)The next time the event fires, then stops listening.
Salla.event.onlyWhen(name, fn)Now if the event already fired on this page, otherwise the first time it fires. Returns a promise.

onlyWhen is the safe choice for "do this once the cart has loaded": it does not miss an event that fired before your component mounted.

What a handler receives

The arguments depend on the event. Most success events pass the response first and the id the call was about second:

Salla.cart.event.onItemAdded((response, productId) => {
  // response.data.cart is the updated cart
});

Failure events pass the error first: the request error, or a message string when the SDK stopped the call before sending it.

Send your own event

Salla.event.emit(name, ...data) fires an event, and Salla.event.dispatch does the same. Other code listens to it as usual.

Salla.event.emit('my-theme::filters.opened', { source: 'header' });

Give your events your own prefix, such as your theme name, so they never clash with SDK events.

Events not tied to a method

EventWhen
twilight::initiatedThe SDK finished starting. Salla.onReady() waits for it.
languages::translations.loadedThe SDK's own texts loaded. See Languages.
wishlist::storage.syncedThe saved wishlist ids were read from the server for a logged-in customer.
document::request.failedAny SDK request failed. The handler receives the request and the error.
login::openDispatch it to open the login popup: Salla.event.dispatch('login::open').

Gotchas

  • Pair on with off. Salla.cart.event.onItemAdded(fn) registers a wrapper, so Salla.event.off('cart::item.added', fn) removes nothing. Undo a helper with its off... helper.
  • Use the dotted name. The event is auth::logged.in, not auth::loggedIn. Check the table on the module page.
  • Do not emit a method name. For old Twig code, Salla.event.emit('cart::addItem', 123) calls Salla.cart.addItem(123) instead of firing an event. Keep your own names out of the module::method shape.

See also

On this page