---
title: "Widget functions and events"
url: "https://help.flowsplay.world/en/article/widget-functions-and-events"
language: "en"
last_updated: "2026-08-05T07:55:34.360Z"
---

# Widget functions and events

This guide covers the JavaScript functions and events of the FlowsPlay widget. It applies to both the FlashWins and the Jackpots widget, since both run on the same package. Installing and starting the widget is covered in the Installing Script guide; this guide covers the functions you call after it is running and the events it sends back to your page.

The widget ships as the npm package `flowsgames`. Once the script is installed, you can drive it in two ways: through the `flowsGames` object (the simplest option, used in the Installing Script guide) or through the `<flows-games>` element on the page. The functions and events below work with both.

## Widget functions

Call these on the `flowsGames` object after the widget has started.

| Function | What it does |
| --- | --- |
| `flowsGames.gameRoundStart()` | Locks the widget while a game round is in play. Any win that arrives during the round is queued, not shown, so it never interrupts the spin. |
| `flowsGames.gameRoundEnd()` | Unlocks the widget when the round finishes and shows the queued win, if there was one. |
| `flowsGames.lock()` | Manually locks the widget. While locked it will not open, change opt-in, drag, or minimise. |
| `flowsGames.unlock()` | Removes a manual lock. |
| `flowsGames.minimize()` | Collapses the floating bar to a compact pill. Works only in the floating layout. |
| `flowsGames.expand()` | Expands the pill back to the full bar. Works only in the floating layout. |
| `flowsGames.swapAppearance(appearance)` | Swaps the widget styling without resetting its state. Useful for switching a sub-brand theme on the fly. |
| `flowsGames.closeWidget()` | Closes and removes the widget. See the Installing Script guide. |

Lock the widget while a game round runs, then unlock it when the result is known:

```
function onSpinStart() {
  flowsGames.gameRoundStart();
}

function onSpinEnd() {
  flowsGames.gameRoundEnd();
}
```

## Widget events

The widget sends events to your page as it loads, opens, closes, and awards prizes. Listen to these to run your own logic, such as showing a custom message or refreshing the player's balance.

Use the `flowsgames-` events. They fire for both FlashWins and Jackpots and carry a `game` field set to `"flashwin"` or `"jackpot"`, so one handler can cover both.

| Event | When it fires |
| --- | --- |
| `flowsgames-loaded` | The widget has started and is visible. |
| `flowsgames-open` | The campaign has opened. |
| `flowsgames-won` | The current player has won a prize. The event detail carries the win information. |
| `flowsgames-won-other` | Another player has won a prize. |
| `flowsgames-closed` | The campaign has closed. The detail carries the reason. |
| `flowsgames-won-popup-closed` | The player has dismissed the win notification, whether by closing it, pressing Escape, or letting it close on its own. |

### Listening for events

The simplest way is `flowsGames.on()`. Register your handler before or after starting the widget, and it keeps working if the widget is closed and started again. The handler receives the event detail directly.

```
flowsGames.on("flowsgames-won", (detail) => {
  if (detail.game === "jackpot") {
    // handle a jackpot win
  } else {
    // handle a FlashWins win
  }
});

// on() returns a function that removes the handler
const stop = flowsGames.on("flowsgames-loaded", () => {
  console.log("Widget ready");
});
stop();
```

You can also listen on the `<flows-games>` element with a standard event listener. Here the details are on `event.detail`:

```
const widget = document.querySelector("flows-games");

widget.addEventListener("flowsgames-won", (event) => {
  console.log("Winner:", event.detail.game, event.detail);
});
```

### Listening to one feature only

You do not have to use the `flowsgames-` events. If you only care about one of them, listen to that feature's own events instead. The widget sends a full set for each:

-   **FlashWins only:** `flashwins-loaded`, `flashwins-open`, `flashwins-won`, `flashwins-won-other`, `flashwins-closed`, `flashwins-won-popup-closed`
-   **Jackpots only:** `jackpot-loaded`, `jackpot-open`, `jackpot-won`, `jackpot-won-other`, `jackpot-closed`, `jackpot-won-popup-closed`

Each fires only for its own feature, so your handler never has to check which one it was. For example, to react to FlashWins wins only:

```
flowsGames.on("flashwins-won", (detail) => {
  // fires only for FlashWins
});
```

Use the `flowsgames-` events when you want one handler for both features, and the feature-specific events when you want to react to just one.

## Widget events are not the same as push events

The events on this page are sent by the widget to the page it runs on. They are for sites that use the FlowsPlay widget. If you run your own widget in API mode, you subscribe to our push event service instead, which is covered in the Receive Events guides. Do not mix the two: the widget already handles the push events for you.

## Related topics

-   [Installing Script (FlashWins)](https://help.flowsplay.world/en/article/flashwins-installing-script) - install the widget and start or close it
-   [Receive FlashWins Events](https://help.flowsplay.world/en/article/flashwins-receive-events) - push events for API-mode integrations