Skip to content

Getting started

Conventions

The rules every 0xui component follows, so once you know one you know them all.

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

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:

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

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 also gives agents the wallet state directly.

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