Components
Balance
Native or ERC-20 balance for the connected account or any address.
Reads a balance and formats it with Token Amount. It defaults to the connected account’s native balance on the current chain, and refreshes every 15 seconds.
Loading balance
Installation
Section titled “Installation”npx shadcn@latest add @0xui/balancepnpm dlx shadcn@latest add @0xui/balanceyarn dlx shadcn@latest add @0xui/balancebunx --bun shadcn@latest add @0xui/balanceimport { Balance } from "@/components/balance";
// Connected account, native currency, current chain<Balance />;Examples
Section titled “Examples”ERC-20
Section titled “ERC-20”Pass the token contract. Balance, decimals and symbol are read in one batched call.
Loading balance
<Balance token="0xA0b8…eB48" price={1} />Headless
Section titled “Headless”import { useTokenBalance } from "@/components/balance";
const { value, decimals, symbol, phase, refetch } = useTokenBalance({ token });Call refetch() after a transaction to update right away.
States
Section titled “States”data-phase |
What the user sees |
|---|---|
idle |
Nothing: no address and no wallet connected. |
loading |
Skeleton the height of the text, “Loading balance” for screen readers. |
ready |
The formatted balance. |
error |
“—”, with “Couldn’t load balance” on hover. |
Also accepts the Token Amount formatting props: maxDecimals, compact, price, currency and locale. The amount morphs when it changes. Pass animate={false} to turn that off.
| Prop | Type | Default | Description |
|---|---|---|---|
address |
Address |
connected account | Whose balance. |
token |
Address |
— | ERC-20 contract. Omit for native. |
chainId |
number |
current chain | Chain to read. |
symbol |
string |
from chain | Override the symbol. |
refreshInterval |
number | false |
15000 |
Refetch interval in ms. |
enabled |
boolean |
true |
Set to false to skip reading, e.g. until a token is chosen. |
