Getting started
Conventions
The rules every 0xui component follows, so once you know one you know them all.
Hook, parts, shell
Section titled “Hook, parts, shell”Each component has three layers, and all of them are exported:
- Hook: all wagmi calls and state. Use it alone to build your own UI.
- Parts: small presentational pieces that take plain props.
- Shell: the default composed component. Variants such as popover and dialog are thin shells over the same hook and parts.
variant,sizeandclassNameon the root.- Icon slots take a component, or
falseto hide the icon.disableIconshides all of them. - Overlays can be controlled or uncontrolled:
open,defaultOpen,onOpenChange. - Callbacks are named
onXand 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.
Agents
Section titled “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 also gives agents the wallet state directly.
Web3 rules
Section titled “Web3 rules”- Amounts are
bigintfrom end to end. Formatting goes through viemformatUnits/parseUnits, neverNumber(). - Amount inputs use text,
inputMode="decimal", nevertype="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
Section titled “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.
