# Events (https://docs.salla.dev/twilight/react/sdk/events)



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](https://docs.salla.dev/twilight/react/guide/salla-sdk-and-events) shows the React patterns. This page is the reference.

## Event names [#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 [#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`.

```tsx title="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 [#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 [#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:

```ts
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 [#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.

```ts
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 [#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](https://docs.salla.dev/twilight/react/sdk/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 [#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 [#see-also]

* [Salla SDK and events](https://docs.salla.dev/twilight/react/guide/salla-sdk-and-events)
* [React to cart events](https://docs.salla.dev/twilight/react/recipes/react-to-cart-events)
* [Overview](https://docs.salla.dev/twilight/react/sdk)
