# useBalance Hook

The `useBalance` hook fetches and watches an address balance on a given chain, pairing live USD conversion.

## Import

```tsx
import { useBalance } from "@scaffold-ui/hooks";
```

## Usage

```tsx
const {
  displayUsdMode,
  toggleDisplayUsdMode,
  formattedBalance,
  balanceInUsd,
  balance,
  isBalanceLoading,
  isBalanceError,
  isNativeCurrencyPriceLoading,
  isNativeCurrencyPriceError,
  isLoading,
  isError,
} = useBalance({
  address: "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
  chain: mainnet,
  defaultUsdMode: true,
});
```

## Parameters

| Parameter        | Type                     | Default | Description                                                                 |
| ---------------- | ------------------------ | ------- | --------------------------------------------------------------------------- |
| `address`        | `Address` *(optional)*   | -       | The address to watch. When omitted, the hook returns zeroed balance values. |
| `chain`          | `Chain`                  | -       | The **viem** chain configuration used for fetching balances and USD prices. |
| `defaultUsdMode` | `boolean` *(optional)*   | `false` | If `true` and price data is available, show USD values by default.          |

## Return Values

| Property                       | Type                             | Description                                                                 |
| ------------------------------ | -------------------------------- | --------------------------------------------------------------------------- |
| `displayUsdMode`               | `boolean`                        | Whether the display is currently set to USD.                                |
| `toggleDisplayUsdMode`         | `() => void`                     | Toggle between native and USD display (only active when price data exists). |
| `formattedBalance`             | `number`                         | Native balance normalized with `formatEther`.                               |
| `balanceInUsd`                 | `number`                         | USD value derived from `formattedBalance * nativeCurrencyPrice`.            |
| `balance`                      | `GetBalanceReturnType \| undefined` | Raw wagmi balance payload containing value, decimals, and symbol.          |
| `isBalanceLoading`             | `boolean`                        | Loading state for the balance fetch.                                       |
| `isBalanceError`               | `boolean`                        | Error state for the balance fetch.                                         |
| `isNativeCurrencyPriceLoading` | `boolean`                        | Loading state for fetching the native currency price.                       |
| `isNativeCurrencyPriceError`   | `boolean`                        | Error state for fetching the native currency price.                         |
| `isLoading`                    | `boolean`                        | Combined loading state: balance data or price is still loading.             |
| `isError`                      | `boolean`                        | Combined error state: balance data or price failed to load.                 |

:::info
USD display is enabled only after the native currency price has been fetched. If the price is not available, toggling to USD is disabled and native balance is shown.
:::

## Live Examples

### Basic Usage

Display a live balance with an inline USD toggle.

<DocsProvider>
  <UseBalanceBasicExample />

  <div style={{ height: 12 }} />
</DocsProvider>

```tsx
import React from "react";
import { useBalance } from "@scaffold-ui/hooks";
import { mainnet } from "viem/chains";

function BalanceWithToggle() {
  const address = "0xd8da6bf26964af9d7eed9e03e53415d37aa96045";
  const {
    formattedBalance,
    balanceInUsd,
    displayUsdMode,
    toggleDisplayUsdMode,
    isLoading,
  } = useBalance({
    address,
    chain: mainnet,
  });

  return (
    <div>
      <p>
        Balance: {displayUsdMode ? `$${balanceInUsd.toLocaleString()}` : `${formattedBalance.toLocaleString()} ETH`}
      </p>
      <button onClick={toggleDisplayUsdMode} disabled={isLoading}>
        Toggle USD / ETH
      </button>
    </div>
  );
}
```

### Loading and Error States

Handle asynchronous fetch states while keeping the toggle experience consistent.

<DocsProvider>
  <UseBalanceLoadingErrorExample />
</DocsProvider>

```tsx
import React, { useState } from "react";
import { useBalance } from "@scaffold-ui/hooks";
import { mainnet } from "viem/chains";

function BalanceWithLoadingStates() {
  const [isValidAddress, setIsValidAddress] = useState(true);
  const validAddress = "0xd8da6bf26964af9d7eed9e03e53415d37aa96045";
  const brokenAddress = "0x";
  const {
    formattedBalance,
    balanceInUsd,
    displayUsdMode,
    toggleDisplayUsdMode,
    isLoading,
    isError,
  } = useBalance({
    address: isValidAddress ? validAddress : brokenAddress,
    chain: mainnet,
    defaultUsdMode: true,
  });

  if (isLoading) return <p>Fetching balance…</p>;
  if (isError) return (
    <div>
        <p style={{ color: "red" }}>Could not fetch balance</p>
        <button
            style={{ display: "block", padding: "8px", background: "#dae8ff", borderRadius: "4px", marginTop: "4px", border: "none", cursor: "pointer", color: "#000" }}
            onClick={() => setIsValidAddress((v) => !v)}
        >
            Fetch balance of the valid address
        </button>
    </div>
  );

  return (
    <div>
      <p>
        Balance: {displayUsdMode ? `$${balanceInUsd.toLocaleString()}` : `${formattedBalance.toLocaleString()} ETH`}
      </p>
      <button onClick={toggleDisplayUsdMode}>Toggle USD / ETH</button>
      <button
        style={{ display: "block", padding: "8px", background: "#dae8ff", borderRadius: "4px", marginTop: "4px", border: "none", cursor: "pointer", color: "#000" }}
        onClick={() => setIsValidAddress((v) => !v)}
      >
        Try to fetch balance of the broken address
      </button>
    </div>
  );
}
```