# 0xui --- > Copy-paste web3 React components built on wagmi, viem, Base UI and Tailwind. Every page of the docs at https://0xui.io, as Markdown. --- # Installation Source: https://0xui.io/getting-started/installation.md > Add the 0xui registry to a shadcn project and set up wagmi. 0xui is a [shadcn registry](https://ui.shadcn.com/docs/registry). Components are copied into your project as source, so you own and can edit them. ## 1. Set up shadcn If your project doesn't use shadcn yet, follow the [shadcn installation guide](https://ui.shadcn.com/docs/installation) for your framework. You need Tailwind CSS v4 and a `components.json`. 0xui needs the [Base UI](https://base-ui.com) flavor of shadcn (`npx shadcn@latest init --base base`). The Radix flavor isn't supported: components use Base UI props that Radix primitives don't have. ## 2. Add the 0xui registry Add the `@0xui` namespace to `components.json`: ```json title="components.json" ins={3-5} { // ... "registries": { "@0xui": "https://0xui.io/r/{name}.json" } } ``` ## 3. Add wagmi ```bash npx shadcn@latest add @0xui/wagmi-config ``` This adds two files: - `lib/wagmi-config.ts`: chains, connectors and transports. Edit it to match your app. - `components/web3-provider.tsx`: `WagmiProvider` and a TanStack `QueryClientProvider`. Wrap your app once: ```tsx title="app.tsx" import { Web3Provider } from "@/components/web3-provider"; export function App() { return {/* your app */}; } ``` Optionally, register the config type so wagmi hooks infer your chain IDs: ```ts title="lib/wagmi-config.ts" declare module "wagmi" { interface Register { config: typeof config; } } ``` If you already have a wagmi setup, skip this step. Every 0xui component reads from whatever `WagmiProvider` is above it. ## 4. Add components ```bash npx shadcn@latest add @0xui/chain-selector ``` Shared helpers (`@0xui/0xui-utils`, `@0xui/use-mounted`, …) and shadcn primitives (`popover`, `dialog`, …) install automatically as dependencies. ## Using an AI agent The shadcn MCP server lets agents browse and install from any registry in your `components.json`, including `@0xui`: ```bash npx shadcn@latest mcp init ``` --- # Conventions Source: https://0xui.io/getting-started/conventions.md > The rules every 0xui component follows, so once you know one you know them all. ## Hook, parts, shell Each component has three layers, and all of them are exported: 1. **Hook**: all wagmi calls and state. Use it alone to build your own UI. 2. **Parts**: small presentational pieces that take plain props. 3. **Shell**: the default composed component. Variants such as popover and dialog are thin shells over the same hook and parts. ## Props - `variant`, `size` and `className` on the root. - Icon slots take a component, or `false` to hide the icon. `disableIcons` hides all of them. - Overlays can be controlled or uncontrolled: `open`, `defaultOpen`, `onOpenChange`. - Callbacks are named `onX` and receive typed payloads. ## State Async components export their state as a union type, such as `type TxPhase = "idle" | "confirming" | "pending" | "success" | "error"`, and set it as `data-phase` on the root element. Style or test each state without reaching into internals: ```css [data-phase="pending"] { opacity: 0.8; } ``` When an action fails, `data-error` says why, as one stable word next to `data-phase`: | `data-error` | Meaning | | --- | --- | | `user-rejected` | The person dismissed the wallet prompt. Not an error. | | `reverted` | The transaction or call reverted. | | `insufficient-funds` | Not enough native currency for the value and gas. | | `wrong-chain` | The wallet is on, or can't switch to, the wrong chain. | | `no-wallet` | No wallet or connector is available. | | `unsupported` | The wallet doesn't support the request, like batching. | | `network` | The RPC failed or timed out. | | `unknown` | Anything else. Read the message. | `errorCode(phase, error)` in `0xui-utils` produces it, for your own components too. ## Agents Buttons that send, sign or approve carry `data-agent-confirm` with a sentence saying what they do, like "Send 0.1 ETH: sends a transaction on Ethereum from your wallet". Browser agents treat it as "a person must approve this first". Override the sentence with `agentConfirm`, or pass `agentConfirm={false}` to drop it. Together with `data-phase` and `data-error`, an agent can drive a 0xui interface and know what happened without reading the page. [Agent Tools](https://0xui.io/components/agent-tools.md) also gives agents the wallet state directly. ## Web3 rules - **Amounts are `bigint`** from end to end. Formatting goes through viem `formatUnits` / `parseUnits`, never `Number()`. - **Amount inputs use text**, `inputMode="decimal"`, never `type="number"`. - **Addresses** are checksummed, truncated as `0x1234…abcd`, and copyable. - **Explorer links** come from `chain.blockExplorers`. Nothing is hardcoded. - **A dismissed wallet prompt is a cancellation, not an error.** It gets a muted note, not red text. - **SSR-safe**: nothing that depends on the wallet renders until the component has mounted in the browser. ## Accessibility - Click targets are at least 44px. Every list supports keyboard navigation. - Icon-only triggers keep an accessible label. - Phase changes are announced politely. Errors use `role="alert"`. - Spinners always have a label. Disabled buttons say what is blocking them. --- # Hello dapp Source: https://0xui.io/getting-started/hello-dapp.md > Connect, switch network, show a balance and send a transaction, using only 0xui components. A whole dapp in about 40 lines: a header with network and wallet, a balance, a send button, and live transaction status. Connect the **Demo Wallet** to try it. Demo transactions aren't broadcast. ## Install ```bash npx shadcn@latest add @0xui/wagmi-config @0xui/wallet-button @0xui/chain-selector @0xui/balance @0xui/transaction-button @0xui/transaction-status @0xui/block-number ``` ## Code ```tsx import { useState } from "react"; import { parseEther, type Hash } from "viem"; import { useConnection } from "wagmi"; import { Balance } from "@/components/balance"; import { BlockNumber } from "@/components/block-number"; import { ChainSelector } from "@/components/chain-selector"; import { TransactionButton } from "@/components/transaction-button"; import { TransactionStatus } from "@/components/transaction-status"; import { WalletButton } from "@/components/wallet-button"; import { Web3Provider } from "@/components/web3-provider"; export default function App() { return ( ); } function HelloDapp() { const { address } = useConnection(); const [hash, setHash] = useState(); return (
{address && } Send 0.01 ETH {hash && }
); } ``` ## What you didn't have to write - A wallet picker with recent and installed wallets, and cancel handling. - A placeholder while a returning user's connection is restored. - The network check and "Switch to Ethereum" before sending. - Confirm, pending, success, reverted and cancelled states, each with words, not just a spinner. - `bigint`-safe balance formatting. --- # Token lists Source: https://0xui.io/getting-started/token-lists.md > 0xui uses the token list standard, the format of Uniswap's lists. Load any list with useTokenList. Every 0xui component that takes tokens (Token Select, Token Input, Swap, Send, Portfolio) takes them in the [token list standard](https://tokenlists.org). It's the JSON format Uniswap created, and CoinGecko, most DEXs and most wallets publish lists in it. So you don't map anything: load a list and pass its tokens. The demos in these docs use **[Uniswap Labs' default list](https://tokens.uniswap.org)**, fetched live: about 1,800 tokens across Ethereum, Base, Arbitrum, Optimism, Polygon and more. ## Install ```bash npx shadcn@latest add @0xui/use-token-list ``` ## Load a list ```tsx import { useTokenList } from "@/hooks/use-token-list"; import { UNISWAP_DEFAULT_LIST } from "@/lib/token-list"; import { TokenSelect } from "@/components/token-select"; function Picker() { const { tokens, isLoading } = useTokenList(UNISWAP_DEFAULT_LIST); const [token, setToken] = useState(); return ; } ``` `useTokenList`: - downloads the list once per session (cached with TanStack Query, one retry); - keeps only tokens on the current chain (or `chainId`, or `null` for all chains); - puts the chain's **native currency first**. Lists don't include it (Uniswap's has WETH, not ETH), so it's added from your wagmi chain config with the address `NATIVE_TOKEN_ADDRESS` (`0xEeee…EEeE`); - drops entries that aren't EVM tokens. Uniswap's list includes Solana tokens, for example. ### Several lists ```tsx const { tokens } = useTokenList( [UNISWAP_DEFAULT_LIST, "https://tokens.coingecko.com/base/all.json"], { extraTokens: importedTokens } ); ``` Earlier lists win when two lists contain the same token, and `extraTokens` win over everything. `ipfs://` and `ar://` list URLs work too. ## Allowlist and blocklist Long lists include tokens you may not want to offer. Pass an **allowlist** (a whitelist) to show only the tokens you support, or a **blocklist** to hide known scams: ```tsx const { tokens } = useTokenList(UNISWAP_DEFAULT_LIST, { allowlist: [USDC, USDT, WETH, WBTC], // only these, on any chain blocklist: ["8453:0x…"], // never this one, on Base }); ``` Entries are token addresses, or `chainId:address` to pin a chain. Symbols aren't accepted, because spam tokens copy the symbols of real ones. The blocklist wins when a token is on both, and the native currency is always kept. For plain arrays, use `applyTokenFilters(tokens, { allowlist, blocklist })` from `@/lib/token-list`. ## The token shape ```ts type TokenInfo = { chainId: number; address: Address; // checksummed name: string; symbol: string; decimals: number; logoURI?: string; // https://, ipfs:// or ar:// tags?: string[]; extensions?: { bridgeInfo?: Record; // Uniswap: the same token on other chains [key: string]: unknown; }; }; ``` Writing tokens by hand? Use the same shape. `nativeToken(chain)` builds the native-currency entry. ## Logos [Token Icon](https://0xui.io/components/token-icon.md) shows `logoURI` and resolves `ipfs://` through a gateway. When a logo fails to load, which happens often with list logos, it falls back to the built-in icon for the symbol, then to the symbol's first letters. ## Big lists Uniswap's list has about 400 tokens on Ethereum alone, so the components are built for that: - **Token Select** pages through the list 50 rows at a time (tokens you hold first), loading more as you scroll. - **Balances** for the whole list are read in batched multicalls. - **Portfolio** reads every token on the chain and shows 10 rows per page. > **Tip: In production** > > Reading balances for 400 tokens per user over RPC is fine for a prototype but hits public RPC rate limits at scale. We recommend an [index of the chain](https://0xui.io/getting-started/indexed-data.md): your own Postgres + ClickHouse, or a service like Goldsky. Pass its balances to the `balances` prop. ## Without the hook ```ts import { fetchTokenList, parseTokenList, mergeTokenLists } from "@/lib/token-list"; const list = await fetchTokenList("https://tokens.uniswap.org"); // validated and cleaned const fromFile = parseTokenList(await import("./my-list.json")); ``` --- # Indexed data Source: https://0xui.io/getting-started/indexed-data.md > For production, feed 0xui from an index of the chain, either your own (Postgres + ClickHouse) or a service like Goldsky. Out of the box, 0xui components read straight from the chain over RPC. That needs zero setup and suits prototypes, small token lists and single users. In production it hits limits: | Reading over RPC | What goes wrong | | --- | --- | | Balances for a 400-token list | Dozens of `eth_call` batches per user, and public RPCs rate-limit you. | | Event history (`historyBlocks`) | Providers cap `eth_getLogs` ranges, so you only see recent blocks. | | Transaction history | Only what this browser recorded: per device, and nothing from other apps. | | Portfolios across chains | One set of reads per chain, per user, per page view. | | Spam tokens | RPC can't tell a real USDC from a copy. Portfolio hides the obvious ones; verdicts for the rest need a scanner. | **We recommend putting an index of the chain behind your app** and passing its data into the components. Every data-heavy component accepts it through a prop and then skips its RPC reads. ## Plugging in your data | Component | Prop | Your index provides | | --- | --- | --- | | [Token Select](https://0xui.io/components/token-select.md) | `balances` | The account's balance per token address | | [Portfolio](https://0xui.io/blocks/portfolio.md) | `balances` | The same, for every token in the list | | [Portfolio](https://0xui.io/blocks/portfolio.md#tokens-from-your-indexer) | `holdings` | Every token the account holds, with its own metadata. Off-list tokens need `showUnlisted` | | [Transaction History](https://0xui.io/components/transaction-history.md) | `transactions` | The account's transactions, from any device or app | | [Event Feed](https://0xui.io/components/event-feed.md) | `initialEvents` | Past events. New ones still stream in over RPC. | | [`useTokenList`](https://0xui.io/getting-started/token-lists.md) | `allowlist` / `blocklist` | Tokens you've verified, or flagged as spam | | [Portfolio](https://0xui.io/blocks/portfolio.md#spam) | `isSpam` | Spam verdicts from a scanning service or your own rules | ```tsx function Holdings({ address }: { address: Address }) { const { tokens } = useTokenList(UNISWAP_DEFAULT_LIST); const { data } = useQuery({ queryKey: ["balances", address], queryFn: async () => { const rows: { token: string; balance: string }[] = await fetch(`/api/balances/${address}`).then((r) => r.json()); // bigints travel as strings over JSON return Object.fromEntries(rows.map((r) => [r.token, BigInt(r.balance)])); }, }); return ; } ``` While `balances` is `undefined` (still loading), components fall back to reading over RPC. Pass `{}` instead if you never want RPC reads. ## Option 1: run your own index (Postgres + ClickHouse) The split that works well for chain data: **Postgres for current state, ClickHouse for history.** - **Postgres** holds what changes in place and what you look up by key: current balances, allowances, your verified-token table, users. It's transactional, so balance updates and reorg rollbacks stay consistent. - **ClickHouse** holds what only grows: transfers, swaps, every event. It's a columnar database built for scanning and aggregating billions of rows, which is what "history for this address" and "volume per token per day" need. An indexer (your own service, or a framework such as Ponder or rindexer) follows new blocks, decodes the logs you care about, writes events to ClickHouse and applies their effects to Postgres. Your API serves the components. Example tables, to adapt rather than copy: ```sql -- Postgres: current balances, upserted by the indexer create table token_balances ( chain_id integer not null, owner text not null, -- lowercase address token text not null, balance numeric(78, 0) not null, -- fits uint256 block bigint not null, -- last block that changed it, for reorg handling primary key (chain_id, owner, token) ); ``` ```sql -- ClickHouse: every ERC-20 transfer, append-only CREATE TABLE transfers ( chain_id UInt32, block_number UInt64, block_time DateTime, tx_hash String, log_index UInt32, token LowCardinality(String), sender String, recipient String, value UInt256 ) ENGINE = ReplacingMergeTree ORDER BY (chain_id, block_number, tx_hash, log_index); -- ReplacingMergeTree de-duplicates re-ingested logs (after a restart or reorg) by the ORDER BY key. -- For "transfers of this address", add a table or projection ordered by (chain_id, recipient, block_number). ``` > **Caution** > > Handle reorgs. Recent blocks can be replaced. Either only index blocks past a confirmation depth, or record the block hash with each row and roll back rows from blocks that were replaced. ## Option 2: use a managed indexer (Goldsky) If you'd rather not run ingestion yourself, [Goldsky](https://goldsky.com) runs it for you: - **Subgraphs**: describe the events you care about and query the indexed result over GraphQL. A good fit for history and feeds. - **Mirror**: streams chain data (blocks, logs, transfers, decoded events) into a database you own, such as Postgres or ClickHouse, so you keep the setup from option 1 without writing the ingestion. Either way, the shape the components need doesn't change: balances by token address, transactions as `HistoryEntry[]`, events as decoded logs. ## When RPC is fine Keep the defaults for prototypes, internal tools, testnets, short token lists, and anything where one user loads one page now and then. The components are built so you can start on RPC and move to an index without changing the UI, only adding props. --- # Sign in with Ethereum Source: https://0xui.io/getting-started/siwe.md > Prove wallet ownership to your server with Sign Message and viem's SIWE helpers. A connected wallet tells your app which address is in the browser. It doesn't prove anything to your server: anyone can send an address in a request. Sign in with Ethereum ([EIP-4361](https://eips.ethereum.org/EIPS/eip-4361), SIWE) closes that gap. The wallet signs a short message, your server checks the signature, and then starts a session. [Sign Message](https://0xui.io/components/sign-message.md) handles the wallet side. viem's `viem/siwe` builds and verifies the message, so there is nothing else to install. Connect the **Demo Wallet** and sign. The demo stops at the signature: checking it is your server's job. ## How it works 1. Your server creates a one-time nonce and remembers it in the session. 2. The browser builds the SIWE message with that nonce, and the wallet signs it. 3. Your server verifies the signature, checks the nonce and domain, and stores the address in the session. ## Install ```bash npx shadcn@latest add @0xui/sign-message ``` ## Server Two endpoints. The examples use the web `Request` and `Response`, so they fit any framework. `session` stands for your session store, for example an encrypted `httpOnly` cookie. ```ts // GET /api/siwe/nonce import { generateSiweNonce } from "viem/siwe"; export async function GET() { const nonce = generateSiweNonce(); await session.set("siweNonce", nonce); return Response.json({ nonce }); } ``` ```ts // POST /api/siwe/verify import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; import { parseSiweMessage } from "viem/siwe"; const client = createPublicClient({ chain: mainnet, transport: http() }); export async function POST(request: Request) { const { message, signature } = await request.json(); const valid = await client.verifySiweMessage({ message, signature, domain: "example.com", nonce: await session.get("siweNonce"), }); // A nonce works once, whether or not the signature was good. await session.delete("siweNonce"); if (!valid) return new Response("Invalid signature", { status: 401 }); const { address, chainId } = parseSiweMessage(message); await session.set("user", { address, chainId }); return Response.json({ address }); } ``` `verifySiweMessage` checks the signature through the RPC, so smart-contract wallets verify too. Create the client for the chain the wallet signed on if your users have smart accounts on other chains. ## Client ```tsx import { useQuery } from "@tanstack/react-query"; import { useMemo } from "react"; import { createSiweMessage } from "viem/siwe"; import { useConnection } from "wagmi"; import { SignMessage } from "@/components/sign-message"; export function SignIn({ onSignedIn }: { onSignedIn: () => void }) { const { address, chainId } = useConnection(); const { data: nonce } = useQuery({ queryKey: ["siwe-nonce", address], queryFn: () => fetch("/api/siwe/nonce").then((r) => r.json()).then((d) => d.nonce as string), enabled: Boolean(address), staleTime: Infinity, }); const message = useMemo( () => address && chainId && nonce ? createSiweMessage({ address, chainId, domain: window.location.host, uri: window.location.origin, nonce, version: "1", statement: "Sign in to Example. This won't cost any gas.", }) : undefined, [address, chainId, nonce] ); return ( { const response = await fetch("/api/siwe/verify", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ message, signature }), }); if (response.ok) onSignedIn(); }} > Sign in ); } ``` Leave `verify` off here. It checks the signature in the browser, which proves nothing to your server. Build the message with `useMemo`. `createSiweMessage` stamps the current time, so building it on every render would change the message between the prompt and the request. ## Checklist | Check | Why | | --- | --- | | The nonce comes from the server and works once | A captured signature can't be replayed. | | The server checks `domain` | A signature made for another site is rejected. | | The session cookie is `httpOnly`, `Secure` and `SameSite` | Scripts can't read it, and other sites can't send it. | | Sign out when the wallet's address changes or disconnects | The session should match the wallet in the browser. Compare `useConnection().address` with the session's address. | | Authorize on the session's address, never on one from the request body | The request body is whatever the caller sends. | Signing in doesn't authorize transactions. The wallet still confirms each one. --- # AI agents Source: https://0xui.io/getting-started/agents.md > Give your coding agent the 0xui docs as Markdown, a skill, the shadcn MCP server or in-browser tools. 0xui is built to be read by agents as well as people. Pick whichever fits how your agent works. They all serve the same docs. ## Agent skill The skill tells an agent how to set up 0xui, which component fits which job, and the rules the components follow. Install it with the [skills CLI](https://github.com/vercel-labs/skills): ```bash npx skills add https://0xui.io ``` The site publishes it at [`/.well-known/agent-skills/index.json`](/.well-known/agent-skills/index.json), following the [Agent Skills discovery RFC](https://github.com/cloudflare/agent-skills-discovery-rfc). You can also install it from GitHub with `npx skills add fimbul-lab/0xui --skill 0xui`. ## Markdown docs Every page has a Markdown version without the live demos. Use **Copy page** at the top of a page to paste it into a chat, or point your agent at: | URL | What it returns | | --- | --- | | [`/llms.txt`](/llms.txt) | Setup and a one-line description of every page, grouped like the sidebar. Start here. | | [`/llms-full.txt`](/llms-full.txt) | Every page in one file. | | Any page URL + `.md` | One page, like [`/components/balance.md`](/components/balance.md). | | `/r/.json` | The registry item: dependencies and the full source of every file. | | `/r/-demo.json` | A runnable example for every component and block. | | `/props/.json` | The component's props, generated from its TypeScript types. | A request for a page with `Accept: text/markdown` gets the Markdown instead of the HTML. Each HTML page also links its Markdown version with ``, and every response links `/llms.txt` and the skill index in its `Link` header. ## shadcn MCP server The [shadcn MCP server](https://ui.shadcn.com/docs/mcp) lets an agent browse, search and install items from any registry in your `components.json`, including `@0xui`. Add the [0xui registry](https://0xui.io/getting-started/installation.md#2-add-the-0xui-registry) first, then set up your client: ```bash npx shadcn@latest mcp init --client claude ``` Other clients: `cursor`, `vscode`, `codex` and `opencode`. Then ask in plain words, like "add a wallet button and an ETH balance to the header using @0xui". The server finds each component's example as `-demo`. ## WebMCP In a browser with [WebMCP](https://webmachinelearning.github.io/webmcp/), this site registers tools the browser's agent can call instead of reading pages: | Tool | What it does | | --- | --- | | `list_docs` | Every page with a one-line description. | | `search_docs` | Full-text search, returning page ids and excerpts. | | `get_doc` | One page as Markdown, by id, name or URL. | | `get_registry_item` | What `shadcn add` installs for an item, with its source. | The tools only read the docs. They don't change anything in your browser or your project. ## In your app 0xui components are built so agents can drive the apps you make with them, too: - [Agent Tools](https://0xui.io/components/agent-tools.md) registers WebMCP tools for the wallet: who is connected, balances, chains, gas. - Buttons that send, sign or approve carry `data-agent-confirm`, so a browser agent asks a person before pressing them. - `data-phase` and `data-error` say what state a component is in and why an action failed. See [Conventions](https://0xui.io/getting-started/conventions.md#state). --- # Blocks Source: https://0xui.io/blocks.md > Whole features assembled from 0xui components. Install one and change what you need. - [Portfolio](https://0xui.io/blocks/portfolio.md): Token holdings with total value, sorted largest first, with spam kept out. - [Send](https://0xui.io/blocks/send.md): Send form for ETH and ERC-20s. Recipient with ENS, amount with balance, and a button that names what's missing. - [Swap](https://0xui.io/blocks/swap.md): Swap form with live quotes, flip, rate, price impact and an approval step. Bring your own quotes. --- # Portfolio Source: https://0xui.io/blocks/portfolio.md > Token holdings with total value, sorted largest first, with spam kept out. - Install: `npx shadcn@latest add @0xui/portfolio` - Registry JSON: https://0xui.io/r/portfolio.json - Source: https://github.com/fimbul-lab/0xui/blob/main/registry/default/components/portfolio.tsx 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. Tokens use the [token list standard](https://0xui.io/getting-started/token-lists.md). The demo uses a short fixed list and fixed [holdings](#tokens-from-your-indexer), 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 ```bash npx shadcn@latest add @0xui/portfolio ``` ## Usage ```tsx import { Portfolio } from "@/components/portfolio"; ; ``` 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 Key prices by `chainId:address` (or plain address) when you can: ```tsx 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. ## Spam 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 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: ```tsx const { data: flagged = new Set() } = 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())); }, }); looksLikeSpam(token) || flagged.has(token.address.toLowerCase())} />; ``` Keep `looksLikeSpam` in the check unless you mean to replace it. Other filters: a `blocklist` on [`useTokenList`](https://0xui.io/getting-started/token-lists.md) removes tokens everywhere, not just here, and `minValue={0}` with `hideUnpriced={false}` turns hiding off. > **Tip: In production** > > Over RPC, a portfolio costs one balance read per token, per user, per chain. We recommend an [index of the chain](https://0xui.io/getting-started/indexed-data.md), either your own (Postgres + ClickHouse) or a service like Goldsky. Pass its balances in: > > ```tsx > > ``` ## 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`: ```tsx ({ 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: ```tsx ``` 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. ```tsx ``` ## 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. ## Props | Prop | Type | Default | Description | | --- | --- | --- | --- | | `tokens` | `Token[]` | `[]` | Tokens to check. With `holdings`, the allowlist. | | `prices` | `Record` | — | 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` | — | 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. | --- # Send Source: https://0xui.io/blocks/send.md > Send form for ETH and ERC-20s. Recipient with ENS, amount with balance, and a button that names what's missing. - Install: `npx shadcn@latest add @0xui/send` - Registry JSON: https://0xui.io/r/send.json - Source: https://github.com/fimbul-lab/0xui/blob/main/registry/default/components/send.tsx A complete send flow built from [Address Input](https://0xui.io/components/address-input.md), [Token Input](https://0xui.io/components/token-input.md), [Transaction Button](https://0xui.io/components/transaction-button.md) and [Transaction Status](https://0xui.io/components/transaction-status.md). The button names the next thing to do: "Enter a recipient", "Enter an amount", "Insufficient USDC balance", then "Send USDC". Tokens use the [token list standard](https://0xui.io/getting-started/token-lists.md). The demo uses Uniswap's default list, loaded live with `useTokenList`. ## Installation ```bash npx shadcn@latest add @0xui/send ``` ## Usage ```tsx import { Send } from "@/components/send"; refetch()} />; ``` Native currency (`NATIVE_TOKEN_ADDRESS`) is sent as a value transfer. ERC-20s call `transfer(to, amount)`. The transaction runs on the selected token's chain, and the button offers a network switch if needed. ### Build your own `Send` is about 100 lines. If you need a different layout, copy it, or use its pure helpers: ```tsx import { sendBlocker, sendRequest } from "@/components/send"; const blocker = sendBlocker(draft, { recipientPhase, insufficient }); // "Enter an amount" | undefined const request = sendRequest({ recipient, amount, token }); // { transaction } | { contract } ``` ## Props | Prop | Type | Default | Description | | --- | --- | --- | --- | | `tokens` | `Token[]` | — | Sendable tokens. One token locks the picker. | | `defaultToken` | `Token` | first token | Initial token. | | `popular` | `string[]` | — | Quick picks. | | `prices` | `Record` | — | Fiat values. | | `onSubmitted` / `onSuccess` | — | — | Transaction callbacks. | | `title` | `ReactNode` | `"Send"` | Heading. `null` hides it. | --- # Swap Source: https://0xui.io/blocks/swap.md > Swap form with live quotes, flip, rate, price impact and an approval step. Bring your own quotes. - Install: `npx shadcn@latest add @0xui/swap` - Registry JSON: https://0xui.io/r/swap.json - Source: https://github.com/fimbul-lab/0xui/blob/main/registry/default/components/swap.tsx Two [Token Input](https://0xui.io/components/token-input.md) panels with a flip button, a live quote that refreshes, the rate (click to invert), price impact, and an [Approve Button](https://0xui.io/components/approve-button.md) in front of the swap when the sell token needs one. The demo uses fixed prices and a 0.3% fee. Nothing is broadcast. Tokens use the [token list standard](https://0xui.io/getting-started/token-lists.md). The demo uses Uniswap's default list, loaded live with `useTokenList`. ## Installation ```bash npx shadcn@latest add @0xui/swap ``` ## Quotes 0xui doesn't pick a DEX or aggregator. You pass `getQuote`, which returns the output amount and the transaction to send: ```tsx import { Swap, type GetQuote } from "@/components/swap"; const getQuote: GetQuote = async ({ sellToken, buyToken, sellAmount, taker }) => { const res = await fetch(`/api/quote?sell=${sellToken.address}&buy=${buyToken.address}&amount=${sellAmount}&taker=${taker}`); const q = await res.json(); return { buyAmount: BigInt(q.buyAmount), transaction: { to: q.to, data: q.data, value: BigInt(q.value) }, spender: q.allowanceTarget, // omit for native sells priceImpact: q.priceImpact, }; }; ; ``` Quotes are fetched 400 ms after typing stops, cached per amount and token pair, and refreshed every 15 seconds. Keep API keys on your server. ## States The swap button always names the blocker: | Situation | Button | | --- | --- | | No token picked | Select a token | | No amount | Enter an amount | | Amount above balance | Insufficient ETH balance | | Quote loading or out of date | Fetching quote… | | `getQuote` threw | No route found, plus the error message | | ERC-20 sell without allowance | Approve USDC | | Ready | Swap | Price impact over 5% shows in amber, and over 15% in red. ## Props | Prop | Type | Description | | --- | --- | --- | | `tokens` | `Token[]` | Tokens for both pickers. | | `getQuote` | `GetQuote` | Your quote function. | | `defaultSellToken` / `defaultBuyToken` | `Token` | Initial pair. Sell defaults to the first token. | | `popular` | `string[]` | Quick picks. | | `prices` | `Record` | Fiat values. | | `onSubmitted` / `onSuccess` | — | Transaction callbacks. The input clears on success. | | `title` | `ReactNode` | Heading. Defaults to `"Swap"`. `null` hides it. | Headless pieces: `useSwapQuote` and `formatRate`. --- # Components Source: https://0xui.io/components.md > Every 0xui component, grouped by what it is for. ## Wallet Connect, show the account, sign. - [Wallet Button](https://0xui.io/components/wallet-button.md): One button for the whole wallet lifecycle. Connect, restore, account. - [Connect Wallet](https://0xui.io/components/connect-wallet.md): Wallet picker with recent and installed badges, per-wallet pending state and cancel handling. - [Account](https://0xui.io/components/account.md): Connected-account button with a panel for balance, copy, explorer link, account switching and disconnect. - [Sign Message](https://0xui.io/components/sign-message.md): Asks the wallet to sign a message or typed data, with labeled steps and optional verification. ## Network Pick a chain, guard against the wrong one, show its pulse. - [Chain Selector](https://0xui.io/components/chain-selector.md): Network switcher with chain icons, active-chain indicator, per-row pending state and inline errors. - [Network Guard](https://0xui.io/components/network-guard.md): Shows a "Switch to " notice when the wallet is on a network the content doesn't support. - [Chain Badge](https://0xui.io/components/chain-badge.md): Static chain chip with icon and name. - [Block Number](https://0xui.io/components/block-number.md): Live block indicator that doubles as an RPC health check. - [Gas Price](https://0xui.io/components/gas-price.md): Current gas price in gwei, optionally colored low, medium or high. ## Identity Addresses, ENS names and avatars. - [Address](https://0xui.io/components/address.md): ENS name or checksummed, truncated address, with copy and explorer link. - [Address Input](https://0xui.io/components/address-input.md): Recipient field that takes an address or ENS name, resolves names, and catches checksum typos. - [Address Avatar](https://0xui.io/components/address-avatar.md): ENS avatar, or a deterministic gradient for any address. - [ENS Profile](https://0xui.io/components/ens-profile.md): Profile card for an ENS name or address. Avatar, name, bio and links. - [Explorer Link](https://0xui.io/components/explorer-link.md): Link to an address, transaction or block on the chain's block explorer. ## Tokens Balances, amounts and token pickers. - [Token Input](https://0xui.io/components/token-input.md): The swap panel. Amount, token picker, fiat value, balance with Max, insufficient-balance state. - [Token Select](https://0xui.io/components/token-select.md): Searchable token picker with recent and popular tokens and the user's balances. - [Amount Input](https://0xui.io/components/amount-input.md): Large decimal input for token amounts. String state, decimal clamping, lenient paste, Max. - [Balance](https://0xui.io/components/balance.md): Native or ERC-20 balance for the connected account or any address. - [Token Amount](https://0xui.io/components/token-amount.md): Formats bigint token amounts without losing precision. - [Token Icon](https://0xui.io/components/token-icon.md): Token logo with fallbacks and an optional chain badge. - [Add Token](https://0xui.io/components/add-token.md): Button that asks the wallet to track a token, e.g. "Add USDC to wallet". - [NFT Card](https://0xui.io/components/nft-card.md): Image, name and collection for an ERC-721 or ERC-1155 token, from its on-chain metadata. ## Transactions Send, approve, track and read contracts. - [Transaction Button](https://0xui.io/components/transaction-button.md): Sends a transaction and shows every step on the button. Connect, switch network, confirm, pending, done. - [Approve Button](https://0xui.io/components/approve-button.md): ERC-20 approval gate. Shows "Approve" until the allowance covers the amount, then your action. - [Batch Transaction](https://0xui.io/components/batch-transaction.md): Several calls as one action. One wallet prompt with EIP-5792, step by step otherwise. - [Transaction Status](https://0xui.io/components/transaction-status.md): Inline card that follows a transaction from submitted to confirmed. - [Transaction Toast](https://0xui.io/components/transaction-toast.md): Follow a transaction in a toast, from pending to confirmed or reverted. - [Transaction History](https://0xui.io/components/transaction-history.md): Transactions sent from your app, with live status. Stored in the browser. - [Contract Form](https://0xui.io/components/contract-form.md): Read and write forms for any contract, generated from its ABI. - [Event Feed](https://0xui.io/components/event-feed.md): Live list of a contract's events, newest first, each linked to its transaction. ## Utilities Small pieces the other components are built from, and tools for browser agents. - [Copy Button](https://0xui.io/components/copy-button.md): Icon button that copies a value and confirms with a checkmark. - [Responsive Dialog](https://0xui.io/components/responsive-dialog.md): A dialog that becomes a bottom drawer on small screens. - [Morph Text](https://0xui.io/components/morph-text.md): Text that morphs from the old value to the new one when it changes. - [Agent Tools](https://0xui.io/components/agent-tools.md): WebMCP tools that let browser agents read the wallet, its balances and chains, without clicking through your app. --- # Wallet Button Source: https://0xui.io/components/wallet-button.md > One button for the whole wallet lifecycle. Connect, restore, account. - Install: `npx shadcn@latest add @0xui/wallet-button` - Registry JSON: https://0xui.io/r/wallet-button.json - Source: https://github.com/fimbul-lab/0xui/blob/main/registry/default/components/wallet-button.tsx The wallet button most apps need in their header. It shows "Connect wallet" when disconnected and the [Account](https://0xui.io/components/account.md) button when connected. While wagmi restores a previous connection on page load, it shows a placeholder, so returning users never see a flash of "Connect wallet". ## Installation ```bash npx shadcn@latest add @0xui/wallet-button ``` ## Usage ```tsx import { WalletButton } from "@/components/wallet-button"; ; ``` Pass props through to either state: ```tsx ``` ## States | Phase | What the user sees | | --- | --- | | `restoring` | Skeleton the size of the button: during server render and while wagmi reconnects. | | `disconnected` | [Connect Wallet](https://0xui.io/components/connect-wallet.md) button. | | `connected` | [Account](https://0xui.io/components/account.md) button. | `useWalletButtonPhase()` returns the current phase. ## Props | Prop | Type | Description | | --- | --- | --- | | `connect` | `ConnectWalletProps` | Props for the connect button and picker. | | `account` | `AccountProps` | Props for the account button and panel. | | `className` | `string` | Applied in every state. | --- # Connect Wallet Source: https://0xui.io/components/connect-wallet.md > Wallet picker with recent and installed badges, per-wallet pending state and cancel handling. - Install: `npx shadcn@latest add @0xui/connect-wallet` - Registry JSON: https://0xui.io/r/connect-wallet.json - Source: https://github.com/fimbul-lab/0xui/blob/main/registry/default/components/connect-wallet.tsx A "Connect wallet" button that opens a wallet picker. The wallets are the connectors in your wagmi config. Browser extensions that announce themselves ([EIP-6963](https://eips.ethereum.org/EIPS/eip-6963)) appear automatically with their own icon. Pick **Demo Wallet** to try it without an extension. ## Installation ```bash npx shadcn@latest add @0xui/connect-wallet ``` ## Usage ```tsx import { ConnectWallet } from "@/components/connect-wallet"; ; ``` Most apps want [Wallet Button](https://0xui.io/components/wallet-button.md), which shows this button while disconnected and the account once connected. ## Examples ### Custom trigger `ConnectWallet` accepts every shadcn `Button` prop. Its children become the label. ```tsx Sign in ``` ### Your own trigger Open the picker from anywhere with `ConnectWalletDialog`: ```tsx import { ConnectWalletDialog } from "@/components/connect-wallet"; const [open, setOpen] = useState(false); ; ``` ### Headless ```tsx import { useConnectWallet } from "@/components/connect-wallet"; const { wallets, connect, phase, pendingId } = useConnectWallet(); // wallets: { id, name, icon, installed, recent, connector }[] ``` ## Behavior - **Order:** the wallet used last comes first, then installed extensions, then everything else. - **Fewer choices:** shows `maxVisible` wallets (4 by default). The rest sit behind "Other wallets". - **Duplicates:** the generic `injected()` connector is hidden when extensions announce themselves, since it would duplicate one of them. - **Closing:** the dialog closes itself after a successful connection. - **Small screens:** below 640px the picker opens as a bottom drawer, within thumb reach, and can be swiped away. Set `mode` to force a dialog or a drawer. See [Responsive Dialog](https://0xui.io/components/responsive-dialog.md). ## States `data-phase` on the dialog holds the current state. | `data-phase` | What the user sees | | --- | --- | | `idle` | Wallet list. | | `connecting` | Spinner on the chosen wallet, other rows disabled, "Confirm the connection in <wallet>". | | `cancelled` | The user closed the wallet prompt. Muted "Request cancelled" note. Not an error. | | `error` | The wallet's message, with `role="alert"`. | ## Props `ConnectWallet` also accepts all shadcn `Button` props. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `open` / `defaultOpen` / `onOpenChange` | — | — | Control the dialog. | | `onConnect` | `(connector: Connector) => void` | — | Called after a wallet connects. | | `title` | `ReactNode` | `"Connect a wallet"` | Dialog title. | | `maxVisible` | `number` | `4` | Wallets shown before "Other wallets". | | `footer` | `ReactNode` | privacy note | Small print under the list. `null` hides it. | | `mode` | `"auto" \| "dialog" \| "drawer"` | `"auto"` | Bottom drawer on small screens, dialog otherwise. Or force one. | --- # Account Source: https://0xui.io/components/account.md > Connected-account button with a panel for balance, copy, explorer link, account switching and disconnect. - Install: `npx shadcn@latest add @0xui/account` - Registry JSON: https://0xui.io/r/account.json - Source: https://github.com/fimbul-lab/0xui/blob/main/registry/default/components/account.tsx The button shows the connected account's avatar and ENS name, or its truncated address. It opens a panel with the balance, current network, copy, explorer link and disconnect. It renders nothing while disconnected. ## Installation ```bash npx shadcn@latest add @0xui/account ``` ## Usage ```tsx import { Account } from "@/components/account"; ; ``` To show "Connect wallet" while disconnected as well, use [Wallet Button](https://0xui.io/components/wallet-button.md). ## Examples ### Balance in the trigger ```tsx ``` ### Switch account wagmi can hold several wallet connections at once. When more than one wallet is connected, the panel lists the others under "Switch account". Picking one makes it the current account for the whole app. Disconnect only disconnects the current wallet. There is nothing to configure: the list appears once a second wallet connects, for example through [Connect Wallet](https://0xui.io/components/connect-wallet.md). Accounts inside one wallet are switched in the wallet itself. wagmi follows the change, and the button updates. ### Extra panel content Children render at the bottom of the panel, above disconnect: ```tsx Settings ``` ### Headless ```tsx import { useConnectedAccount } from "@/components/account"; const { address, ensName, displayName, chain, connector, disconnect } = useConnectedAccount(); // With several wallets connected: const { otherAccounts, switchAccount, isSwitching } = useConnectedAccount(); otherAccounts.map(({ address, connector }) => switchAccount(connector)); ``` ## Props | Prop | Type | Default | Description | | --- | --- | --- | --- | | `open` / `defaultOpen` / `onOpenChange` | — | — | Control the panel. | | `showBalance` | `boolean` | `false` | Show the native balance in the trigger. | | `onDisconnect` | `() => void` | — | Called after disconnecting. | | `children` | `ReactNode` | — | Extra panel content. | --- # Sign Message Source: https://0xui.io/components/sign-message.md > Asks the wallet to sign a message or typed data, with labeled steps and optional verification. - Install: `npx shadcn@latest add @0xui/sign-message` - Registry JSON: https://0xui.io/r/sign-message.json - Source: https://github.com/fimbul-lab/0xui/blob/main/registry/default/components/sign-message.tsx For sign-in flows, off-chain orders, and proving ownership of an address. It signs plain messages (EIP-191) or typed data (EIP-712), labels each step, and can check the signature against the connected address. Connect the **Demo Wallet** to try it. Demo signatures come from a throwaway key, so they wouldn't verify against the demo address. ## Installation ```bash npx shadcn@latest add @0xui/sign-message ``` ## Usage ```tsx import { SignMessage } from "@/components/sign-message"; login(address, signature)} > Sign in ; ``` Verification goes through the RPC, so smart-contract wallets (ERC-1271 and ERC-6492) verify too. It's a convenience for the UI: **always verify again on your server** before trusting a signature. For a full sign-in flow with a nonce, a server check and a session, see [Sign in with Ethereum](https://0xui.io/getting-started/siwe.md). ## Examples ### Typed data ```tsx ``` ## States | `data-phase` | Button | | --- | --- | | `idle` | Your label, or "Connect wallet" | | `signing` | Spinner, "Sign in wallet…" | | `verifying` | Spinner, "Verifying…" | | `signed` | Check, "Signed" or "Signature verified" | | `invalid` | Alert: the signature doesn't match the connected address. | | `cancelled` | "Cancelled in wallet." Not an error. | | `error` | Alert with the wallet's message. | ## Props Also accepts shadcn `Button` props. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `message` | `string \| { raw: Hex }` | — | Message to sign. Pass this or `typedData`. | | `typedData` | `TypedDataDefinition` | — | EIP-712 payload. | | `verify` | `boolean` | `false` | Check the signature after signing. | | `onSigned` | `(signature) => void` | — | Called with the signature. | | `showMessage` | `boolean` | `false` | Show what is being signed. | | `showSignature` | `boolean` | `false` | Show the signature with copy. | | `children` | `ReactNode` | `"Sign message"` | Label. | | `agentConfirm` | `string \| false` | label + what it does | Sets `data-agent-confirm`, so browser agents ask a person first. `false` drops it. | Headless: `useSignFlow(request, { verify })`. --- # Chain Selector Source: https://0xui.io/components/chain-selector.md > Network switcher with chain icons, active-chain indicator, per-row pending state and inline errors. - Install: `npx shadcn@latest add @0xui/chain-selector` - Registry JSON: https://0xui.io/r/chain-selector.json - Source: https://github.com/fimbul-lab/0xui/blob/main/registry/default/components/chain-selector.tsx Default, IconOnly, Dialog, GroupByNetwork, Branded, } from "@/demos/chain-selector"; Shows the current chain and lets the user switch to any chain in your wagmi config. Comes as a popover (`ChainSelector`) and a dialog (`ChainSelectorDialog`). Both share the same props and behavior. ## Installation ```bash npx shadcn@latest add @0xui/chain-selector ``` Requires the `@0xui` registry in `components.json` and a `` around your app. See [Installation](https://0xui.io/getting-started/installation.md). ## Usage ```tsx import { ChainSelector } from "@/components/chain-selector"; ; ``` Chains come from your wagmi config. There is nothing to pass in. ## Examples ### Icon only The label is hidden visually but stays available as a tooltip and to screen readers. ```tsx ``` ### Dialog Better on small screens, or when the list of chains is long. ```tsx import { ChainSelectorDialog } from "@/components/chain-selector"; ; ``` ### Grouped by network Splits chains into Mainnet and Testnet tabs, based on `chain.testnet`. ```tsx ``` ### Branded icons ```tsx ``` ## States | State | What the user sees | | --- | --- | | Before hydration | A skeleton of the icon and name, so server HTML never shows wallet state and nothing moves when the chain appears. "Select Chain" for screen readers. | | Idle | Current chain icon and name. In the list, the active chain has a checkmark and `aria-current`. | | Switching | Spinner on the trigger and on the target row. The list is disabled until the wallet responds. | | Cancelled | The user dismissed the wallet prompt. Muted "Request cancelled in wallet" note. | | Error | Any other failure. The wallet's message is shown inline with `role="alert"`. | | Wrong network | The wallet is on a chain your config doesn't include. The trigger reads "Wrong network" with a warning icon, and the list asks the user to pick a supported chain. | Errors and the cancelled note clear when the selector is reopened. ## Props | Prop | Type | Default | Description | | --- | --- | --- | --- | | `variant` | `"background" \| "branded" \| "mono"` | `"background"` | Chain icon style. | | `monoColor` | `string` | — | Icon color. Only with `variant="mono"`. | | `iconOnly` | `boolean` | `false` | Hide the visible label. It stays accessible. | | `groupByNetwork` | `boolean` | `false` | Group chains into Mainnet / Testnet tabs. | | `chainIcon` | `ComponentType \| false` | `NetworkIcon` | Custom chain icon, or `false` to hide it. | | `chevronIcon` | `ComponentType<{ className?: string }> \| false` | `ChevronDownIcon` | Custom chevron, or `false` to hide it. | | `loaderIcon` | `ComponentType<{ className?: string }> \| false` | `Loader2Icon` | Custom spinner, or `false` to hide it. | | `disableIcons` | `boolean` | `false` | Hide every icon. Overrides the icon props. | | `chainMeta` | `(chain: Chain) => ReactNode` | — | Extra detail under each chain's name, e.g. `"~2s blocks"`. | --- # Network Guard Source: https://0xui.io/components/network-guard.md > Shows a "Switch to " notice when the wallet is on a network the content doesn't support. - Install: `npx shadcn@latest add @0xui/network-guard` - Registry JSON: https://0xui.io/r/network-guard.json - Source: https://github.com/fimbul-lab/0xui/blob/main/registry/default/components/network-guard.tsx Wrap anything that only works on certain chains. When the connected wallet is elsewhere, it shows a notice with a one-click switch. With no wallet connected, or on a supported chain, it renders its children unchanged. ## Installation ```bash npx shadcn@latest add @0xui/network-guard ``` ## Usage ```tsx import { NetworkGuard } from "@/components/network-guard"; ; // Several chains: the first is offered as the switch target … ``` `mode="banner"` (the default) shows the notice above the content. `mode="replace"` hides the content until the network is right. ## Props | Prop | Type | Default | Description | | --- | --- | --- | --- | | `chainId` | `number \| number[]` | — | Supported chains. | | `mode` | `"banner" \| "replace"` | `"banner"` | Notice above the content, or instead of it. | | `children` | `ReactNode` | — | Guarded content. | Headless: `useNetworkGuard(chainId)` returns `wrongNetwork`, `target`, `switchToTarget()` and `phase`. --- # Chain Badge Source: https://0xui.io/components/chain-badge.md > Static chain chip with icon and name. - Install: `npx shadcn@latest add @0xui/chain-badge` - Registry JSON: https://0xui.io/r/chain-badge.json - Source: https://github.com/fimbul-lab/0xui/blob/main/registry/default/components/chain-badge.tsx Labels a chain, e.g. where a token lives or which network a transaction ran on. It doesn't switch chains. Use [Chain Selector](https://0xui.io/components/chain-selector.md) for that. ## Installation ```bash npx shadcn@latest add @0xui/chain-badge ``` ## Usage ```tsx import { ChainBadge } from "@/components/chain-badge"; ; ``` The name comes from your wagmi config. Chains that aren't configured show as "Chain <id>", unless you pass `name`. ## Examples ### Icon only ```tsx ``` ### Just the icon `ChainIcon` is the logo on its own, with a placeholder for unknown chains. Other 0xui components reuse it. ```tsx import { ChainIcon } from "@/components/chain-badge"; ; ``` ## Props Also accepts all `` props. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `chainId` | `number` | — | Chain to show. | | `name` | `string` | from config | Display name. | | `iconOnly` | `boolean` | `false` | Hide the name visually. It stays accessible. | | `variant` | `"background" \| "branded" \| "mono"` | `"background"` | Icon style. | | `chainIcon` | `ComponentType \| false` | `ChainIcon` | Custom icon, or `false` to hide it. | --- # Block Number Source: https://0xui.io/components/block-number.md > Live block indicator that doubles as an RPC health check. - Install: `npx shadcn@latest add @0xui/block-number` - Registry JSON: https://0xui.io/r/block-number.json - Source: https://github.com/fimbul-lab/0xui/blob/main/registry/default/components/block-number.tsx Shows the latest block and updates as new blocks arrive. The dot shows whether the RPC is responding. ## Installation ```bash npx shadcn@latest add @0xui/block-number ``` ## Usage ```tsx import { BlockNumber } from "@/components/block-number"; ; ``` With HTTP transports, wagmi polls for new blocks (every 4 seconds by default). Pass `watch={false}` to fetch once. ## Examples ### Linked to the explorer ```tsx ``` ## States `data-phase` on the root holds the current state. | `data-phase` | What the user sees | | --- | --- | | `loading` | Grey dot and a skeleton where the number will be. "Loading block…" for screen readers. | | `live` | Green dot (pulses while watching) and the block number. | | `error` | Red dot, "RPC unavailable". | ## Props | Prop | Type | Default | Description | | --- | --- | --- | --- | | `chainId` | `number` | current chain | Chain to watch. | | `watch` | `boolean` | `true` | Keep updating. | | `explorer` | `boolean` | `false` | Link the number to the block on the explorer. | --- # Gas Price Source: https://0xui.io/components/gas-price.md > Current gas price in gwei, optionally colored low, medium or high. - Install: `npx shadcn@latest add @0xui/gas-price` - Registry JSON: https://0xui.io/r/gas-price.json - Source: https://github.com/fimbul-lab/0xui/blob/main/registry/default/components/gas-price.tsx Shows the current gas price and refreshes it every 12 seconds. ## Installation ```bash npx shadcn@latest add @0xui/gas-price ``` ## Usage ```tsx import { GasPrice } from "@/components/gas-price"; ; ``` ## Examples ### With thresholds Normal gas varies a lot between chains: 20 gwei is cheap on mainnet and very expensive on Base. So there are no default thresholds. Pass the cut-offs that make sense for your chain. ```tsx ``` The tone is set as `data-tone` (`low`, `medium` or `high`) and is announced to screen readers. ## Props | Prop | Type | Default | Description | | --- | --- | --- | --- | | `chainId` | `number` | current chain | Chain to read. | | `refreshInterval` | `number \| false` | `12000` | Refresh interval in ms. `false` fetches once. | | `thresholds` | `{ low: number; high: number }` | — | Gwei cut-offs for the tone. | | `icon` | `ComponentType \| false` | `FuelIcon` | Custom icon, or `false` to hide it. | | `locale` | `string` | runtime locale | Number formatting locale. | --- # Address Source: https://0xui.io/components/address.md > ENS name or checksummed, truncated address, with copy and explorer link. - Install: `npx shadcn@latest add @0xui/address` - Registry JSON: https://0xui.io/r/address.json - Source: https://github.com/fimbul-lab/0xui/blob/main/registry/default/components/address.tsx Shows an address the way people expect: the ENS name when there is one, otherwise `0x1234…abcd` (checksummed). The full address is always available on hover and to screen readers. ## Installation ```bash npx shadcn@latest add @0xui/address ``` ENS names resolve on Ethereum mainnet, so mainnet must be in your wagmi config. If it isn't, or if the lookup fails, the component shows the address. ## Usage ```tsx import { Address } from "@/components/address";
; ``` ## Examples ### Without ENS, with explorer link ```tsx
``` ### Pill ```tsx
``` ### Headless ```tsx import { useAddressName } from "@/components/address"; const { name, checksummed, isLoading } = useAddressName(address); ``` ## Props | Prop | Type | Default | Description | | --- | --- | --- | --- | | `address` | `Address` | — | Address to show. Any casing works. | | `ens` | `boolean` | `true` | Resolve and show the ENS name. | | `name` | `string` | — | Name to show instead. Skips the ENS lookup. | | `variant` | `"inline" \| "pill"` | `"inline"` | Inline text or a bordered chip. | | `copyable` | `boolean` | `true` | Show a copy button. | | `explorer` | `boolean` | `false` | Link to the address on the current chain's explorer. | | `truncate` | `{ start?: number; end?: number }` | `{ start: 6, end: 4 }` | Characters kept when truncating. | --- # Address Input Source: https://0xui.io/components/address-input.md > Recipient field that takes an address or ENS name, resolves names, and catches checksum typos. - Install: `npx shadcn@latest add @0xui/address-input` - Registry JSON: https://0xui.io/r/address-input.json - Source: https://github.com/fimbul-lab/0xui/blob/main/registry/default/components/address-input.tsx Type or paste an address or an ENS name. Names resolve on mainnet once typing pauses, with the avatar and resolved address shown. Mixed-case addresses must match their checksum, which catches most single-character typos. Problems show after the field loses focus, not while typing. ## Installation ```bash npx shadcn@latest add @0xui/address-input ``` ## Usage ```tsx import { AddressInput } from "@/components/address-input"; const [text, setText] = useState(""); const [recipient, setRecipient] = useState
(); setRecipient(state.address)} />; ``` Always send to `state.address`, never to the raw text. It is `undefined` until the input is a valid address or a resolved name. ## Private addresses With `shielded`, the field also accepts a private `0zk…` address, for a recipient inside a private balance. It is checked by length and by its own checksum, so one wrong character is caught. The result is in `state.shieldedAddress`, and `state.address` stays `undefined`. ```tsx setRecipient(state.shieldedAddress ?? state.address)} /> ``` A private address is never sent to an ENS resolver or any other lookup. Without `shielded`, a pasted `0zk` address is turned down with "Private (0zk) addresses can't be used here." The format is Railgun's: `0zk`, 127 characters, bech32m. `isShieldedAddress` in `lib/0xui-utils` is the same check on its own. ## States `data-phase` on the root holds the current state. | Phase | Meaning | | --- | --- | | `empty` | Nothing typed. | | `incomplete` | Not a full address or name yet. Reported after blur. | | `resolving` | Looking up an ENS name. | | `valid` | `state.address` is set. For names, the resolved address is shown under the field. For addresses, the ENS name is shown. | | `invalid` | Bad checksum, too long, or not a valid name. Reported after blur. | | `not-found` | The name has no address. Reported right away. | ## Props Also accepts `` props. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `value` | `string` | — | Text in the field. | | `onValueChange` | `(value) => void` | — | Called on every change. | | `onResolve` | `(state) => void` | — | Called when validation settles on a new result. | | `label` | `string` | `"Recipient"` | Accessible label. | | `showPaste` | `boolean` | `true` | Paste button while empty. | | `shielded` | `boolean` | `false` | Also accept private `0zk…` addresses. | Headless: `useAddressInput(value, { shielded })` returns the same state. --- # Address Avatar Source: https://0xui.io/components/address-avatar.md > ENS avatar, or a deterministic gradient for any address. - Install: `npx shadcn@latest add @0xui/address-avatar` - Registry JSON: https://0xui.io/r/address-avatar.json - Source: https://github.com/fimbul-lab/0xui/blob/main/registry/default/components/address-avatar.tsx Shows the ENS avatar when the address has one. Otherwise it shows a gradient derived from the address, so the same address always looks the same. ## Installation ```bash npx shadcn@latest add @0xui/address-avatar ``` ENS avatars resolve on Ethereum mainnet, so mainnet must be in your wagmi config. ## Usage ```tsx import { AddressAvatar } from "@/components/address-avatar"; ; ``` The avatar is decorative (`aria-hidden`). Put the name or address next to it as text. ### Headless ```tsx import { useAddressAvatar, addressGradient } from "@/components/address-avatar"; const { name, avatar } = useAddressAvatar(address); const background = addressGradient(address); // CSS gradient string ``` ## Props | Prop | Type | Default | Description | | --- | --- | --- | --- | | `address` | `Address` | — | Address to show. | | `ens` | `boolean` | `true` | Look up the ENS avatar. | | `src` | `string` | — | Image URL to use instead of the ENS avatar. | | `size` | `number` | `24` | Diameter in px. | | `className` | `string` | — | Extra classes on the root. | --- # ENS Profile Source: https://0xui.io/components/ens-profile.md > Profile card for an ENS name or address. Avatar, name, bio and links. - Install: `npx shadcn@latest add @0xui/ens-profile` - Registry JSON: https://0xui.io/r/ens-profile.json - Source: https://github.com/fimbul-lab/0xui/blob/main/registry/default/components/ens-profile.tsx Avatar, name, address with copy, bio, and links from the name's text records (website, X, GitHub, email). ## Installation ```bash npx shadcn@latest add @0xui/ens-profile ``` ## Usage ```tsx import { EnsProfile } from "@/components/ens-profile"; ; // Or by address: uses its primary name ; ``` ENS lives on Ethereum mainnet, so mainnet must be in your wagmi config. Pass `records` to read other text records. Unknown keys are fetched and returned by `useEnsProfile`, but not rendered. ## States | `data-phase` | Meaning | | --- | --- | | `loading` | A skeleton measured from the avatar, name and address. | | `ready` | Profile shown. | | `not-found` | The name has no address, or the address has no primary name. | --- # Explorer Link Source: https://0xui.io/components/explorer-link.md > Link to an address, transaction or block on the chain's block explorer. - Install: `npx shadcn@latest add @0xui/explorer-link` - Registry JSON: https://0xui.io/r/explorer-link.json - Source: https://github.com/fimbul-lab/0xui/blob/main/registry/default/components/explorer-link.tsx Builds the URL from `chain.blockExplorers` in your wagmi config, so it works on every chain you configure. Nothing is hardcoded. ## Installation ```bash npx shadcn@latest add @0xui/explorer-link ``` ## Usage Pass exactly one of `address`, `tx` or `block`. ```tsx import { ExplorerLink } from "@/components/explorer-link"; ; ``` Uses the current chain unless you pass `chainId`. ## Examples ### Custom text and chain ```tsx Block 21,000,000 on Base ``` ### Headless ```tsx import { useExplorerLink } from "@/components/explorer-link"; const { href, explorerName } = useExplorerLink({ address }, chainId); ``` ## Behavior - Opens in a new tab with `rel="noopener noreferrer"`. Screen readers hear "(opens in a new tab)". - If the chain has no explorer, the children render as plain text with no link. ## Props Also accepts all `` props except `href`. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `address` / `tx` / `block` | `string` / `string` / `bigint \| number` | — | What to link to. Pass one. | | `chainId` | `number` | current chain | Chain whose explorer to use. | | `children` | `ReactNode` | `"View on "` | Link text. | | `icon` | `ComponentType \| false` | `ExternalLinkIcon` | Custom icon, or `false` to hide it. | --- # Token Input Source: https://0xui.io/components/token-input.md > The swap panel. Amount, token picker, fiat value, balance with Max, insufficient-balance state. - Install: `npx shadcn@latest add @0xui/token-input` - Registry JSON: https://0xui.io/r/token-input.json - Source: https://github.com/fimbul-lab/0xui/blob/main/registry/default/components/token-input.tsx [Amount Input](https://0xui.io/components/amount-input.md) and [Token Select](https://0xui.io/components/token-select.md) combined into the panel every swap and send form uses. It reads the connected account's balance of the chosen token, offers Max, and flags amounts above the balance. Tokens use the [token list standard](https://0xui.io/getting-started/token-lists.md). The demo uses Uniswap's default list, loaded live with `useTokenList`. ## Installation ```bash npx shadcn@latest add @0xui/token-input ``` ## Usage ```tsx import { TokenInput } from "@/components/token-input"; setValue(next)} token={token} onTokenChange={setToken} tokens={tokens} price={prices[token.symbol]} />; ``` Use `insufficient` to block the action, and name the reason on the button: ```tsx ``` ### "You receive" panel ```tsx {}} token={out} readOnly checkBalance={false} /> ``` ## Props | Prop | Type | Default | Description | | --- | --- | --- | --- | | `label` | `ReactNode` | — | Label above the panel. | | `value` | `string` | — | Decimal string. | | `onValueChange` | `(value, { amount, insufficient, balance }) => void` | — | Called on change. | | `token` | `Token` | — | Selected token. | | `onTokenChange` / `tokens` | — | — | Pass both to make the token pickable. | | `popular` | `string[]` | — | Quick picks in the picker. | | `price` / `currency` | `number` / `string` | — / `"USD"` | Fiat line. | | `prices` | `Record` | — | Fiat line for any selected token, and value-sorted holdings in the picker. | | `checkBalance` | `boolean` | `true` | Read the balance, offer Max, flag insufficient amounts. | | `readOnly` | `boolean` | `false` | For quoted outputs. | --- # Token Select Source: https://0xui.io/components/token-select.md > Searchable token picker with recent and popular tokens and the user's balances. - Install: `npx shadcn@latest add @0xui/token-select` - Registry JSON: https://0xui.io/r/token-select.json - Source: https://github.com/fimbul-lab/0xui/blob/main/registry/default/components/token-select.tsx A token pill that opens a picker. It has search by symbol, name or pasted address, quick picks (your recent tokens, then `popular`), and the full list with tokens you hold sorted first. Arrow keys move between the search field and the rows. The demo loads [Uniswap's default token list](https://tokens.uniswap.org) live. ## Installation ```bash npx shadcn@latest add @0xui/token-select ``` ## Usage Tokens use the [token list standard](https://0xui.io/getting-started/token-lists.md), the format of Uniswap's lists. Load one with `useTokenList`: ```tsx import { TokenSelect, type Token } from "@/components/token-select"; import { useTokenList } from "@/hooks/use-token-list"; import { UNISWAP_DEFAULT_LIST } from "@/lib/token-list"; const { tokens, isLoading } = useTokenList(UNISWAP_DEFAULT_LIST); const [token, setToken] = useState(); ; ``` Only tokens on `chainId` (the current chain by default) are listed. `useTokenList` adds the native currency (ETH) first, since lists don't include it, and takes an `allowlist` or `blocklist` to control which tokens appear. The list is paged, 50 rows at a time (`pageSize`): more load as the user scrolls, or with "Show more". Below 640px the picker opens as a bottom drawer. Set `mode` to force a dialog or a drawer. See [Responsive Dialog](https://0xui.io/components/responsive-dialog.md). > **Tip: In production** > > Balances are read over RPC by default: fine for prototypes, but heavy for long lists. With an [index of the chain](https://0xui.io/getting-started/indexed-data.md), pass `balances` and nothing is read over RPC: > > ```tsx > > ``` ### While the list loads Pass `isLoading` and the picker shows skeleton rows under the tokens it already has, which is usually just the native currency. This demo's list never arrives: ### Your own trigger ```tsx ``` ### Headless `filterTokens(tokens, query)` is the search, and `useTokenBalances(tokens)` reads every balance in one batch. ## Props Also accepts shadcn `Button` props for the trigger. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `tokens` | `Token[]` | — | Token list. | | `value` | `Token` | — | Selected token. | | `onValueChange` | `(token) => void` | — | Called on pick. The dialog closes itself. | | `chainId` | `number` | current chain | Chain to list. | | `popular` | `string[]` | `[]` | Symbols or addresses for quick picks. | | `showBalances` | `boolean` | `true` | Read and show the connected account's balances. | | `prices` | `Record` | — | Sort held tokens by value. Without prices, held tokens keep list order: raw amounts aren't comparable across tokens. | | `isLoading` | `boolean` | `false` | The list is still downloading. Shows skeleton rows, and "Loading tokens…" for screen readers. | | `pageSize` | `number` | `50` | Rows per page. More load on scroll or with "Show more". | | `balances` | `Record` | — | Balances from your own source. Skips RPC reads. | | `mode` | `"auto" \| "dialog" \| "drawer"` | `"auto"` | Bottom drawer on small screens, dialog otherwise. Or force one. | | `placeholder` | `string` | `"Select token"` | Trigger text with nothing selected. | | `title` | `ReactNode` | `"Select a token"` | Picker title. | Recent picks are kept in `localStorage` per chain (4 max). If storage is blocked, they're simply not saved. --- # Amount Input Source: https://0xui.io/components/amount-input.md > Large decimal input for token amounts. String state, decimal clamping, lenient paste, Max. - Install: `npx shadcn@latest add @0xui/amount-input` - Registry JSON: https://0xui.io/r/amount-input.json - Source: https://github.com/fimbul-lab/0xui/blob/main/registry/default/components/amount-input.tsx The big borderless amount field from swap UIs. It keeps the value as a string, so precision is never lost to floats. It refuses invalid keystrokes and digits past the token's decimals, and cleans up pasted amounts like `$1,000.50`. ## Installation ```bash npx shadcn@latest add @0xui/amount-input ``` ## Usage ```tsx import { AmountInput } from "@/components/amount-input"; const [value, setValue] = useState(""); setValue(next)} decimals={6} max={balance} />; ``` `amount` is the parsed `bigint`, ready for a contract call. It is `undefined` while the field is empty. ## Input rules | User does | Result | | --- | --- | | Types `1,5` | `1.5`. A comma is treated as the decimal point. | | Types `.5` | `0.5` | | Types letters, `-` or `e` | The keystroke is ignored. | | Types a 7th decimal on a 6-decimal token | The keystroke is ignored. | | Pastes `$1,000.50` or `1.000,50 USDC` | `1000.5` | It is `type="text"` with `inputMode="decimal"`, never `type="number"`. Number inputs silently round large values and reject commas. ## Props Also accepts `` props. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `value` | `string` | — | Decimal string. | | `onValueChange` | `(value, { amount, exceedsMax }) => void` | — | Called on every accepted change. | | `decimals` | `number` | — | Token decimals. | | `max` | `bigint` | — | Enables Max and the over-max state (`aria-invalid`). | | `showMax` | `boolean` | `true` | Show the Max button when `max` is set. | | `hint` | `ReactNode` | — | Line under the amount, e.g. a fiat value. | | `label` | `string` | `"Amount"` | Accessible label. | Pure helpers: `sanitizeAmountInput(raw, decimals)` and `getAmountState(value, decimals, max?)`. --- # Balance Source: https://0xui.io/components/balance.md > 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 ; ``` ## Examples ### ERC-20 Pass the token contract. Balance, decimals and symbol are read in one batched call. ```tsx ``` ### 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. | --- # Token Amount Source: https://0xui.io/components/token-amount.md > Formats bigint token amounts without losing precision. - Install: `npx shadcn@latest add @0xui/token-amount` - Registry JSON: https://0xui.io/r/token-amount.json - Source: https://github.com/fimbul-lab/0xui/blob/main/registry/default/components/token-amount.tsx Formats a raw `bigint` amount for display. Precision is never lost to floating point, and amounts always round toward zero, so a balance never looks larger than it is. Hover to see the exact amount. ## Installation ```bash npx shadcn@latest add @0xui/token-amount ``` ## Usage ```tsx import { TokenAmount } from "@/components/token-amount"; ; ``` ## Examples ### With fiat value 0xui doesn't fetch prices. Pass your own. ```tsx ``` ### Compact ```tsx ``` ### Dust Non-zero amounts too small to show render as a bound instead of a misleading `0`. ## Props | Prop | Type | Default | Description | | --- | --- | --- | --- | | `value` | `bigint` | — | Amount in the token's smallest unit. | | `decimals` | `number` | — | Token decimals. | | `symbol` | `string` | — | Shown after the amount. | | `maxDecimals` | `number` | `4` | Maximum fraction digits. | | `compact` | `boolean` | `false` | Compact notation, e.g. `1.2M`. | | `price` | `number` | — | Price of one token. Adds a fiat line. | | `currency` | `string` | `"USD"` | ISO 4217 currency for the fiat value. | | `locale` | `string` | runtime locale | Number formatting locale. | | `animate` | `boolean` | `false` | Morph the amount and fiat value when they change, with [Morph Text](https://0xui.io/components/morph-text.md). Leave off in long lists. | --- # Token Icon Source: https://0xui.io/components/token-icon.md > Token logo with fallbacks and an optional chain badge. - Install: `npx shadcn@latest add @0xui/token-icon` - Registry JSON: https://0xui.io/r/token-icon.json - Source: https://github.com/fimbul-lab/0xui/blob/main/registry/default/components/token-icon.tsx Tries three sources in order: your `src` URL (a token list's `logoURI`; `ipfs://` works), the built-in icon for the symbol, then the symbol's first two letters. List logos go dead often, so each step falls through to the next. ## Installation ```bash npx shadcn@latest add @0xui/token-icon ``` ## Usage ```tsx import { TokenIcon } from "@/components/token-icon"; ; // With a token list ; ``` ## Examples ### With chain badge The same token on different chains is easy to mix up. `chainId` adds the chain's logo in the corner. ```tsx ``` ## Props | Prop | Type | Default | Description | | --- | --- | --- | --- | | `symbol` | `string` | — | Token symbol. Used for the built-in icon, the fallback and the accessible label. | | `src` | `string` | — | Logo URL, e.g. `token.logoURI`. Takes priority over the built-in icon. | | `gateway` | `string` | `https://ipfs.io/ipfs/` | IPFS gateway for `ipfs://` logos. | | `chainId` | `number` | — | Show this chain's logo as a corner badge. | | `size` | `number` | `24` | Diameter in px. | | `variant` | `"background" \| "branded" \| "mono"` | `"branded"` | Style of the built-in icons. | --- # Add Token Source: https://0xui.io/components/add-token.md > Button that asks the wallet to track a token, e.g. "Add USDC to wallet". - Install: `npx shadcn@latest add @0xui/add-token` - Registry JSON: https://0xui.io/r/add-token.json - Source: https://github.com/fimbul-lab/0xui/blob/main/registry/default/components/add-token.tsx Asks the wallet to track an ERC-20 ([EIP-747](https://eips.ethereum.org/EIPS/eip-747)). Useful after a swap or bridge into a token the wallet doesn't list by default. Renders nothing when no wallet is connected. ## Installation ```bash npx shadcn@latest add @0xui/add-token ``` ## Usage ```tsx import { AddToken } from "@/components/add-token"; ; ``` ## States | `data-phase` | What the user sees | | --- | --- | | `idle` | "Add USDC to wallet" | | `adding` | Spinner, "Confirm in your wallet." | | `added` | Check, "USDC added" (disabled) | | `cancelled` | "Cancelled in wallet." Not an error. | | `error` | The wallet doesn't support adding tokens, or failed. | ## Props Also accepts shadcn `Button` props. | Prop | Type | Description | | --- | --- | --- | | `token` | `{ address, symbol, decimals, logoURI? }` | Token to add. Wallets show `logoURI` as its icon. | | `children` | `ReactNode` | Label. Defaults to "Add <symbol> to wallet". | --- # NFT Card Source: https://0xui.io/components/nft-card.md > Image, name and collection for an ERC-721 or ERC-1155 token, from its on-chain metadata. - Install: `npx shadcn@latest add @0xui/nft-card` - Registry JSON: https://0xui.io/r/nft-card.json - Source: https://github.com/fimbul-lab/0xui/blob/main/registry/default/components/nft-card.tsx Reads `tokenURI` (ERC-721) or `uri` (ERC-1155) and fetches the metadata. Handles IPFS, Arweave and inline `data:` metadata. The third card below is a token that doesn't exist. ## Installation ```bash npx shadcn@latest add @0xui/nft-card ``` ## Usage ```tsx import { NftCard } from "@/components/nft-card"; ; ``` ### Traits ```tsx ``` ## IPFS `ipfs://` links go through `https://ipfs.io/ipfs/` by default. The public gateway is slow and rate-limited, so use your own in production: ```tsx ``` ## States | `data-phase` | What the user sees | | --- | --- | | `loading` | A skeleton measured from the card's own layout. | | `ready` | Image, name, collection and id. | | `not-found` | "Token not found": no `tokenURI`/`uri`, so it's not an NFT or doesn't exist. | | `metadata-error` | "Metadata unavailable": the token exists, but its metadata host failed. Usually a rate-limited public IPFS gateway. | Helpers: `useNft`, `fetchNftMetadata`, `resolveUri` and `expandTokenUri` (ERC-1155 `{id}` substitution). --- # Transaction Button Source: https://0xui.io/components/transaction-button.md > Sends a transaction and shows every step on the button. Connect, switch network, confirm, pending, done. - Install: `npx shadcn@latest add @0xui/transaction-button` - Registry JSON: https://0xui.io/r/transaction-button.json - Source: https://github.com/fimbul-lab/0xui/blob/main/registry/default/components/transaction-button.tsx The button carries the whole flow. Disconnected users get the wallet picker. On the wrong network it offers to switch. Then it walks through confirm in wallet, pending and done, with a status line for each step. Connect the **Demo Wallet** to try it. Demo transactions get a fake hash and "mine" after 3 seconds. Nothing is broadcast. ## Installation ```bash npx shadcn@latest add @0xui/transaction-button ``` ## Usage Send ETH: ```tsx import { TransactionButton } from "@/components/transaction-button"; Send 0.01 ETH ; ``` Call a contract: ```tsx refetchAllowance()} > Approve ``` Always pass `chainId`. The button then makes sure the wallet is on that chain before sending. ## Examples ### Wrong network The label says exactly what clicking does: "Switch to Base". Once the switch is done, the button returns to its normal label. ### Name the blocker Don't just disable the button. Say why, so users know what to fix. ```tsx ``` ### Reverted ### Simulate first With `simulate`, the button dry-runs the transaction from the connected account before anyone clicks. If it would revert, the button is disabled and the contract's revert reason is shown, so the wallet never opens on a transaction that will fail. This demo tries to send a billion USDC from the Demo Wallet. The check runs against mainnet. ```tsx Send ``` The simulation runs once a wallet is connected on the right network and `disabledReason` is clear, and again after each transaction. Use `disabledReason` for what your form already knows, such as an empty amount, and `simulate` for what only the chain knows. It is a check, not a guarantee: state can change between the simulation and the block the transaction lands in. ### Headless ```tsx import { useTransactionFlow } from "@/components/transaction-button"; const flow = useTransactionFlow({ chainId: 1 }); flow.execute({ transaction: { to, value } }); // flow.phase, flow.hash, flow.receipt, flow.error, flow.wrongChain, flow.switchToTarget() ``` `useTransactionSimulation({ contract, chainId })` runs the same dry run on its own. It returns `status` (`idle`, `checking`, `ok` or `failed`) and the revert `reason`. ## States `data-phase` on the root holds the current state, also exported as `TxPhase`. | `data-phase` | Button | Status line | | --- | --- | --- | | `idle` | Your label, or "Connect wallet" / "Switch to X" | — | | `idle`, with `simulate` | "Checking…", then your label or "Transaction will fail" | Alert with the revert reason when it would fail. | | `switching` | Spinner, "Switching network…" | Approve the network switch in your wallet. | | `confirming` | Spinner, "Confirm in wallet…" | Confirm the transaction in your wallet. | | `pending` | Spinner, "Pending…" | Transaction submitted. Waiting for confirmation… | | `success` | Check, `successLabel` | Transaction confirmed. Returns to idle after `resetAfter`. | | `reverted` | Your label (retry) | Alert: transaction reverted. | | `cancelled` | Your label | Cancelled in wallet. Not an error, and `onError` isn't called. | | `error` | Your label (retry) | Alert with the wallet or RPC message. | ## Props Also accepts shadcn `Button` props. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `transaction` | `{ to, value?, data? }` | — | Plain transaction. Pass this or `contract`. | | `contract` | `{ address, abi, functionName, args?, value? }` | — | Contract call. | | `chainId` | `number` | current chain | Chain the transaction must run on. | | `confirmations` | `number` | `1` | Confirmations before success. | | `disabledReason` | `string` | — | Disable and show this text. | | `simulate` | `boolean` | `false` | Dry-run first. Disable and show the revert reason when it would fail. | | `children` | `ReactNode` | `"Submit"` | Label. | | `successLabel` | `ReactNode` | `"Done"` | Label after success. | | `resetAfter` | `number \| false` | `4000` | Back to idle after success, in ms. | | `hideStatus` | `boolean` | `false` | Hide the status line. | | `agentConfirm` | `string \| false` | label + what it does | Sets `data-agent-confirm`, so browser agents ask a person first. `false` drops it. | | `onSubmitted` | `(hash) => void` | — | Wallet returned a hash. | | `onSuccess` | `(receipt) => void` | — | Mined successfully. | | `onError` | `(error) => void` | — | Failed or reverted. Not called on cancel. | --- # Approve Button Source: https://0xui.io/components/approve-button.md > ERC-20 approval gate. Shows "Approve" until the allowance covers the amount, then your action. - Install: `npx shadcn@latest add @0xui/approve-button` - Registry JSON: https://0xui.io/r/approve-button.json - Source: https://github.com/fimbul-lab/0xui/blob/main/registry/default/components/approve-button.tsx Wrap the action that spends a token. While the allowance is too low it shows "Approve USDC" as a [Transaction Button](https://0xui.io/components/transaction-button.md). Once the approval is mined, it renders your action instead. If the allowance already covers the amount, it skips straight to the action. Connect the **Demo Wallet** to try it. ## Installation ```bash npx shadcn@latest add @0xui/approve-button ``` ## Usage ```tsx import { ApproveButton } from "@/components/approve-button"; Swap ; ``` ## Exact or unlimited By default it approves exactly `amount`. That's safest: the spender can't move more than this action needs. `unlimited` approves the maximum, which saves future approvals but lets the spender move all of the token. If you offer it, let the user choose. ```tsx ``` ### Tokens that need a reset Some tokens refuse to change a non-zero allowance to another non-zero value. USDT on mainnet is the well-known one. When such a token has a leftover allowance that is too low, the button first shows "Reset USDT approval", which sets it to `0`, and then "Approve USDT". That is two transactions. Mainnet USDT is detected by address. For any other token that behaves this way, pass `resetFirst`: ```tsx {action} ``` ## Props Also accepts [Transaction Button](https://0xui.io/components/transaction-button.md) props such as `onSuccess` and `variant`. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `token` | `{ address, symbol }` | — | Token to approve. | | `spender` | `Address` | — | Contract that will spend it. | | `amount` | `bigint` | — | Amount the action needs. | | `chainId` | `number` | — | Chain the token is on. | | `unlimited` | `boolean` | `false` | Approve the maximum. | | `resetFirst` | `boolean` | `true` for mainnet USDT | Set a leftover allowance to `0` before raising it. | | `children` | `ReactNode` | — | Shown once approved. | Headless: `useAllowance({ token, spender })`. --- # Batch Transaction Source: https://0xui.io/components/batch-transaction.md > Several calls as one action. One wallet prompt with EIP-5792, step by step otherwise. - Install: `npx shadcn@latest add @0xui/batch-transaction` - Registry JSON: https://0xui.io/r/batch-transaction.json - Source: https://github.com/fimbul-lab/0xui/blob/main/registry/default/components/batch-transaction.tsx Approve-and-swap without two prompts. When the wallet supports atomic batches ([EIP-5792](https://eips.ethereum.org/EIPS/eip-5792)), like Coinbase Smart Wallet and most smart accounts, every call goes out in **one prompt** and lands together. Other wallets get the same calls one by one, with a step list showing progress. Connect the **Demo Wallet**. It acts like a smart account that supports batching. ## Installation ```bash npx shadcn@latest add @0xui/batch-transaction ``` ## Usage ```tsx import { BatchTransaction } from "@/components/batch-transaction"; Approve and swap ; ``` ## Modes | `mode` | Behavior | | --- | --- | | `"auto"` (default) | Atomic if the wallet reports `atomic` support on the chain, otherwise sequential. | | `"atomic"` | Always `wallet_sendCalls`. The wallet may reject it if it can't batch. | | `"sequential"` | One transaction per call, each waiting to be mined. Stops at the first revert or cancel. | Sequential, for comparison: Atomic batches are all-or-nothing: if one call reverts, none take effect. Sequential calls are not. A revert in step 2 leaves step 1 in place, so order your calls so that's safe (approvals first). ## States `data-phase` holds the current state, and `data-atomic` is set when batching. Phases: `idle`, `switching`, `confirming`, `pending`, `success`, `reverted`, `cancelled`, `error`. Sequential labels count steps: "Confirm 2 of 3 in wallet…". Headless: `useBatchTransaction({ calls, chainId, mode })`. --- # Transaction Status Source: https://0xui.io/components/transaction-status.md > Inline card that follows a transaction from submitted to confirmed. - Install: `npx shadcn@latest add @0xui/transaction-status` - Registry JSON: https://0xui.io/r/transaction-status.json - Source: https://github.com/fimbul-lab/0xui/blob/main/registry/default/components/transaction-status.tsx Follows one transaction hash. Shows what the transaction does, a list of steps, the hash with copy, and an explorer link. Never a bare spinner. Connect the **Demo Wallet** and send to see it. The demo hash isn't on chain, so its explorer link won't resolve. ## Installation ```bash npx shadcn@latest add @0xui/transaction-status ``` ## Usage ```tsx import { TransactionStatus } from "@/components/transaction-status"; Send 0.01 ETH to vitalik.eth ; ``` Pair it with [Transaction Button](https://0xui.io/components/transaction-button.md) through `onSubmitted`: ```tsx const [hash, setHash] = useState(); Send {hash && Send 0.01 ETH} ``` ### More confirmations ```tsx ``` This adds a live "3 of 12 confirmations" step. ### Headless ```tsx import { useTransactionStatus } from "@/components/transaction-status"; const { phase, receipt, confirmations, required } = useTransactionStatus({ hash }); ``` ## States | `data-phase` | Heading | | --- | --- | | `pending` | Transaction pending | | `confirming` | Confirming (mined, waiting for more confirmations) | | `confirmed` | Transaction confirmed | | `reverted` | Transaction reverted | | `error` | Couldn't track transaction | ## Props | Prop | Type | Default | Description | | --- | --- | --- | --- | | `hash` | `Hash` | — | Transaction to follow. | | `chainId` | `number` | current chain | Chain it was sent on. | | `confirmations` | `number` | `1` | Required confirmations. | | `title` | `ReactNode` | per phase | Heading override. | | `children` | `ReactNode` | — | What the transaction does. | | `onConfirmed` | `(receipt) => void` | — | Called once on confirmation. | --- # Transaction Toast Source: https://0xui.io/components/transaction-toast.md > Follow a transaction in a toast, from pending to confirmed or reverted. - Install: `npx shadcn@latest add @0xui/transaction-toast` - Registry JSON: https://0xui.io/r/transaction-toast.json - Source: https://github.com/fimbul-lab/0xui/blob/main/registry/default/components/transaction-toast.tsx Follow a transaction without keeping its UI on screen. One toast goes from "Transaction pending" to "Transaction confirmed" or "Transaction reverted", with a link to the explorer. Built on [Sonner](https://sonner.emilkowal.ski). Connect the **Demo Wallet** and send to see it. ## Installation ```bash npx shadcn@latest add @0xui/transaction-toast ``` This also installs the shadcn `sonner` component. Mount its `` once, near the root of your app: ```tsx import { Toaster } from "@/components/ui/sonner"; ; ``` ## Usage ```tsx import { useTransactionToast } from "@/components/transaction-toast"; const toastTransaction = useTransactionToast(); toastTransaction(hash, { description: "Send 0.01 ETH" })} hideStatus > Send ; ``` It works with any hash, including ones from your own `writeContract` calls. ## Options | Option | Type | Description | | --- | --- | --- | | `chainId` | `number` | Chain the transaction is on. Defaults to the current chain. | | `description` | `ReactNode` | What the transaction does. Shown in every state. | | `titles` | `{ pending?, success?, reverted?, error? }` | Override the headings. | | `onConfirmed` | `(receipt) => void` | Called when mined successfully. | The pending toast stays until the transaction settles. The confirmed toast stays 6 seconds, and the reverted or error toast 10 seconds. --- # Transaction History Source: https://0xui.io/components/transaction-history.md > Transactions sent from your app, with live status. Stored in the browser. - Install: `npx shadcn@latest add @0xui/transaction-history` - Registry JSON: https://0xui.io/r/transaction-history.json - Source: https://github.com/fimbul-lab/0xui/blob/main/registry/default/components/transaction-history.tsx A list of transactions sent from your app, newest first. Pending ones update live, and settled ones keep their result. It's stored in this browser (`localStorage`), so it's per device and survives reloads. Other tabs update too. Connect the **Demo Wallet** and send a couple. ## Installation ```bash npx shadcn@latest add @0xui/transaction-history ``` ## Usage Record transactions wherever you send them, then render the list anywhere: ```tsx import { TransactionHistory, recordTransaction } from "@/components/transaction-history"; recordTransaction({ hash, chainId: 1, from: address, description: "Send 0.1 ETH" }) } /> ``` By default, the list shows the connected account's transactions (entries recorded with `from`). Pass `from={null}` to show all. `recordTransaction` works outside React too. It keeps the 50 most recent. > **Tip: In production** > > Local history only knows what this browser recorded. For full history across devices and apps, we recommend an [index of the chain](https://0xui.io/getting-started/indexed-data.md), either your own (Postgres + ClickHouse) or a service like Goldsky. Pass its rows to `transactions`. Pending ones still update live: > > ```tsx > > ``` ## Props | Prop | Type | Default | Description | | --- | --- | --- | --- | | `from` | `Address \| null` | connected | Filter by sender. `null` shows all. | | `transactions` | `HistoryEntry[]` | — | Transactions from your own source instead of this browser's. | | `pageSize` | `number` | `10` | Rows per page, with "Show more". | | `clearable` | `boolean` | `true` | Show a Clear button. | | `title` | `ReactNode` | `"Recent transactions"` | Heading. | | `locale` | `string` | runtime locale | Locale for the relative times. | Also exported: `useTransactionHistory`, `updateTransaction`, `clearTransactionHistory`. --- # Contract Form Source: https://0xui.io/components/contract-form.md > Read and write forms for any contract, generated from its ABI. - Install: `npx shadcn@latest add @0xui/contract-form` - Registry JSON: https://0xui.io/r/contract-form.json - Source: https://github.com/fimbul-lab/0xui/blob/main/registry/default/components/contract-form.tsx Point it at a contract and an ABI and get a card per function: typed inputs, **Read** for view functions, and a [Transaction Button](https://0xui.io/components/transaction-button.md) for writes. Useful for admin panels, debugging, and tools an agent builds on the fly. The demo is USDC on Ethereum. Reads are real. Writes go through the Demo Wallet and aren't broadcast. ## Installation ```bash npx shadcn@latest add @0xui/contract-form ``` ## Usage ```tsx import { ContractForm } from "@/components/contract-form"; ; // Just some functions, in this order ; // Only reads ; ``` Render one function with `ContractFunction`. ## Input rules | Solidity type | Enter | Checks | | --- | --- | --- | | `uint*` / `int*` | `1000` or `1_000` | Whole number, within the type's range | | `address` | `0x…` | Valid, and the checksum must match if mixed-case | | `bool` | select | — | | `bytes` / `bytesN` | `0x…` | Hex, exact length for `bytesN` | | `string` | text | — | | arrays, tuples | JSON: `["1", "2"]`, `{ "to": "0x…", "amount": "5" }` | Each element by its type | Payable functions get an ETH value field. The write button names the first field to fix, e.g. "Check amount". Pure helpers: `parseAbiInput(param, text)` and `formatAbiValue(value)`. --- # Event Feed Source: https://0xui.io/components/event-feed.md > Live list of a contract's events, newest first, each linked to its transaction. - Install: `npx shadcn@latest add @0xui/event-feed` - Registry JSON: https://0xui.io/r/event-feed.json - Source: https://github.com/fimbul-lab/0xui/blob/main/registry/default/components/event-feed.tsx Follow a contract's events as they happen: transfers, swaps, mints. New events appear at the top, each with its arguments and a link to the transaction. Screen readers hear new entries politely (`role="log"`). ## Installation ```bash npx shadcn@latest add @0xui/event-feed ``` ## Usage ```tsx import { EventFeed } from "@/components/event-feed"; ; ``` `args` filters on indexed arguments, so `{ to: address }` shows only incoming transfers. `historyBlocks` loads that many recent blocks first. Keep it small: public RPCs cap how many blocks one log request may cover. ### Custom rows ```tsx } /> ``` Headless: `useEventFeed(params)` returns `events`, newest first and deduplicated. > **Tip: In production** > > `historyBlocks` reads past events over RPC, and providers cap those ranges. For real history, we recommend an [index of the chain](https://0xui.io/getting-started/indexed-data.md), either your own (ClickHouse is built for event logs) or a service like Goldsky. Pass its events to `initialEvents`, and new events still stream in live: > > ```tsx > > ``` ## Props | Prop | Type | Default | Description | | --- | --- | --- | --- | | `address` | `Address` | — | Contract. | | `abi` | `Abi` | — | ABI with the event. | | `eventName` | `string` | all | Event to follow. | | `args` | `object` | — | Indexed-argument filter. | | `chainId` | `number` | current | Chain. | | `historyBlocks` | `number` | `0` | Recent blocks to load first. | | `max` | `number` | `20` | Events kept. | | `initialEvents` | `FeedEvent[]` | — | Past events from your own source. | | `renderEvent` | `(event) => ReactNode` | — | Custom row. | | `title` | `ReactNode` | `"Live events"` | Heading. `null` hides it. | --- # Copy Button Source: https://0xui.io/components/copy-button.md > Icon button that copies a value and confirms with a checkmark. - Install: `npx shadcn@latest add @0xui/copy-button` - Registry JSON: https://0xui.io/r/copy-button.json - Source: https://github.com/fimbul-lab/0xui/blob/main/registry/default/components/copy-button.tsx Copies a value to the clipboard. The icon turns into a checkmark for two seconds, and "Copied" is announced to screen readers. ## Installation ```bash npx shadcn@latest add @0xui/copy-button ``` ## Usage ```tsx import { CopyButton } from "@/components/copy-button"; ; ``` Always pass a specific `label`. It is the button's only accessible name. ## Examples ### Other button styles Accepts every shadcn `Button` prop, including `variant` and `size`. ```tsx ``` ## States | State | What the user sees | | --- | --- | | Idle | Copy icon. | | Copied | Checkmark for `timeout` ms, "Copied" announced. `data-copied` is set on the button. | | Clipboard blocked | Nothing changes and `onCopy` is not called. | ## Props Also accepts all shadcn `Button` props except `onClick` and `children`. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `value` | `string` | — | Text to copy. | | `label` | `string` | `"Copy"` | Accessible label and tooltip. | | `timeout` | `number` | `2000` | How long the copied state lasts, in ms. | | `onCopy` | `(value: string) => void` | — | Called after a successful copy. | | `copyIcon` | `ComponentType \| false` | `CopyIcon` | Custom icon, or `false` to hide it. | | `copiedIcon` | `ComponentType \| false` | `CheckIcon` | Custom icon, or `false` to hide it. | --- # Responsive Dialog Source: https://0xui.io/components/responsive-dialog.md > A dialog that becomes a bottom drawer on small screens. - Install: `npx shadcn@latest add @0xui/responsive-dialog` - Registry JSON: https://0xui.io/r/responsive-dialog.json - Source: https://github.com/fimbul-lab/0xui/blob/main/registry/default/components/responsive-dialog.tsx A centered dialog is out of thumb reach on a phone. This shell shows the same title and content as a dialog on larger screens and as a bottom drawer below 640px. The drawer has a handle and can be swiped away. It is what [Connect Wallet](https://0xui.io/components/connect-wallet.md) and [Token Select](https://0xui.io/components/token-select.md) open. Use it for your own pickers and small forms. Narrow the window below 640px to get the drawer. ## Installation ```bash npx shadcn@latest add @0xui/responsive-dialog ``` It installs the shadcn `dialog` and `drawer` primitives. ## Usage ```tsx import { ResponsiveDialog } from "@/components/responsive-dialog"; const [open, setOpen] = useState(false); {content} ; ``` `description` is read by screen readers and not shown. Write it for someone who can't see the content. ## Examples ### Force one `mode="drawer"` or `mode="dialog"` skips the media query. ```tsx ``` ### Another breakpoint ```tsx ``` ### Headless `useMediaQuery(query)` is the hook behind `auto`. It is false on the server and where `matchMedia` is missing, such as jsdom. ## Behavior | Case | What happens | | --- | --- | | Server render and first paint | Dialog. The drawer is chosen after hydration, while the dialog is still closed. | | The screen crosses the breakpoint while open | It stays open and switches. The content remounts, so lift state that must survive above it. | | Long content in the drawer | The content area scrolls. The drawer stops short of the top of the screen. | | `className` | Applies to the dialog panel only. The drawer is full width and sizes itself. | ## Props | Prop | Type | Default | Description | | --- | --- | --- | --- | | `open` / `onOpenChange` | — | — | Control it. | | `title` | `ReactNode` | — | Shown at the top. | | `description` | `ReactNode` | — | For screen readers. Not shown. | | `mode` | `"auto" \| "dialog" \| "drawer"` | `"auto"` | Pick by screen size, or force one. | | `drawerQuery` | `string` | `"(max-width: 639px)"` | Media query that picks the drawer in `auto` mode. | | `className` | `string` | — | Class for the dialog panel. | | `children` | `ReactNode` | — | Dialog content. | --- # Morph Text Source: https://0xui.io/components/morph-text.md > Text that morphs from the old value to the new one when it changes. - Install: `npx shadcn@latest add @0xui/morph-text` - Registry JSON: https://0xui.io/r/morph-text.json - Source: https://github.com/fimbul-lab/0xui/blob/main/registry/default/components/morph-text.tsx Animates a label when its text changes. Characters the old and new text share slide to their new place, and the rest fade. Built on [torph](https://github.com/lochie/torph). Click the button to step through a transaction's labels. ## Installation ```bash npx shadcn@latest add @0xui/morph-text ``` ## Usage ```tsx import { MorphText } from "@/components/morph-text"; ; ``` Keep one `MorphText` mounted and change its text. Swapping between two `MorphText` elements replaces the label without a morph. ## Examples ### Numbers Digits roll by place value, so only the places that changed move. Use `tabular-nums` on the parent to stop the width from shifting. ```tsx {blockNumber.toLocaleString()} ``` ## Where 0xui uses it | Component | What morphs | | --- | --- | | [Transaction Button](https://0xui.io/components/transaction-button.md), [Batch Transaction](https://0xui.io/components/batch-transaction.md), [Sign Message](https://0xui.io/components/sign-message.md), [Add Token](https://0xui.io/components/add-token.md) | The button label, across phases. This covers [Approve Button](https://0xui.io/components/approve-button.md), [Send](https://0xui.io/blocks/send.md) and [Swap](https://0xui.io/blocks/swap.md) too. | | [Contract Form](https://0xui.io/components/contract-form.md) | "Read" and "Reading…". | | [Chain Selector](https://0xui.io/components/chain-selector.md) | The current chain's name. | | [Block Number](https://0xui.io/components/block-number.md), [Gas Price](https://0xui.io/components/gas-price.md) | The live value. | | [Balance](https://0xui.io/components/balance.md), [Token Input](https://0xui.io/components/token-input.md) | The balance and the fiat value. | | [Swap](https://0xui.io/blocks/swap.md), [Portfolio](https://0xui.io/blocks/portfolio.md) | The rate, price impact and total value. | [Token Amount](https://0xui.io/components/token-amount.md) only morphs with `animate`, so long lists don't pay for it. ## Behavior | Case | What happens | | --- | --- | | Text and numbers, alone or mixed like `Approve {symbol}` | Joined into one label and morphed. | | Children that hold an element | Rendered as-is, with no animation. | | Screen readers | Read the plain text once. The animated characters are hidden from them. | | `prefers-reduced-motion` | The text changes without animating. | | No Web Animations API, as in jsdom | Plain text in a `span`, so tests can query the label. | The text never wraps: torph sets `white-space: nowrap`. Use it for short labels and values, not sentences. torph adds one `