Balance Display

Introduction

BalanceDisplay is a component for displaying balances from supported chains with real-time balance display and optional comparison currency.

Features

Token Definition: Define which tokens to include by specific asset IDs. Supports native tokens and tokens from pallet assets.
Balance Display: Show real-time token balances for connected accounts
Comparison Currency: Optionally include a comparison currency
Multi-Chain Support: Works with different Substrate-based chains
TypeScript: Full type safety with comprehensive interfaces
Customizable: Flexible styling, precision settings, and comparison currency

Installation

npx polkadot-ui@latest add balance-display

Usage

Balance Display

Formatted on-chain balance with optional comparison currency

Balance Display - Custom Thousands Separator and Decimal Separator

Formatted Polkadot USDT treasury balance with custom thousands and decimal separator

Balance Display - Compare Token

With compare token. Use any other token as compare token and pass the conversion rate.

Props

Prop	Type	Default	Description
`assetIds`	`number[]`	-	Array of asset IDs to filter tokens
`chainId`	`string`	`"paseoAssetHub"`	Chain ID to fetch tokens from
`value`	`number`	-	Currently selected token asset ID
`onChange`	`(assetId: number) => void`	-	Called when token selection changes
`placeholder`	`string`	`"Select Token"`	Button placeholder text
`withBalance`	`boolean`	`false`	Show token balances
`withSearch`	`boolean`	`false`	Enable search functionality in dialog
`includeNative`	`boolean`	`true`	Include native chain token
`balancePrecision`	`number`	`2`	Decimal precision for balance display
`variant`	`ButtonVariant`	`"outline"`	Button style variant
`disabled`	`boolean`	`false`	Disable the component
`className`	`string`	-	Additional CSS classes
`fallback`	`React.ReactNode`	-	Fallback content when loading

Connection States

The component shows different states based on wallet connection:

Connected: Shows available tokens with balances
Disconnected: Button is disabled with loading state
Loading: Shows spinner while fetching token data
No Tokens: Shows empty state when no tokens match filters

Token Filtering

Asset IDs

Specify which tokens to include using the assetIds prop:

<SelectTokenDialog
  chainId="paseoAssetHub"
  assetIds={[1984, 8, 27]} // Only show these specific tokens
  withBalance
/>

Native Token Inclusion

Control whether to include the chain's native token:

<SelectTokenDialog
  chainId="paseoAssetHub"
  assetIds={[1984, 8]}
  includeNative={true} // Include native token, default is true
  withBalance
/>

Search Functionality

When withSearch is enabled:

Users can search by token name or symbol
Search is case-insensitive
Results update in real-time
Shows "No tokens found" state for empty results

<SelectTokenDialog
  chainId="paseoAssetHub"
  assetIds={[1984, 8, 27, 1337, 2125]}
  withSearch
  withBalance
/>

Balance Display

When withBalance is enabled:

Shows formatted token balances for connected accounts
Balances update automatically when account changes
Precision controlled by balancePrecision prop
Handles loading states gracefully

<SelectTokenDialog
  chainId="paseoAssetHub"
  assetIds={[1984, 8, 27]}
  withBalance
  balancePrecision={4} // Show 4 decimal places
/>

Multi-Chain Support

The component supports different Asset Hub chains:

paseoAssetHub: Paseo Asset Hub (testnet)
kusamaAssetHub: Kusama Asset Hub
polkadotAssetHub: Polkadot Asset Hub

<SelectTokenDialog
  chainId="kusamaAssetHub"
  assetIds={[1000, 2000]}
  withBalance
/>

Token Information

Each token includes:

Symbol: Token ticker (e.g., "USDT", "DOT")
Name: Full token name
Decimals: Token precision
Logo: Token icon (when available)
Balance: User's current balance
Asset ID: On-chain asset identifier

Styling Options

Button Variants

Use different button styles:

<SelectTokenDialog
  variant="secondary" // or "outline", "ghost", etc.
  className="w-[200px]"
/>

Balance Precision

Control decimal places shown:

<SelectTokenDialog
  withBalance
  balancePrecision={6} // Show up to 6 decimal places
/>

Error Handling

The component handles various error states:

Network disconnection: Shows appropriate loading state
Failed token fetching: Graceful degradation
Invalid asset IDs: Filters out non-existent tokens
Balance fetch errors: Shows tokens without balance info

Provider Requirements

The component requires a PolkadotProvider wrapper:

import { PolkadotProvider } from "@/registry/polkadot-ui/lib/polkadot-provider.dedot";

<PolkadotProvider>
  <SelectTokenDialog
    chainId="paseoAssetHub"
    assetIds={[1984, 8, 27]}
    withBalance
  />
</PolkadotProvider>;

Alternatively, use the component with provider included:

import { SelectTokenDialogWithProvider } from "@/registry/polkadot-ui/blocks/select-token/select-token-dialog.dedot";

<SelectTokenDialogWithProvider
  chainId="paseoAssetHub"
  assetIds={[1984, 8, 27]}
  withBalance
/>;

Balance Display

On this page