Skip to main content

​
Overview

A UI element that displays the user’s balance information including available, pending, and reserve balances. This element provides a comprehensive view of the user’s financial status:
  • Available balance (funds ready for withdrawal)
  • Pending balance (funds being processed)
  • Regular reserve balance (funds held in reserve)
  • BNPL reserve balance (Buy Now Pay Later reserve funds)
Clicking on balance sections opens detailed breakdown modals by default.

​
Usage

​
Basic usage

// Create the element
const element = session.createElement("balance-element", {
  onReady: () => {
    console.log("Balance loaded!");
  },
});

// Mount it to a container
element.mount("#balance-container");

​
Hiding pending balance

const element = session.createElement("balance-element", {
  hidePendingBalance: true,
});

element.mount("#balance-container");

​
Custom breakdown handling

const element = session.createElement("balance-element", {
  onShowAvailableBalanceBreakdown: (ev) => {
    // Prevent the default modal from opening
    ev.preventDefault();
    // Show your own custom breakdown UI
    showCustomBreakdownModal();
  },
});

element.mount("#balance-container");

​
Listening to events

const element = session.createElement("balance-element", {});

element.on("ready", () => {
  console.log("Element loaded");
});

element.on("showAvailableBalanceBreakdown", (ev) => {
  console.log("User clicked on available balance");
  // Let default modal open, or call ev.preventDefault() to handle yourself
});

element.mount("#container");

const element = session.createElement("balance-element", {
  hidePendingBalance: true,
  onReady: (element) => {
    console.log("Balance element is ready");
  },
  onShowAvailableBalanceBreakdown: (ev) => {
    // Custom handling - prevent default modal
    ev.preventDefault();
    showCustomBreakdownModal();
  },
});

​
Events

Events emitted by the BalanceElement. Listen to these events using the on() method or by passing callback functions in the options.

​
error

Emitted when an error occurs during element initialization or operation. Callback signature: (error: unknown) => void

​
ready

Emitted when the element has finished loading and is ready for user interaction. Callback signature: (element: BalanceElement) => void

​
optionsUpdated

Emitted when the element’s options are updated via updateOptions(). Callback signature: (options: BalanceElementOptions) => void

​
snapshot

Emitted when the element’s internal state changes. Callback signature: (snapshot: BalanceElementSnapshot) => void

​
showAvailableBalanceBreakdown

Emitted when the user clicks to view the available balance breakdown. By default, opens the TotalBalanceBreakdown modal. Call ev.preventDefault() to handle this yourself. Callback signature: (ev: CustomEvent<BalanceElement>) => void

​
showRegularReserveBalanceBreakdown

Emitted when the user clicks to view the regular reserve balance breakdown. By default, opens the RegularReserveBalanceBreakdown modal. Call ev.preventDefault() to handle this yourself. Callback signature: (ev: CustomEvent<BalanceElement>) => void

​
showBnplReserveBalanceBreakdown

Emitted when the user clicks to view the BNPL reserve balance breakdown. By default, opens the BnplReserveBalanceBreakdown modal. Call ev.preventDefault() to handle this yourself. Callback signature: (ev: CustomEvent<BalanceElement>) => void

​
Methods

​
mount(container)

Mount the element to a DOM container. The container must be an empty element. The element will be appended as a child. If the element is already mounted, this method will log a warning and return.
ParameterTypeDescription
containerHTMLElement | #$\{string\}The container element or a CSS selector starting with ’#‘
// Using a selector
element.mount("#my-container");

// Using an element reference
const container = document.getElementById("my-container");
element.mount(container);

​
unmount()

Remove the element from the DOM and clean up all event listeners. After unmounting, the element instance should not be reused. Create a new element instance if you need to mount again. 
// Unmount when done
element.unmount();

// Commonly used in event handlers
element.on("complete", () => {
  element.unmount();
});

​
updateOptions(options)

Update the element’s configuration options after creation. Only the provided options will be updated; other options remain unchanged. The element will re-render with the new options.
ParameterTypeDescription
optionsPartial<BalanceElementOptions>Partial options object with the values to update
// Update a single option
element.updateOptions({
  onComplete: (ev) => {
    console.log("New handler!");
  },
});

​
getSnapshot()

Get the current state snapshot of the element. The snapshot contains the element’s current internal state, such as loading status, form values, or other element-specific data. Returns: BalanceElementSnapshot 
const snapshot = element.getSnapshot();
console.log("Current state:", snapshot.state);

// Or listen for changes
element.on("snapshot", (snapshot) => {
  console.log("State changed:", snapshot);
});

​
Types

​
BalanceElementOptions

Configuration options for the BalanceElement.
PropertyTypeRequiredDefaultDescription
hidePendingBalanceboolean | undefinedNofalseWhether to hide the pending balance from the display. When ‘true’, only the available balance will be shown.
onReady((element: BalanceElement) => void) | undefinedNo-Callback fired when the element has finished loading and is ready for interaction. This is equivalent to listening to the ‘ready’ event.
onShowAvailableBalanceBreakdown((ev: CustomEvent<BalanceElement>) => void) | undefinedNo-Callback fired when the user clicks to view the available balance breakdown. By default, opens the TotalBalanceBreakdown modal. Call ‘ev.preventDefault()’ to handle this yourself.
onShowRegularReserveBalanceBreakdown((ev: CustomEvent<BalanceElement>) => void) | undefinedNo-Callback fired when the user clicks to view the regular reserve balance breakdown. By default, opens the RegularReserveBalanceBreakdown modal. Call ‘ev.preventDefault()’ to handle this yourself.
onShowBnplReserveBalanceBreakdown((ev: CustomEvent<BalanceElement>) => void) | undefinedNo-Callback fired when the user clicks to view the BNPL reserve balance breakdown. By default, opens the BnplReserveBalanceBreakdown modal. Call ‘ev.preventDefault()’ to handle this yourself.

​
BalanceElementSnapshot

Represents the current state of the BalanceElement. Use element.getSnapshot() to get the current state, or listen to the snapshot event for changes.
PropertyTypeRequiredDefaultDescription
state"loading" | "ready"Yes-The current loading state of the element. - ‘“loading”’ - The element is initializing - ‘“ready”’ - The element is fully loaded and interactive