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.
| Way | Subscribe | Unsubscribe |
|---|---|---|
| By name | Salla.event.on('cart::item.added', fn) | Salla.event.off('cart::item.added', fn) |
| Helper | Salla.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.
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
| Method | Runs |
|---|---|
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
| Event | When |
|---|---|
twilight::initiated | The SDK finished starting. Salla.onReady() waits for it. |
languages::translations.loaded | The SDK's own texts loaded. See Languages. |
wishlist::storage.synced | The saved wishlist ids were read from the server for a logged-in customer. |
document::request.failed | Any SDK request failed. The handler receives the request and the error. |
login::open | Dispatch it to open the login popup: Salla.event.dispatch('login::open'). |
Gotchas
- Pair
onwithoff.Salla.cart.event.onItemAdded(fn)registers a wrapper, soSalla.event.off('cart::item.added', fn)removes nothing. Undo a helper with itsoff...helper. - Use the dotted name. The event is
auth::logged.in, notauth::loggedIn. Check the table on the module page. - Do not emit a method name. For old Twig code,
Salla.event.emit('cart::addItem', 123)callsSalla.cart.addItem(123)instead of firing an event. Keep your own names out of themodule::methodshape.