Hooks
API reference for every Wyllet hook: useWyllet, useWylletButton, useWylletToast, useWylletActivity, useWylletAuth and more.
Wyllet exports nine hooks. All of them except useCopyToClipboard read Wyllet's context, so they must be called from a component rendered inside WylletProvider (which itself sits inside wagmi's WagmiProvider and react-query's QueryClientProvider). Calling one outside the provider throws an error that names WylletProvider.
import {
useCopyToClipboard,
useWalletOptions,
useWyllet,
useWylletActivity,
useWylletAuth,
useWylletButton,
useWylletChains,
useWylletToast,
useWylletTokens,
} from 'wyllet'useWyllet
Controls the Wyllet panel from anywhere in your app.
function useWyllet(): {
open(view?: PanelView, options?: OpenOptions): void
close(): void
openConnect(options?: OpenOptions): void
openAccount(options?: OpenOptions): void
openTab(tab: AccountTab, options?: OpenOptions): void
view: PanelView | null
isConnected: boolean
address: Address | undefined
chainId: number | undefined
authStatus: AuthStatus | undefined
}| Field | Type | Description |
|---|---|---|
open | (view?, options?) => void | Opens a view. Without a view it opens 'account' when connected and 'connect' otherwise. |
close | () => void | Closes the panel. |
openConnect | (options?) => void | Opens the connect view. |
openAccount | (options?) => void | Opens the account panel. |
openTab | (tab, options?) => void | Opens the account panel on a tab: 'tokens', 'activity' or 'networks'. |
view | PanelView | null | The open view ('connect' or 'account'), or null when closed. |
isConnected | boolean | true when wagmi reports a connected account. |
address | Address | undefined | The connected address. |
chainId | number | undefined | The connected chain id. |
authStatus | AuthStatus | undefined | Sign-in status for the connected account, or undefined when no auth adapter is set. |
OpenOptions has two optional fields: anchor (an Element the popover presentation anchors to) and tab (an AccountTab).
function Toolbar() {
const { openConnect, openTab, isConnected } = useWyllet()
return isConnected ? (
<button onClick={(e) => openTab('activity', { anchor: e.currentTarget })}>Activity</button>
) : (
<button onClick={() => openConnect()}>Connect</button>
)
}useWylletButton
Headless state for building your own trigger. It powers WylletButton. See WylletButton for a full walkthrough.
function useWylletButton(): WylletButtonState| Field | Type | Description |
|---|---|---|
mounted | boolean | false during server rendering and the first client render. Render a placeholder until it is true to avoid hydration mismatches. |
status | 'disconnected' | 'connecting' | 'reconnecting' | 'connected' | wagmi's connection status. |
account | object | undefined | Present when connected: address, displayName (ENS name or shortened address), ensName, and balance (formatted, symbol, value, decimals). |
chain | object | undefined | Present when connected: id, name, and unsupported (true when the wallet is on a chain your config does not include). |
authStatus | AuthStatus | undefined | undefined when no auth adapter is configured. |
open | (anchor?: Element | null) => void | Opens the connect view when disconnected or not yet signed in, otherwise the account panel. |
openConnect | (anchor?: Element | null) => void | Opens the connect view. |
openAccount | (anchor?: Element | null, tab?: AccountTab) => void | Opens the account panel, optionally on a tab. |
Pass the clicked element as anchor so the popover presentation can position itself next to it.
function MyButton() {
const { mounted, account, chain, open } = useWylletButton()
if (!mounted) return <button disabled>Connect</button>
return (
<button onClick={(e) => open(e.currentTarget)}>
{account ? `${account.displayName} on ${chain?.name}` : 'Connect'}
</button>
)
}useWylletToast
Returns the toast API. See Toasts.
function useWylletToast(): ToastApi| Member | Type | Description |
|---|---|---|
| call | (options: ToastOptions) => string | Shows a toast and returns its id. Pass an existing id to update that toast in place. |
success | (title, options?) => string | Shows a success toast. |
error | (title, options?) => string | Shows an error toast. |
loading | (title, options?) => string | Shows a loading toast. Loading toasts never auto-dismiss. |
update | (id: string, options: Partial<ToastOptions>) => void | Updates an existing toast. Does nothing if the id is unknown. |
dismiss | (id?: string) => void | Dismisses one toast, or all of them when called without an id. |
promise | (promise, messages) => Promise<T> | Shows a loading toast that becomes success or error when the promise settles. Returns the original result and rethrows on failure. |
ToastOptions fields: title (ReactNode), description, status ('info' | 'success' | 'error' | 'loading'), duration in milliseconds (Infinity keeps the toast open), action (label plus href or onClick) and id. Without a duration, error toasts stay for 7 seconds and other toasts for 4.5 seconds.
const toast = useWylletToast()
toast.success('Saved')
await toast.promise(bridge(), {
loading: 'Bridging…',
success: 'Bridged',
error: (e) => `Bridge failed: ${String(e)}`,
})useWylletActivity
The connected account's activity timeline, plus transaction tracking. See Activity and transactions.
function useWylletActivity(): {
activity: ActivityItem[]
addTransaction(tx: {
hash: Hash
description?: string
chainId?: number
account?: Address
toast?: boolean
}): boolean
log(entry: {
title: string
description?: string
status?: ActivityStatus
account?: Address
}): boolean
clearActivity(): void
}| Field | Type | Description |
|---|---|---|
activity | ActivityItem[] | Entries for the connected account, newest first. Empty when disconnected. |
addTransaction | (tx) => boolean | Adds a pending transaction, watches for its receipt and shows pending and confirmed toasts (set toast: false to skip them). Defaults to the connected account and chain. Returns false if no account or chain is known. |
log | (entry) => boolean | Adds a custom entry. status defaults to 'info'. Returns false if no account is known. |
clearActivity | () => void | Clears the connected account's entries. |
Activity is stored in localStorage (up to 50 entries per account). Transactions still pending when the page reloads are watched again if they are less than 24 hours old. A transaction that is not mined within 30 minutes stays pending rather than being marked as failed.
const { writeContractAsync } = useWriteContract()
const { addTransaction, log } = useWylletActivity()
const hash = await writeContractAsync({ /* ... */ })
addTransaction({ hash, description: 'Mint 1 NFT' })
log({ title: 'Staked 10 ETH', status: 'success' })useWylletAuth
Sign-In With Ethereum state. Requires the auth prop on WylletProvider. See Sign-In With Ethereum.
function useWylletAuth(): {
enabled: boolean
status: AuthStatus
signIn(options?: OpenOptions): void
signOut(): Promise<void>
}| Field | Type | Description |
|---|---|---|
enabled | boolean | true when an auth adapter is configured. |
status | 'loading' | 'unauthenticated' | 'authenticated' | Per connected account: a session for a different address reads as 'unauthenticated'. |
signIn | (options?) => void | Opens the panel at the sign-in step, connecting first if needed. |
signOut | () => Promise<void> | Clears the local session and calls your adapter's signOut. Errors from the adapter are swallowed. |
function Session() {
const { status, signIn, signOut } = useWylletAuth()
if (status === 'loading') return null
return status === 'authenticated' ? (
<button onClick={() => signOut()}>Sign out</button>
) : (
<button onClick={(e) => signIn({ anchor: e.currentTarget })}>Sign in</button>
)
}useWylletTokens
The token list for a chain: your configured tokens, plus tokens the user imported when allowTokenImport is on. See Tokens.
function useWylletTokens(chainId?: number): {
tokens: ListedToken[]
importToken(token: Token, chainId?: number): void
removeToken(address: string, chainId?: number): void
canImport: boolean
}| Field | Type | Description |
|---|---|---|
tokens | ListedToken[] | Configured tokens in list order, followed by imported ones. Imported tokens have custom: true. Empty when no chain id is known. |
importToken | (token, chainId?) => void | Saves a token for the user in this browser. Defaults to the hook's chain. |
removeToken | (address, chainId?) => void | Removes an imported token. Address matching is case-insensitive. |
canImport | boolean | The provider's allowTokenImport value. |
chainId defaults to the connected chain. Imported tokens are only included in tokens when allowTokenImport is true.
function TokenList() {
const { tokens } = useWylletTokens(8453)
return (
<ul>
{tokens.map((t) => (
<li key={t.address}>{t.symbol}</li>
))}
</ul>
)
}useWylletChains
Your configured chains, ordered by the provider's chainOrder. Chains not listed in chainOrder follow in config order. See Chains.
function useWylletChains(): { chains: Chain[] }const { chains } = useWylletChains()
// With chainOrder={[8453]}: Base first, then the rest of your configchainOrder only affects display. The default chain is still the first chain in your wagmi config.
useCopyToClipboard
Copies text and exposes a copied flag that resets after a delay. It does not need WylletProvider.
function useCopyToClipboard(resetMs?: number): {
copied: boolean
copy(text: string): Promise<boolean>
}| Field | Type | Description |
|---|---|---|
copied | boolean | true for resetMs milliseconds (default 1600) after a successful copy. |
copy | (text: string) => Promise<boolean> | Writes to navigator.clipboard. Resolves false if the clipboard is unavailable or the write fails. |
function CopyAddress({ address }: { address: string }) {
const { copied, copy } = useCopyToClipboard()
return <button onClick={() => copy(address)}>{copied ? 'Copied' : 'Copy'}</button>
}useWalletOptions
The wallet list Wyllet's connect view uses: your configured wallets merged with what is actually available in the browser. Use it to build a fully custom wallet picker.
function useWalletOptions(): {
groups: WalletGroup[]
all: WalletOption[]
walletConnectConnector?: Connector
}| Field | Type | Description |
|---|---|---|
groups | WalletGroup[] | Non-empty groups in order: 'installed' (detected or recently used), 'popular', and 'more' (wallets with featured: false). |
all | WalletOption[] | Every option, in the same order as the groups. |
walletConnectConnector | Connector | undefined | The WalletConnect connector, if your config has one. |
Each WalletOption has:
| Field | Type | Description |
|---|---|---|
wallet | Wallet | The wallet. Installed extensions use the icon they announce. |
connector | Connector | undefined | The connector used for a direct connection. |
installed | boolean | An EIP-6963 provider matching the wallet's rdns was announced. |
recent | boolean | The user connected with this wallet recently. |
action | 'connect' | 'walletConnect' | 'get' | What picking it does: connect directly, start WalletConnect, or show install links. |
Installed EIP-6963 wallets you did not list still appear in the 'installed' group. Wallets that can neither connect nor use WalletConnect, and have no downloadUrls, are left out.
import { useConnect } from 'wagmi'
function Picker() {
const { all } = useWalletOptions()
const { connect } = useConnect()
return all
.filter((o) => o.action === 'connect' && o.connector)
.map((o) => (
<button key={o.wallet.id} onClick={() => connect({ connector: o.connector! })}>
{o.wallet.name}
</button>
))
}