# Balance

> Native or ERC-20 balance for the connected account or any address.

- Install: `npx shadcn@latest add @0xui/balance`
- Registry JSON: https://0xui.io/r/balance.json
- Source: https://github.com/fimbul-lab/0xui/blob/main/registry/default/components/balance.tsx

Reads a balance and formats it with [Token Amount](https://0xui.io/components/token-amount.md). It defaults to the connected account's native balance on the current chain, and refreshes every 15 seconds.

## Installation

```bash
npx shadcn@latest add @0xui/balance
```

## Usage

```tsx
import { Balance } from "@/components/balance";

// Connected account, native currency, current chain
<Balance />;
```

## Examples

### ERC-20

Pass the token contract. Balance, decimals and symbol are read in one batched call.

```tsx
<Balance token="0xA0b8…eB48" price={1} />
```

### Headless

```tsx
import { useTokenBalance } from "@/components/balance";

const { value, decimals, symbol, phase, refetch } = useTokenBalance({ token });
```

Call `refetch()` after a transaction to update right away.

## 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. |

## Props

Also accepts the [Token Amount](https://0xui.io/components/token-amount.md) 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. |
