ListElement

The holdings behind an account’s balance. Every currency and token gets its own row, showing its name and its value in dollars, largest first. Rows can report which one the viewer tapped, so you can open your own screen for it.

This page documents @whop/elements@1.0.0-beta.0 and @whop/elements-react@1.0.0-beta.0.

Pre-release, not yet part of a stable release.

Mounts inside Balances, in Wallet. accountId comes from Wallet. Pass props and callbacks through the create options or React props.

Mounts anywhere in your view hierarchy. Takes an accountId and loads its own data; pass a closure too and the rows become tappable. The root is a VStack, so it sizes to its content and fills the width you give it.

React

import { WhopElements, Wallet, Balances, ListElement } from "@whop/elements-react";
import { loadWhop } from "@whop/elements";

function Example() {
  return (
    <WhopElements elements={loadWhop()}>
      <Wallet /* options */>
        <Balances>
          <ListElement onBalanceSelected={(e) => console.log(e)} onAccountSelected={(e) => console.log(e)} />
        </Balances>
      </Wallet>
    </WhopElements>
  );
}

Example data. Open the Playground.

Props

accessToken · string

A scoped token for the read. An account needs company:balance:read; a user’s holdings or owned-account list needs user:balance:read. Mint it on your server with POST /api/v1/access_tokens. Without it the read uses the viewer’s own session, which only works same-origin.

includeOwnedAccounts · boolean

For a user’s user_… account, list their personal balance followed by every owned account the backend returns instead of listing the holdings inside their personal account. Ignored for an account. Defaults to false.

showSourceCurrency · boolean

Show each row in the currency it is held in (€4.20, 0.00000009 cbBTC) and put the dollar value underneath. Off by default, so every row is in dollars. Defaults to false.

showUsdEquivalent · boolean

Keep the dollar value under a holding shown in its own currency. Only applies when showSourceCurrency is on. Defaults to true.

showPersonalAccount · boolean

Keep the personal row when includeOwnedAccounts is on. Turn it off if your app has no personal account to open. Defaults to true.

Events

Pass callbacks in the create options or React props.

onBalanceSelected

A holding row was clicked, with includeOwnedAccounts off. key is usd for the combined dollar row, otherwise the holding symbol (cbBTC, EUR), and kind tells you which of the three it is so you can route without classifying symbols yourself. The element never navigates.

Signature: ((payload: { key: string; kind: "usd" | "cash" | "asset"; }) => void)

onAccountSelected

An account row was clicked, with includeOwnedAccounts on. accountId is the personal user_… tag or an owned biz_… tag, and kind lets you route without inspecting it. The element never navigates.

Signature: ((payload: { accountId: string; kind: "personal" | "business"; }) => void)

onLoaderStart

Runs after the loading skeleton first paints and before onReady.

Signature: (() => void)

onReady

Runs after the element’s first complete paint.

Signature: (() => void)

onError

Runs when the element fails to load or crashes. The fallback remains visible. Use code for programmatic handling. sourceKey identifies a failed host-state source.

Signature: ((e: { message: string; code?: string | undefined; sourceKey?: string | undefined; }) => void)

Methods

Call these on the handle returned by create, or through a React ref.

mount

Mounts the element in target and starts loading. React components mount themselves.

Signature: (target: string | HTMLElement) => void

destroy

Removes the element and releases its frame and subscriptions. You can call it more than once. React removes the element automatically.

Signature: () => void

update

Merges new props into the mounted element. In React, change the component props instead.

Signature: (options: Partial<ListElementProps>) => void

Styling

Style these parts through appearance.classes. Use camel case or kebab case for property names and include units. Page stylesheets can’t reach the element’s frame. The framework validates each declaration before injecting it.

Class	Targets
.whop-BalanceRow	One balance row — its icon, name, value and chevron
.whop-BalancesSurface	The balances list — one row per holding or account

const wallet = whop.wallet.create({
  appearance: {
    classes: {
      'whop-BalanceRow': { borderRadius: '8px', fontWeight: '600' },
      'whop-BalancesSurface': { borderRadius: '8px', fontWeight: '600' }
    }
  }
});

wallet.update({
  appearance: { classes: { 'whop-BalanceRow': { fontWeight: '700' } } }
});

In React, pass appearance to <Wallet>. Set it globally with WhopElements({ appearance }).

Parameters

accountId · String · required

The account whose money the view reads. Use an account ID prefixed biz_. A user ID prefixed user_ reads the viewer’s own balance and needs viewer authentication (WhopSDK.configureWithOAuth), not an account token.

onBalanceSelected · ((WalletBalance) -> Void)?

Called with the row the viewer tapped. Omit it and the rows render without chevrons, and tapping does nothing.

WalletBalance

What a selection hands back:

• id: String: stable per row
• symbol: String: USD, BTC, …
• displayName: String: the name shown on the row
• amountUsd: Decimal: the row’s value in dollars
• isCrypto: Bool: a crypto holding rather than fiat

States

Shows two placeholder rows while the balances load. An account ID that can’t be resolved shows Couldn't load this account. If the balance read itself fails, the list renders empty rather than showing an error.

Good to know

• It doesn’t scroll on its own, so put it in a ScrollView when it shares a screen with other content.
• Pairs with BalanceElement, which shows the same account’s total and how it changed.

Call WhopSDK.configure(tokenProvider:) once at launch. Views wait for the token. See Getting started. Apply a theme with .whopTheme(_:).