Blocks
Portfolio
Token holdings with total value, sorted largest first, with spam kept out.
Holdings for a token list: total value on top, then one row per token with amount and value, largest first. Likely spam, tokens without a price and dust are collapsed under “Hidden tokens”. All balances are read in one batch.
vitalik.eth
Tokens use the token list standard. The demo uses a short fixed list and fixed holdings, behind a pretend one-second load so you see the skeleton first. Open “Hidden tokens” to see one of each kind: dust, no price, likely spam and not on the list.
Installation
Section titled “Installation”npx shadcn@latest add @0xui/portfoliopnpm dlx shadcn@latest add @0xui/portfolioyarn dlx shadcn@latest add @0xui/portfoliobunx --bun shadcn@latest add @0xui/portfolioimport { Portfolio } from "@/components/portfolio";
<Portfolio tokens={tokenList.tokens} prices={prices} />;It shows the connected account’s holdings, or pass address for anyone’s. Only tokens on chainId (the current chain by default) are read.
Headless: usePortfolio({ tokens, prices }) returns the shown rows, the hidden ones (each with its reason), and the total.
Prices
Section titled “Prices”Key prices by chainId:address (or plain address) when you can:
const prices = { "1:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48": 1, // USDC on Ethereum "1:0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE": 3150, // ETH};Symbol keys ({ USDC: 1 }) also work and are handy for demos, but a symbol is whatever the token’s deployer typed: a fake “USDC” would get the real one’s price. Address keys win when both are given. The same lookup, getTokenPrice(prices, token), is used by Token Select, Token Input, Send and Swap.
Wallets collect junk: airdropped tokens that advertise a “claim” site, copies of real tokens, and worthless dust. Portfolio hides a holding when, checked in this order:
| Reason | Shown as | Rule |
|---|---|---|
spam |
“Likely spam” | isSpam(token) is true. Defaults to looksLikeSpam. |
unpriced |
“No price” | No price for the token. Turn off with hideUnpriced={false}. |
dust |
“Under $0.50” | Worth less than minValue (default 0.5). |
Hidden rows are left out of the total, and listed with their reason under a collapsed “Hidden tokens (N)” so a false positive costs a click, not a missing balance. Spam rows show the symbol’s letters instead of the token’s logo. The chain’s native currency is never hidden.
Before any of this, only tokens in your list are shown at all, so tokens airdropped outside the list never appear. Spam can still come from the list itself or from tokens you add.
looksLikeSpam (from @/lib/token-list) is a cheap check for the common cases: names with links or “claim”/“airdrop”/“rewards”, a domain as the symbol, invisible characters, and Latin text mixed with lookalike letters (a Cyrillic “С” in “USDС”). It flags none of the 1,600 tokens on Uniswap’s default list. It can’t spot a well-named copy, which is why prices matter most: a copy has no price under its own address, so it’s hidden as unpriced.
Adding your own verdicts
Section titled “Adding your own verdicts”For wallet-grade filtering, check tokens against a scanning service, or rules in your indexer, from your server (they need an API key), and pass the verdicts in:
const { data: flagged = new Set<string>() } = useQuery({ queryKey: ["spam", chainId, address], queryFn: async () => { const addresses: string[] = await fetch(`/api/spam/${chainId}/${address}`).then((r) => r.json()); return new Set(addresses.map((a) => a.toLowerCase())); },});
<Portfolio tokens={tokens} prices={prices} isSpam={(token) => looksLikeSpam(token) || flagged.has(token.address.toLowerCase())}/>;Keep looksLikeSpam in the check unless you mean to replace it. Other filters: a blocklist on useTokenList removes tokens everywhere, not just here, and minValue={0} with hideUnpriced={false} turns hiding off.
Tokens from your indexer
Section titled “Tokens from your indexer”balances only covers tokens on your list. An indexer usually knows more: every token the address holds, with a name, symbol and decimals. Pass those as holdings:
<Portfolio tokens={tokens} holdings={rows.map((row) => ({ token: { chainId: 1, address: row.token, symbol: row.symbol, name: row.name, decimals: row.decimals }, balance: BigInt(row.balance), }))} prices={prices}/>While your query runs, pass isLoading. Portfolio shows its skeleton and doesn’t read from RPC in the meantime:
<Portfolio tokens={tokens} holdings={query.data} isLoading={query.isLoading} prices={prices} />The token list stays the allowlist. A holding on the list uses the list’s name and logo. A holding off the list goes under “Hidden tokens” as “Not on the token list”, out of the total.
Set showUnlisted to show them as normal rows instead. The spam, price and dust filters still apply. Key prices by address when you do: a price keyed by symbol also values every copy of that symbol.
<Portfolio holdings={holdings} prices={pricesByAddress} showUnlisted />States
Section titled “States”data-phase |
What the user sees |
|---|---|
idle |
“Connect a wallet to see its tokens.” |
loading |
A skeleton measured from the rows themselves when they are known, from three sample rows otherwise. |
ready |
Total and rows, and “Hidden tokens (N)” when some are hidden. |
empty |
“No tokens from this list in this wallet.” |
error |
Couldn’t load balances. |
Each row has data-hidden set to its reason when it’s hidden.
| Prop | Type | Default | Description |
|---|---|---|---|
tokens |
Token[] |
[] |
Tokens to check. With holdings, the allowlist. |
prices |
Record<string, number> |
— | Prices by chainId:address, address or symbol. |
address |
Address |
connected | Whose holdings. |
chainId |
number |
current | Chain to read. |
hideZero |
boolean |
true |
Hide empty balances. |
isSpam |
(token) => boolean |
looksLikeSpam |
Flags scam tokens. |
hideUnpriced |
boolean |
true |
Hide tokens without a price. |
minValue |
number |
0.5 |
Hide holdings worth less than this. |
currency |
string |
"USD" |
Currency for values. |
locale |
string |
runtime locale | Locale for amounts and values. Set it when rendering on a server, so server and browser agree. |
balances |
Record<address, bigint> |
— | Balances from your own source. Skips RPC reads. |
holdings |
{ token, balance }[] |
— | Holdings from your own source, with each token’s metadata. Skips RPC reads. |
showUnlisted |
boolean |
false |
Show holdings that aren’t on tokens. |
isLoading |
boolean |
false |
Your own balances or holdings are still loading. Shows the skeleton and skips RPC reads. |
pageSize |
number |
10 |
Rows per page, with “Show more”. |
title |
ReactNode |
"Portfolio" |
Heading. null hides it. |
