Configuration

Set shared chains and identity resolution options in lib/onchain/config.ts. Components read explorer URLs from those chains and use the configured clients for name and avatar lookups.

npx shadcn add @onchain-ui/onchain-config

Components that read this file include it in their installation.

Edit the config file

lib/onchain/config.ts exports a plain object. Edit it to configure onchain-ui. Components import it directly, so you do not need an OnchainUIProvider.

// lib/onchain/config.ts
export const onchainConfig: OnchainUIConfig = {
  chains: [mainnet, base, arbitrum, optimism, polygon],
}

Define your chains once

If you use wagmi, reuse its chain list:

// lib/onchain/config.ts
import { wagmiConfig } from "@/lib/onchain/wagmi"

export const onchainConfig: OnchainUIConfig = {
  chains: wagmiConfig.chains,
}

AddressDisplay reads explorer URLs from chain.blockExplorers. When you reuse wagmi's chain list, adding a chain there also makes its explorer available to AddressDisplay.

Share your RPC endpoints

AddressIdentity uses read clients to resolve ENS names and Basenames, even when no wallet is connected. The default clients use public RPC endpoints.

Use getClient to share the clients from your wagmi config:

// lib/onchain/config.ts
import { getPublicClient } from "@wagmi/core"
import { wagmiConfig } from "@/lib/onchain/wagmi"

export const onchainConfig: OnchainUIConfig = {
  chains: wagmiConfig.chains,
  getClient: (chainId) => getPublicClient(wagmiConfig, { chainId }),
  avatarGatewayUrls: {
    ipfs: "https://gateway.pinata.cloud",
    arweave: "https://arweave.net",
  },
}

Identity lookups now use the endpoints and fallbacks in your wagmi transports.

Avatar text records can contain ipfs:// or ar:// URLs. The gateway options convert those records into URLs the browser can load. Use your own gateway if the bundled public gateways do not meet your availability or rate limit needs.

Re-installing and --overwrite

Registry items that use lib/onchain/config.ts include a copy of it. When a later install prompts to overwrite the file, decline to keep your changes.

shadcn add --overwrite skips that prompt and replaces the item's files with the published source. This resets your chains, getClient, and gateway settings when the item includes config.ts. It also replaces lib/onchain/crypto-icons.tsx when the item includes that file.

Precedence

Components check settings in this order:

1. Component props, such as name on NetworkLogo, explorerUrl on AddressDisplay, and resolverOptions on AddressIdentity.
2. Shared chains, clients, and avatar gateways in config.ts.
3. Built-in names and symbols, public RPC endpoints, and public asset gateways.

Use a prop to override a setting for one component instance.

Icons and data sources

Edit lib/onchain/crypto-icons.tsx to change token and network icons. It contains the built-in SVG logos and token icon URL builder. See Icon resolution.

Fetch balances, prices, and token lists in your app and pass them as props. See Data fetching for an example using TanStack Query.

Reference