# Wyllet documentation

> Wyllet is an open-source wallet connector for React dApps built on wagmi and viem. A connect button, account panel, tokens, activity, toasts and Sign-In With Ethereum, themed to match your app, with zero direct runtime dependencies (React, wagmi, viem and TanStack Query are peer dependencies).

---

# Introduction

> What Wyllet is, what it includes, and how it fits into a wagmi + viem dApp.

Source: https://wyllet.dev/docs/introduction

Wyllet is an open-source, MIT-licensed wallet connector for React dApps. It gives your app a connect button, a connect flow and an account panel, and it runs on top of the wagmi and viem setup your dApp already uses.

## What Wyllet is

Most dApps need the same things around a wallet: a way to pick and connect one, a place to see the connected account, a network switcher, and feedback while transactions confirm. Wyllet packages these into one system that you add with a provider and a button.

Wyllet does not replace wagmi. It reads connection state through wagmi hooks and connects wallets through wagmi connectors. Your own code keeps using `useConnection`, `useWriteContract`, `useBalance` and the rest of wagmi as before.

## What it includes

| Piece | What it does |
| --- | --- |
| Wallet Island | `<WylletButton>`, one button that is a call to action when disconnected and shows avatar, name, network badge and balance when connected. See [WylletButton](/docs/wyllet-button). |
| Panel presentations | The connect and account views open as a side `drawer` (the default), an anchored `popover` or a centered `modal`. Phones get a draggable bottom sheet. See [Presentations](/docs/presentations). |
| Connect flow | Installed wallets are detected through EIP-6963. Other wallets connect through WalletConnect with a QR code on desktop or an app link on phones. Arrow keys, Enter and number keys 1 to 9 pick a wallet, and recent wallets get a one-tap "Continue with" row. |
| Account panel | Address, copy, receive QR code, explorer link and disconnect, plus Tokens, Activity and Networks tabs. An optional generative identity card can replace the compact summary. See [Account panel](/docs/account-panel). |
| Chains and tokens in code | You define networks and tokens in code, so every user sees the same curated set. `popularChains`, `customChain()` and `withDefaultTokens()` help. See [Chains](/docs/chains) and [Tokens](/docs/tokens). |
| Activity | A per-account timeline of connects, network switches, sign-ins, tracked transactions and your own entries. See [Activity](/docs/activity). |
| Toasts | Themed, promise-aware notifications through `useWylletToast()`. See [Toasts](/docs/toasts). |
| Sign-In With Ethereum | Pass an auth adapter and a signature step becomes part of the connect flow. See [SIWE](/docs/siwe). |
| `<ConnectGate>` | Renders its children only when the user is connected, on a supported network and, if you use SIWE, signed in. See [ConnectGate](/docs/connect-gate). |
| Themes | Four presets (Obsidian, Porcelain, Aurora, Terminal), light and dark pairs, and every design token exposed as a `--wy-*` CSS variable. See [Theming](/docs/theming). |
| Burner wallet | `burnerWallet()` is an in-browser wallet for local development and demos. See [Wallets](/docs/wallets). |

## How it fits into a wagmi and viem dApp

A Wyllet app has three layers, from the outside in:

1. `<WagmiProvider>` with a wagmi config. You can create the config with Wyllet's `getDefaultConfig()`, which wires up wallet discovery, WalletConnect and your wallet list, or write it yourself with wagmi's `createConfig()`.
2. `<QueryClientProvider>` from `@tanstack/react-query`, which wagmi requires.
3. `<WylletProvider>`, which holds the theme, presentation and feature options, and renders the panel and toasts.

Inside the provider you render `<WylletButton />` wherever the connect button belongs, and use Wyllet hooks such as `useWyllet()` when you want to open the panel from your own UI.

```tsx
<WagmiProvider config={config}>
  <QueryClientProvider client={queryClient}>
    <WylletProvider>
      <WylletButton />
    </WylletProvider>
  </QueryClientProvider>
</WagmiProvider>
```

## Dependencies

Wyllet has no direct runtime dependencies. It uses only `react`, `react-dom`, `wagmi`, `viem` and `@tanstack/react-query`, which your dApp already has, and declares them as peer dependencies. The QR code encoder is built in.

WalletConnect support is opt-in. If you set a `walletConnectProjectId`, you install `@walletconnect/ethereum-provider` yourself, so you choose and pin its version.

Wyllet makes no network requests of its own, with one opt-in exception: when WalletConnect is enabled and a user opens **All wallets**, it loads the wallet list and logos from the WalletConnect registry. Set `appearance.walletDirectory` to `false` to turn that off. See [All wallets](/docs/all-wallets).

Styles are injected by the provider, so there is no CSS file to import.

## Next steps

- [Installation](/docs/installation): install the package and its peers.
- [Quick start](/docs/quick-start): a minimal working app.
- [Next.js](/docs/nextjs): setup for the App Router.
- Try every option live in the [playground](/playground).

---

# Installation

> Install Wyllet and its peer dependencies, and enable WalletConnect.

Source: https://wyllet.dev/docs/installation

Install the `wyllet` package together with its peer dependencies. If your dApp already uses wagmi, you likely have most of them.

## Install

```bash title="pnpm"
pnpm add wyllet wagmi viem @tanstack/react-query
```

```bash title="npm"
npm install wyllet wagmi viem @tanstack/react-query
```

```bash title="yarn"
yarn add wyllet wagmi viem @tanstack/react-query
```

```bash title="bun"
bun add wyllet wagmi viem @tanstack/react-query
```

`react` and `react-dom` are peers too. They are already part of any React app.

## Peer dependencies

Wyllet has no direct runtime dependencies. Everything it needs is a peer dependency that your dApp provides.

| Package | Version | Required |
| --- | --- | --- |
| `react` | `>=18` | Yes |
| `react-dom` | `>=18` | Yes |
| `wagmi` | `^3.0.0` | Yes |
| `viem` | `^2.15.0` | Yes |
| `@tanstack/react-query` | `>=5.0.0` | Yes |
| `@walletconnect/ethereum-provider` | `^2.21.1` | Only with WalletConnect |

## Enable WalletConnect

WalletConnect lets users connect mobile wallets by scanning a QR code on desktop, or by opening the wallet app on a phone. It also powers the **All wallets** directory. It is optional, and it is only active when you pass a `walletConnectProjectId`.

To enable it:

1. Create a free project ID at [cloud.reown.com](https://cloud.reown.com).
2. Install the WalletConnect provider.
3. Pass the ID to `getDefaultConfig()`.

```bash title="pnpm"
pnpm add @walletconnect/ethereum-provider
```

```bash title="npm"
npm install @walletconnect/ethereum-provider
```

```bash title="yarn"
yarn add @walletconnect/ethereum-provider
```

```bash title="bun"
bun add @walletconnect/ethereum-provider
```

```ts title="wagmi.ts"
import { base, mainnet } from 'viem/chains'
import { getDefaultConfig } from 'wyllet'

export const config = getDefaultConfig({
  appName: 'My dApp',
  walletConnectProjectId: 'YOUR_PROJECT_ID',
  chains: [mainnet, base],
})
```

Without a project ID, Wyllet does not add a WalletConnect connector, and the WalletConnect option is hidden from the wallet list. Installed browser wallets still work.

> **Note:** Keep the project ID in an environment variable, for example `NEXT_PUBLIC_WC_PROJECT_ID` in Next.js or `VITE_WC_PROJECT_ID` in Vite. It is a public value, but an environment variable makes it easy to use different projects per environment. See [WalletConnect](/docs/walletconnect) for domain allowlists and other settings.

## Styles

You do not need to import a stylesheet. `<WylletProvider>` injects its base styles in a `<style>` element when it renders.

If you would rather serve the base stylesheet as a file, turn injection off and import it yourself:

```tsx title="main.tsx"
import 'wyllet/styles.css'
```

```tsx
<WylletProvider injectStyles={false}>{children}</WylletProvider>
```

> **Warning:** `injectStyles={false}` only removes the base stylesheet. The provider still renders a small `<style>` element that holds your theme's `--wy-*` CSS variables. Account for it if your Content Security Policy restricts inline styles. See [Security](/docs/security).

## TypeScript

Wyllet ships its own type definitions for both ESM and CommonJS. No `@types` package is needed.

## Next steps

- [Quick start](/docs/quick-start): render your first connect button.
- [Next.js](/docs/nextjs): App Router setup.
- [Configuration](/docs/configuration): every `getDefaultConfig()` option.

---

# Quick start

> Add a working connect button to a React dApp in a few minutes.

Source: https://wyllet.dev/docs/quick-start

This page builds a minimal app with a working connect button. It assumes you have a React app and have [installed](/docs/installation) Wyllet and its peers.

## 1. Create a wagmi config

`getDefaultConfig()` returns a regular wagmi config with wallet discovery, WalletConnect and your wallet list already wired up.

```ts title="wagmi.ts"
import { base, mainnet } from 'viem/chains'
import { getDefaultConfig } from 'wyllet'

export const config = getDefaultConfig({
  appName: 'My dApp',
  walletConnectProjectId: 'YOUR_PROJECT_ID', // optional, free at https://cloud.reown.com
  chains: [mainnet, base], // the first chain is the default
})
```

Leave out `walletConnectProjectId` if you only need browser extension wallets for now.

## 2. Add the providers

Wrap your app in wagmi's `WagmiProvider`, react-query's `QueryClientProvider` and `WylletProvider`, in that order. Then render `WylletButton` anywhere inside.

```tsx title="App.tsx"
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { WagmiProvider } from 'wagmi'
import { WylletButton, WylletProvider } from 'wyllet'
import { config } from './wagmi'

const queryClient = new QueryClient()

export function App() {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        <WylletProvider>
          <header>
            <WylletButton />
          </header>
        </WylletProvider>
      </QueryClientProvider>
    </WagmiProvider>
  )
}
```

That is the whole integration. Styles are injected for you, so there is no CSS import. Clicking the button opens the connect panel. Once connected, the button shows the account, and clicking it opens the account panel.

## 3. Use wagmi as usual

Wyllet does not wrap wagmi's hooks. Read the connection and send transactions with wagmi directly:

```tsx
import { useConnection } from 'wagmi'

function Greeting() {
  const { address, isConnected } = useConnection()
  return isConnected ? <p>Connected as {address}</p> : null
}
```

## Next steps

### Pick a theme

The default theme follows the operating system: Porcelain in light mode and Obsidian in dark mode. Pass a preset with your brand color to change it.

```tsx
import { obsidianTheme } from 'wyllet'

<WylletProvider theme={obsidianTheme({ accentColor: '#C6F432', radius: 'soft' })}>
```

See [Theming](/docs/theming).

### Choose a presentation

The panel opens as a side drawer by default. Switch to a popover anchored to the button, or a centered modal:

```tsx
<WylletProvider appearance={{ presentation: 'popover' }}>
```

See [Presentations](/docs/presentations).

### Add a keyboard shortcut

```tsx
<WylletProvider shortcut="mod+k">
```

`mod` is ⌘ on macOS and Ctrl elsewhere. The button shows the shortcut as a hint while disconnected.

### Test without a wallet extension

`burnerWallet()` adds an in-browser wallet whose private key is kept in `localStorage`. It lets you try the connected state locally without installing anything.

```ts title="wagmi.ts"
import { base, mainnet } from 'viem/chains'
import { burnerWallet, defaultWallets, getDefaultConfig } from 'wyllet'

export const config = getDefaultConfig({
  appName: 'My dApp',
  chains: [mainnet, base],
  wallets: [...defaultWallets(), burnerWallet()],
})
```

> **Warning:** The burner wallet is for development only. Its key is stored unencrypted, and Wyllet logs a console warning when it runs on a non-local host (anything other than addresses like `localhost`, `127.0.0.1` or a `.local` or `.test` domain). Remove it from production builds.

### Keep going

- [Next.js](/docs/nextjs) if you use the App Router.
- [Configuration](/docs/configuration) for app metadata, RPC transports and wallets.
- [WylletProvider](/docs/provider) for every provider option.
- The [playground](/playground) to try options and copy the generated code.

---

# Next.js

> Use Wyllet with the Next.js App Router, server components and SSR.

Source: https://wyllet.dev/docs/nextjs

Wyllet works with the Next.js App Router. You put the providers in a client component, wrap your layout with it, and render the button from any page.

## How it works with server components

The published package starts with a `'use client'` directive, so every Wyllet export is a client module. In practice this means:

- You can render `<WylletButton />` and `<ConnectGate>` from a server component. They become client components automatically.
- Functions such as `getDefaultConfig()`, `obsidianTheme()` or `withDefaultTokens()` must be called from client modules, such as the providers file below. A server component cannot call functions exported from a client module.
- The providers themselves (`WagmiProvider`, `QueryClientProvider`, `WylletProvider`) need a client component, because they hold state.

## 1. Add the project ID

Store the WalletConnect project ID in an environment variable with the `NEXT_PUBLIC_` prefix so it is available in the browser.

```bash title=".env.local"
NEXT_PUBLIC_WC_PROJECT_ID=your_project_id
```

## 2. Create the config

```ts title="lib/wagmi.ts"
import { base, mainnet } from 'viem/chains'
import { getDefaultConfig } from 'wyllet'

export const config = getDefaultConfig({
  appName: 'My dApp',
  appUrl: 'https://my-dapp.xyz',
  walletConnectProjectId: process.env.NEXT_PUBLIC_WC_PROJECT_ID,
  chains: [mainnet, base],
  ssr: true,
})
```

`appUrl` defaults to `window.location.origin`. On the server there is no `window`, so set `appUrl` explicitly when the config is also evaluated during server rendering. The URL is sent to wallets as part of the WalletConnect metadata.

`ssr: true` is a regular wagmi option. `getDefaultConfig()` accepts every wagmi `createConfig()` parameter except `chains`, `transports` and `connectors` (which it builds for you) and passes them through. That includes options such as `ssr` and `storage`.

## 3. Create a providers component

```tsx title="app/providers.tsx"
'use client'

import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { useState, type ReactNode } from 'react'
import { WagmiProvider } from 'wagmi'
import { WylletProvider } from 'wyllet'
import { config } from '@/lib/wagmi'

export function Providers({ children }: { children: ReactNode }) {
  const [queryClient] = useState(() => new QueryClient())

  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        <WylletProvider>{children}</WylletProvider>
      </QueryClientProvider>
    </WagmiProvider>
  )
}
```

Creating the `QueryClient` inside `useState` keeps one client per browser session and avoids sharing a client between server requests.

## 4. Wrap the root layout

```tsx title="app/layout.tsx"
import type { ReactNode } from 'react'
import { Providers } from './providers'

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  )
}
```

## 5. Render the button

```tsx title="app/page.tsx"
import { WylletButton } from 'wyllet'

export default function Page() {
  return (
    <header>
      <WylletButton />
    </header>
  )
}
```

This page stays a server component. Pass theme objects, appearance options and other non-serializable props on `<WylletProvider>` in `providers.tsx`, not from server components.

## Hydration and SSR

Wallet state only exists in the browser, so Wyllet avoids rendering account details on the server:

- `<WylletButton>` renders a hidden, disabled placeholder until it has mounted on the client. The placeholder keeps its space in the layout, so nothing shifts when the real button appears.
- `<ConnectGate>` never renders its children before mount. Until then it shows its default prompt hidden, or your `fallback` if you passed one.
- The panel and toasts render into a portal only on the client.

If you build your own button with `useWylletButton()`, use its `mounted` flag the same way:

```tsx title="components/connect-button.tsx"
'use client'

import { useWylletButton } from 'wyllet'

export function ConnectButton() {
  const { mounted, account, open } = useWylletButton()

  if (!mounted) return <button disabled aria-hidden style={{ visibility: 'hidden' }}>Connect</button>

  return (
    <button onClick={(e) => open(e.currentTarget)}>
      {account ? account.displayName : 'Connect'}
    </button>
  )
}
```

See [WylletButton](/docs/wyllet-button) for the full shape of `useWylletButton()`.

## Light and dark mode

With the default theme pair, Wyllet follows the operating system through `prefers-color-scheme`. If your site has its own theme toggle, pass the current mode as `colorMode` from your providers component so Wyllet matches it:

```tsx
<WylletProvider colorMode={siteTheme}>{children}</WylletProvider>
```

`siteTheme` here is your own `'light'`, `'dark'` or `'auto'` value. See [Theming](/docs/theming).

## Related

- [Configuration](/docs/configuration)
- [WylletProvider](/docs/provider)
- [WalletConnect](/docs/walletconnect)

---

# Build with AI assistants

> Give Cursor, Claude Code, Copilot or ChatGPT the Wyllet docs and the rules for a correct integration.

Source: https://wyllet.dev/docs/ai-assistants

Most Wyllet integrations are now written with an AI coding assistant. This page gives your assistant everything it needs: where to read the docs, a prompt to start from, and the rules that keep generated code correct.

## Give your assistant the docs

Every page on this site is available in a form built for language models.

| Resource | What it contains |
| --- | --- |
| [`/llms.txt`](/llms.txt) | An index of every doc page and post, with one-line summaries and links to their Markdown versions |
| [`/llms-full.txt`](/llms-full.txt) | The complete documentation in one plain-text file |
| `<page>.md` | The Markdown version of any doc or post, for example [`/docs/quick-start.md`](/docs/quick-start.md) |
| `Accept: text/markdown` | Requesting any doc or post URL with this header returns Markdown instead of HTML |

Tools that can fetch URLs (Claude Code, Cursor, Copilot agent mode, ChatGPT with browsing) can read `/llms-full.txt` directly. For tools that can't, copy a page with the **Copy as Markdown** button at the top of every doc and paste it into the chat.

> **Note:** Assistants that support custom documentation sources, such as Cursor's `@Docs`, can index `https://wyllet.dev/llms-full.txt` once and reuse it in every chat.

## A prompt to start from

Paste this into your assistant and fill in the parts in brackets.

```text
Add the Wyllet wallet connector to this [Next.js App Router | Vite + React] app.

Read https://wyllet.dev/llms-full.txt first and follow it exactly. Wyllet is built on wagmi v3 and viem 2.

Requirements:
- Chains: [mainnet, base] (the first chain is the default)
- WalletConnect project ID from the env var [NEXT_PUBLIC_WC_PROJECT_ID]
- Put the connect button in [the site header]
- Theme: [obsidianTheme with accentColor '#…' | light/dark pair following the OS]
- [Optional: Sign-In With Ethereum against my existing /api/auth routes]

Rules:
- Install: wyllet wagmi viem @tanstack/react-query, plus @walletconnect/ethereum-provider because a project ID is set.
- Use getDefaultConfig from wyllet for the wagmi config. Do not install or configure RainbowKit, ConnectKit or Web3Modal.
- Providers go in a 'use client' component, nested WagmiProvider > QueryClientProvider > WylletProvider.
- Do not import any CSS. Wyllet injects its own styles.
- Only use props and hooks documented on wyllet.dev. Do not invent options.
```

## Rules for a correct integration

These are the mistakes assistants make most often. Each rule is checked against the library source.

### Packages

- Install `wyllet` together with its peers: `wagmi`, `viem`, `@tanstack/react-query`, `react` and `react-dom`. Wyllet has no direct runtime dependencies of its own.
- Install `@walletconnect/ethereum-provider` only when `walletConnectProjectId` is set. It is an optional peer.
- Wyllet requires wagmi v3. Tutorials written for wagmi v2 use APIs that have since changed, so prefer these docs and the wagmi v3 reference.

### Providers and client components

- The package ships with a `'use client'` directive. Call `getDefaultConfig()`, theme presets such as `obsidianTheme()` and `withDefaultTokens()` from client modules only.
- Nest the providers in this order: `WagmiProvider`, then `QueryClientProvider`, then `WylletProvider`. Every Wyllet component and hook must render inside `WylletProvider`.
- In Next.js, create the `QueryClient` inside `useState` in the providers component, and set `appUrl` in `getDefaultConfig()` because there is no `window` on the server.
- Do not import a stylesheet. Styles are injected automatically. `injectStyles={false}` plus `import 'wyllet/styles.css'` is only for apps that load styles themselves.

### Configuration

- The order of `chains` is the priority order, and the first chain is the default. Use `customChain()` for chains that `viem/chains` doesn't include.
- `getDefaultConfig()` accepts any wagmi `createConfig()` option except `chains`, `transports` and `connectors`, which it builds. Pass your own RPC URLs through `transports` in production.
- With a hand-written `createConfig()`, pass `wallets`, `appInfo` and `walletConnectProjectId` to `WylletProvider`, include `walletConnect({ showQrModal: false })`, and add `burner()` to the connectors if you use `burnerWallet()`.
- `burnerWallet()` is for local development only. It keeps a private key in `localStorage`.

### Opening the panel

- `useWylletButton()` takes an element: `open(e.currentTarget)` or `openAccount(el, 'activity')`.
- `useWyllet()` takes an options object: `openConnect({ anchor: e.currentTarget })` or `openTab('networks', { anchor })`.
- The popover presentation needs an anchor element. Without one it falls back to a modal.
- The keyboard shortcut is off until you pass `shortcut="mod+k"`.

### Sign-In With Ethereum

- The auth adapter needs `getNonce`, `verify` and `signOut`, and optionally `getSession`. Verify the signature and the nonce on your server, never only in the browser.
- Switching accounts or disconnecting signs the user out automatically. Don't add your own listener for that.

### Styling

- Change colors and radii through theme options or `overrides`, not by targeting internal class names.
- To override `--wy-*` variables from your own stylesheet, use a selector at least as specific as `:root [data-wyllet]`.

## A complete reference implementation

This is the smallest correct Next.js App Router setup. It is a good target to compare generated code against.

```ts title="lib/wagmi.ts"
import { base, mainnet } from 'viem/chains'
import { getDefaultConfig } from 'wyllet'

export const config = getDefaultConfig({
  appName: 'My dApp',
  appUrl: 'https://my-dapp.xyz',
  walletConnectProjectId: process.env.NEXT_PUBLIC_WC_PROJECT_ID,
  chains: [mainnet, base],
  ssr: true,
})
```

```tsx title="app/providers.tsx"
'use client'

import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { useState, type ReactNode } from 'react'
import { WagmiProvider } from 'wagmi'
import { obsidianTheme, WylletProvider } from 'wyllet'
import { config } from '@/lib/wagmi'

export function Providers({ children }: { children: ReactNode }) {
  const [queryClient] = useState(() => new QueryClient())
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        <WylletProvider theme={obsidianTheme({ accentColor: '#48ECD2' })} shortcut="mod+k">
          {children}
        </WylletProvider>
      </QueryClientProvider>
    </WagmiProvider>
  )
}
```

```tsx title="app/layout.tsx"
import type { ReactNode } from 'react'
import { WylletButton } from 'wyllet'
import { Providers } from './providers'

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Providers>
          <header>
            <WylletButton />
          </header>
          {children}
        </Providers>
      </body>
    </html>
  )
}
```

## Check the result

Before you accept generated code, check that:

1. `wyllet` appears in `package.json` with `wagmi` v3 and `viem` v2, and no other wallet connector library was added.
2. The providers file starts with `'use client'` and nests the three providers in the right order.
3. There is no Wyllet CSS import.
4. The button opens the panel, installed wallets appear under **Detected**, and the WalletConnect option shows a QR code once a project ID is set.
5. Every prop and hook used appears in the [Provider](/docs/provider), [Hooks](/docs/hooks) or [Components](/docs/components) reference.

## Related

- [Quick start](/docs/quick-start)
- [Next.js](/docs/nextjs)
- [Migrate from RainbowKit](/docs/migrate-from-rainbowkit)

---

# Configuration

> Create a wagmi config with getDefaultConfig: app info, chains, transports and wallets.

Source: https://wyllet.dev/docs/configuration

`getDefaultConfig()` creates the wagmi config for your app. It returns a standard wagmi `Config` that you pass to `<WagmiProvider>`, and it also registers your wallet list and app metadata so `<WylletProvider>` picks them up without extra props.

## Basic usage

```ts title="wagmi.ts"
import { base, mainnet } from 'viem/chains'
import { getDefaultConfig } from 'wyllet'

export const config = getDefaultConfig({
  appName: 'My dApp',
  walletConnectProjectId: 'YOUR_PROJECT_ID',
  chains: [mainnet, base],
})
```

## Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `appName` | `string` | Required | Your dApp's name. Shown in the connect panel title and sent to wallets. |
| `appDescription` | `string` | `appName` | Sent to wallets in the WalletConnect metadata. |
| `appUrl` | `string` | `window.location.origin` | Your dApp's URL, sent to wallets. Set it explicitly when the config is evaluated on the server. |
| `appIcon` | `string` | None | URL of a square icon shown inside wallets. |
| `walletConnectProjectId` | `string` | None | Enables WalletConnect (QR codes, mobile wallets and the All wallets directory). Requires `@walletconnect/ethereum-provider`. |
| `chains` | `readonly [Chain, ...Chain[]]` | Required | Supported networks in priority order. The first chain is the default. |
| `transports` | `Partial<Record<chainId, Transport>>` | `http()` per chain | Transport per chain id. Chains you leave out use `http()`, which is the chain's public RPC. |
| `wallets` | `Wallet[]` | `defaultWallets()` | Wallets shown in the connect panel, in order. |
| `connectors` | `CreateConnectorFn[]` | `[]` | Extra wagmi connectors, appended as-is. |

Every other wagmi `createConfig()` parameter is passed through unchanged. The type is `Omit<CreateConfigParameters, 'chains' | 'transports' | 'connectors'>` plus the fields above, so options like `ssr`, `storage`, `syncConnectedChain` or `pollingInterval` work as they do in wagmi.

## Chains

`chains` accepts any viem `Chain`. Mix chains from `viem/chains`, Wyllet's `popularChains` and `popularTestnets` presets, and your own chains built with `customChain()`.

```ts
import { sepolia } from 'viem/chains'
import { getDefaultConfig, popularChains } from 'wyllet'

export const config = getDefaultConfig({
  appName: 'My dApp',
  chains: [...popularChains, sepolia],
})
```

The order matters: the first chain is the default. To arrange the Networks tab differently, use the `chainOrder` prop on `<WylletProvider>`. See [Chains](/docs/chains).

## Transports

By default each chain uses `http()` with no URL, which means the chain's public RPC endpoint. Public endpoints are rate-limited and are not meant for production traffic.

> **Warning:** Use your own RPC provider in production. Public RPCs can throttle or drop requests, which shows up as missing balances, slow confirmations and failed reads.

```ts
import { http } from 'wagmi'
import { base, mainnet } from 'viem/chains'
import { getDefaultConfig } from 'wyllet'

export const config = getDefaultConfig({
  appName: 'My dApp',
  chains: [mainnet, base],
  transports: {
    [mainnet.id]: http('https://eth-mainnet.example.com/v2/KEY'),
    [base.id]: http('https://base-mainnet.example.com/v2/KEY'),
  },
})
```

`transports` is partial. Any chain without an entry falls back to `http()`.

## Wallets

`wallets` controls which wallets appear in the connect panel and in what order. It defaults to `defaultWallets()`: MetaMask, Phantom, Rabby, OKX Wallet and WalletConnect.

```ts
import { base, mainnet } from 'viem/chains'
import { burnerWallet, coinbaseWallet, defaultWallets, getDefaultConfig } from 'wyllet'

export const config = getDefaultConfig({
  appName: 'My dApp',
  chains: [mainnet, base],
  wallets: [
    ...defaultWallets(),
    coinbaseWallet({ overrides: { icon: '/brand/coinbase-wallet.svg' } }),
    burnerWallet(),
  ],
})
```

Installed browser wallets you did not list are still detected through EIP-6963 and shown under **Detected**. See [Wallets](/docs/wallets) for every preset and for custom wallets.

## What getDefaultConfig sets up

For reference, `getDefaultConfig()` builds the connector list like this:

1. A WalletConnect connector, if `walletConnectProjectId` is set and at least one wallet in `wallets` supports WalletConnect. It is created with `showQrModal: false`, because Wyllet renders its own QR code.
2. One connector for each wallet that brings its own (for example `burnerWallet()`), tagged so the panel knows which wallet it belongs to.
3. A generic `injected({ shimDisconnect: true })` connector, used for `window.ethereum` in browsers and in-app webviews without EIP-6963.
4. Your extra `connectors`.

EIP-6963 discovery of installed extensions is handled by wagmi itself.

## App metadata

`appName`, `appDescription`, `appUrl` and `appIcon` are sent to wallets when connecting through WalletConnect, and `appName` appears in the connect panel title ("Connect to My dApp").

Some app details are only set on the provider, through its `appInfo` prop: `learnMoreUrl` for the "Learn more about wallets" link, and `termsUrl` plus `privacyUrl` for the terms notice in the panel footer. The notice only appears when both URLs are set. `appInfo` is merged over what `getDefaultConfig()` registered.

```tsx
<WylletProvider appInfo={{ termsUrl: '/terms', privacyUrl: '/privacy' }}>
```

## Using your own createConfig

You can skip `getDefaultConfig()` and write the wagmi config yourself. Wyllet works with any config, but because nothing is registered for it, pass the Wyllet-specific details to `<WylletProvider>` instead.

```ts title="wagmi.ts"
import { createConfig, http, injected } from 'wagmi'
import { walletConnect } from 'wagmi/connectors'
import { base, mainnet } from 'viem/chains'

export const projectId = 'YOUR_PROJECT_ID'

export const config = createConfig({
  chains: [mainnet, base],
  transports: {
    [mainnet.id]: http(),
    [base.id]: http(),
  },
  connectors: [
    walletConnect({
      projectId,
      showQrModal: false,
      metadata: {
        name: 'My dApp',
        description: 'My dApp',
        url: 'https://my-dapp.xyz',
        icons: ['https://my-dapp.xyz/icon.png'],
      },
    }),
    injected({ shimDisconnect: true }),
  ],
})
```

```tsx title="providers.tsx"
import { defaultWallets, WylletProvider } from 'wyllet'
import { projectId } from './wagmi'

<WylletProvider
  wallets={defaultWallets()}
  appInfo={{ name: 'My dApp' }}
  walletConnectProjectId={projectId}
>
  {children}
</WylletProvider>
```

Keep these points in mind with a hand-written config:

- Include a `walletConnect()` connector with `showQrModal: false` if you want QR codes and mobile wallets. Without it, the WalletConnect option is hidden.
- Pass `walletConnectProjectId` to the provider as well. The All wallets directory needs it.
- Pass `appInfo` with at least a `name`. Otherwise the panel title reads "Connect to this app".
- `wallets` defaults to `defaultWallets()` when nothing is registered.
- A wallet that relies on its own connector must find that connector in your config. For the burner wallet, add `burner()` (exported by Wyllet) to `connectors`; `burnerWallet()` matches it by the connector id `burner`. A custom wallet can point at any connector in your config with `connectorId`.

## Related

- [WylletProvider](/docs/provider)
- [Wallets](/docs/wallets)
- [Chains](/docs/chains)
- [WalletConnect](/docs/walletconnect)

---

# WylletProvider

> Every WylletProvider prop: theme, appearance, tokens, auth, messages and callbacks.

Source: https://wyllet.dev/docs/provider

`<WylletProvider>` holds Wyllet's options and renders the panel and toasts. Place it inside `<WagmiProvider>` and `<QueryClientProvider>`, and render every Wyllet component and hook inside it.

## Usage

```tsx
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import type { ReactNode } from 'react'
import { WagmiProvider } from 'wagmi'
import { obsidianTheme, WylletProvider } from 'wyllet'
import { config } from './wagmi'

const queryClient = new QueryClient()

export function Providers({ children }: { children: ReactNode }) {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        <WylletProvider
          theme={obsidianTheme({ accentColor: '#C6F432' })}
          appearance={{ presentation: 'popover' }}
          shortcut="mod+k"
        >
          {children}
        </WylletProvider>
      </QueryClientProvider>
    </WagmiProvider>
  )
}
```

Every prop is optional except `children`. Wyllet components and hooks throw an error if they are rendered outside the provider.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | Required | Your app. |
| `theme` | `Theme \| { light: Theme; dark: Theme }` | Porcelain (light) and Obsidian (dark) | A single theme, or a light and dark pair. See [Theming](/docs/theming). |
| `colorMode` | `'auto' \| 'light' \| 'dark'` | `'auto'` | Which half of a theme pair to use. `auto` follows the OS. Ignored for a single theme. |
| `appearance` | `Appearance` | See below | Presentation and behavior options. |
| `appInfo` | `Partial<AppInfo>` | From `getDefaultConfig()` | Overrides app details. Merged over the registered values. |
| `wallets` | `Wallet[]` | From `getDefaultConfig()`, else `defaultWallets()` | Overrides the wallet list. Needed with a hand-written wagmi config. |
| `walletConnectProjectId` | `string` | From `getDefaultConfig()` | WalletConnect project ID for hand-written configs. Enables the All wallets directory. |
| `tokens` | `TokenList \| TokenEntry[] \| 'default' \| false` | `'default'` | Tokens in the Tokens tab, for every user. `'default'` is a built-in list of blue chips, `false` shows the native balance only. See [Tokens](/docs/tokens). |
| `chainOrder` | `number[]` | `[]` | Chain ids shown first in the Networks tab, in this order. The rest follow in config order. |
| `allowTokenImport` | `boolean` | `false` | Lets users add ERC-20 tokens by contract address. Saved in their browser. |
| `shortcut` | `string` | None | Keyboard shortcut that toggles the panel, such as `'mod+k'`. |
| `messages` | `Partial<Messages>` | English | Rename or translate any string. See [Translations](/docs/i18n). |
| `classNames` | `Partial<Record<WylletSlot, string>>` | `{}` | Extra classes per element. See [Class names](/docs/class-names). |
| `chainIcons` | `Record<number, string>` | `{}` | Icon URL per chain id. Takes priority over `customChain()` icons and built-in marks. |
| `avatar` | `ComponentType<CustomAvatarProps>` | Gradient avatar | Replaces the generated avatar everywhere. |
| `auth` | `WylletAuthAdapter` | None | Enables Sign-In With Ethereum. See [SIWE](/docs/siwe). |
| `disclaimer` | `ReactNode` | Terms notice | Custom footer content in the connect panel. Replaces the terms notice. |
| `ens` | `boolean` | `true` | Resolve ENS names and avatars. Only takes effect when mainnet is in your config. |
| `injectStyles` | `boolean` | `true` | Inject the base stylesheet. Set `false` and import `wyllet/styles.css` yourself. |
| `onConnect` | `(info) => void` | None | Called after a connection. See [Callbacks](#callbacks). |
| `onDisconnect` | `() => void` | None | Called after the wallet disconnects. |

## Appearance

`appearance` groups the options that change how the panel looks and behaves. Pass only the keys you want to change; the rest keep their defaults.

```tsx
<WylletProvider
  appearance={{
    presentation: 'popover',
    identityCard: true,
    accountTabs: ['tokens', 'activity'],
    toastPosition: 'bottom-right',
  }}
>
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `presentation` | `'drawer' \| 'popover' \| 'modal'` | `'drawer'` | How the panel enters the screen. See [Presentations](/docs/presentations). |
| `drawerSide` | `'left' \| 'right'` | `'right'` | Side the drawer slides in from. |
| `mobileSheet` | `boolean` | `true` | Use a draggable bottom sheet on screens up to 640px wide, whatever the `presentation`. |
| `identityCard` | `boolean` | `false` | Show a generative holographic card, unique to each address, instead of the compact account summary. |
| `cardTilt` | `boolean` | `true` | 3D tilt and light sheen that follow the pointer on the identity card. |
| `accountTabs` | `AccountTab[]` | `['tokens', 'activity', 'networks']` | Tabs in the account panel, in order. |
| `closeOnConnect` | `boolean` | `true` | Close the panel after a successful connection. With `false`, it moves on to the account panel. |
| `tokenSort` | `'balance' \| 'list'` | `'balance'` | `balance`: pinned tokens, then tokens the user holds, then the rest, each group in list order. `list`: pinned first, then exactly your list order. |
| `walletSearch` | `boolean \| 'auto'` | `'auto'` | Search field in the wallet list. `auto` shows it when there are 6 or more wallets. |
| `walletDirectory` | `boolean` | `true` | The All wallets directory from the WalletConnect registry. Also needs a WalletConnect project ID. |
| `toastPosition` | `ToastPosition` | `'top-center'` | `'top-left'`, `'top-center'`, `'top-right'`, `'bottom-left'`, `'bottom-center'` or `'bottom-right'`. |
| `branding` | `boolean` | `true` | The "Powered by Wyllet" badge in the panel footers. |
| `disableAnimations` | `boolean` | `false` | Turn off all transitions. `prefers-reduced-motion` is respected either way. |

## App info

`appInfo` accepts any subset of these fields. Values you pass are merged over the ones `getDefaultConfig()` registered from `appName`, `appDescription`, `appUrl` and `appIcon`.

| Field | Type | Description |
| --- | --- | --- |
| `name` | `string` | Shown in the connect panel title. Falls back to "this app" when nothing is set. |
| `description` | `string` | App description. |
| `url` | `string` | App URL. |
| `icon` | `string` | Square icon URL. |
| `learnMoreUrl` | `string` | Target of the "Learn more about wallets" link. Defaults to ethereum.org's wallet page. |
| `termsUrl` | `string` | Terms of service URL. |
| `privacyUrl` | `string` | Privacy policy URL. |

The connect panel footer shows "By connecting you accept the Terms and Privacy Policy" only when both `termsUrl` and `privacyUrl` are set. A `disclaimer` replaces that notice entirely.

## Keyboard shortcut

`shortcut` is a `+`-separated combination. The modifiers are `mod`, `ctrl`, `meta`, `shift` and `alt`, and the last part is the key. `mod` means ⌘ on macOS and Ctrl elsewhere.

```tsx
<WylletProvider shortcut="mod+k">
```

The shortcut toggles the panel. It opens the account view when the user is connected (and signed in, if you use SIWE), and the connect view otherwise. While disconnected, `<WylletButton>` shows the shortcut as a hint.

## Custom avatar

`avatar` receives the address, the resolved ENS avatar URL (when there is one) and the size in pixels.

```tsx
import type { CustomAvatarProps } from 'wyllet'

function MyAvatar({ address, ensImage, size }: CustomAvatarProps) {
  return <img src={ensImage ?? `/avatars/${address}.png`} width={size} height={size} alt="" />
}

<WylletProvider avatar={MyAvatar}>
```

## Callbacks

`onConnect` runs after each connection, including automatic reconnects on page load. Use `isReconnected` to tell them apart.

```tsx
<WylletProvider
  onConnect={({ address, chainId, connectorId, isReconnected }) => {
    if (!isReconnected) analytics.track('wallet_connected', { connectorId, chainId })
  }}
  onDisconnect={() => analytics.track('wallet_disconnected')}
>
```

| Field | Type | Description |
| --- | --- | --- |
| `address` | `Address` | The connected account. |
| `chainId` | `number` | The connected chain. |
| `connectorId` | `string` | The wagmi connector id. |
| `isReconnected` | `boolean` | `true` when the session was restored rather than newly connected. |

## Related

- [Configuration](/docs/configuration)
- [Presentations](/docs/presentations)
- [Theming](/docs/theming)
- [Hooks](/docs/hooks)

---

# WylletButton

> The Island button, its display options, and building your own trigger with useWylletButton.

Source: https://wyllet.dev/docs/wyllet-button

`<WylletButton>` is the Wallet Island: one button that changes with the connection state. When disconnected it is a call to action; when connected it shows the account's avatar, name, network and balance, and opens the account panel.

## Usage

```tsx
import { WylletButton } from 'wyllet'

<WylletButton />
<WylletButton size="lg" display="compact" label="Enter app" />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | `messages.connect` ("Connect") | Text shown while disconnected. |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Button height and text size. |
| `display` | `'full' \| 'compact' \| 'avatar'` | `'full'` | What the connected button shows. `full`: avatar, name and balance. `compact`: avatar and name. `avatar`: avatar only. |
| `className` | `string` | None | Extra class names, added after `classNames.island`. |

## States

The button renders differently depending on the connection.

| State | What it shows | On click |
| --- | --- | --- |
| Before mount | A hidden, disabled placeholder that keeps the button's space. | Nothing. |
| Disconnected | Wallet icon, the `label`, and the shortcut hint if `shortcut` is set on the provider. | Opens the connect view. |
| Connecting or reconnecting | A spinner and "Connecting". | Opens the connect view. |
| Connected | Avatar with a network badge, the ENS name or shortened address, the native balance (with `display="full"`) and a status dot. | Opens the account view. |
| Wrong network | An alert badge on the avatar and "Wrong network" in place of the name. No balance. | Opens the account view on the Networks tab. |
| Needs sign-in | "Verify" in place of the name and a pending status dot. No balance. Only with an `auth` adapter. | Opens the connect view at the sign-in step. |

"Wrong network" means the wallet is on a chain that is not in your wagmi config. The labels come from `messages` (`connect`, `connecting`, `wrongNetwork` and `verify`), so you can rename them. See [Translations](/docs/i18n).

The button passes itself as the anchor when it opens the panel, so the `popover` presentation positions the panel next to it. See [Presentations](/docs/presentations).

If the button ever throws while rendering, Wyllet falls back to a plain connect button so users can still open the panel.

## Headless: useWylletButton

`useWylletButton()` returns the same state that powers `<WylletButton>`, so you can build your own trigger with full control over markup and styles.

```tsx
import { useWylletButton } from 'wyllet'

export function ConnectButton() {
  const { mounted, account, chain, authStatus, open } = useWylletButton()

  if (!mounted) return null

  if (!account) {
    return <button onClick={(e) => open(e.currentTarget)}>Connect wallet</button>
  }

  return (
    <button onClick={(e) => open(e.currentTarget)}>
      {chain?.unsupported ? 'Wrong network' : authStatus === 'unauthenticated' ? 'Verify' : account.displayName}
      {account.balance && ` · ${account.balance.formatted} ${account.balance.symbol}`}
    </button>
  )
}
```

### Return value

| 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` | Set only when connected. See below. |
| `chain` | `object \| undefined` | Set only when connected. See below. |
| `authStatus` | `'loading' \| 'unauthenticated' \| 'authenticated' \| undefined` | Sign-in status for the connected account. `undefined` when no `auth` adapter is configured. |
| `open` | `(anchor?: Element \| null) => void` | Opens the connect view when disconnected or not signed in, otherwise the account view. |
| `openConnect` | `(anchor?: Element \| null) => void` | Opens the connect view. |
| `openAccount` | `(anchor?: Element \| null, tab?: AccountTab) => void` | Opens the account view, optionally on a tab: `'tokens'`, `'activity'` or `'networks'`. |

`account` contains:

| Field | Type | Description |
| --- | --- | --- |
| `address` | `Address` | The connected address. |
| `displayName` | `string` | The ENS name if there is one, otherwise the shortened address. |
| `ensName` | `string \| null \| undefined` | The ENS name, when ENS is enabled and resolved. |
| `balance` | `object \| undefined` | Native balance: `formatted` (string), `symbol`, `value` (bigint) and `decimals`. |

`chain` contains:

| Field | Type | Description |
| --- | --- | --- |
| `id` | `number` | The connected chain id. |
| `name` | `string` | The chain name, or "Chain" followed by the id when the chain is not in your config. |
| `unsupported` | `boolean` | `true` when the chain is not in your wagmi config. |

> **Note:** The open functions here take the anchor element directly, as in `open(e.currentTarget)`. The functions returned by `useWyllet()` take an options object instead, as in `openConnect({ anchor: e.currentTarget })`. See [Hooks](/docs/hooks).

## Styling

The button uses the `islandBackground`, `islandText` and `shadows.island` theme tokens while connected, and the accent color while disconnected. Change them through your theme, or add classes with `className` or `classNames.island`. See [Theming](/docs/theming) and [Class names](/docs/class-names).

## Related

- [Presentations](/docs/presentations)
- [ConnectGate](/docs/connect-gate)
- [Hooks](/docs/hooks)

---

# Presentations

> Open the panel as a drawer, an anchored popover, a modal or a mobile bottom sheet.

Source: https://wyllet.dev/docs/presentations

The connect and account views open in a single panel. The `presentation` option decides how that panel enters the screen: as a side drawer, a popover anchored to the element that opened it, or a centered modal. On phones it becomes a bottom sheet.

## Choosing a presentation

```tsx
<WylletProvider appearance={{ presentation: 'popover' }}>
```

| Value | Behavior |
| --- | --- |
| `'drawer'` | A full-height panel that floats along one side of the screen. The default. |
| `'popover'` | A panel positioned next to the element that opened it, like a dropdown. Falls back to `modal` when there is no anchor. |
| `'modal'` | A centered dialog. |

Every presentation shares the same behavior: the panel renders in a portal on `document.body`, traps focus while open, locks page scroll, closes on Escape or a click outside, and returns focus to the previously focused element when it closes.

## Drawer

The drawer is the default. Use `drawerSide` to choose the side it slides in from.

```tsx
<WylletProvider appearance={{ presentation: 'drawer', drawerSide: 'left' }}>
```

| Option | Type | Default |
| --- | --- | --- |
| `drawerSide` | `'left' \| 'right'` | `'right'` |

The drawer is up to 420px wide and leaves a small gap around its edges. The page behind it is dimmed by the theme's `overlay` color and `overlayBlur` effect.

## Popover

The popover opens next to its anchor element, aligned to the anchor's left or right edge depending on which half of the viewport the anchor is in. It opens below the anchor, or above it when there is not enough room below. The overlay behind a popover is transparent.

```tsx
<WylletProvider appearance={{ presentation: 'popover' }}>
```

The popover needs to know which element to anchor to:

- `<WylletButton>` and the button inside `<ConnectGate>` pass themselves as the anchor automatically.
- When you open the panel yourself, pass the element. See [Opening with an anchor](#opening-with-an-anchor).

If the panel is opened without an anchor, the popover falls back to a modal. That includes opening it with the provider's keyboard `shortcut`.

The anchor's position is measured when the panel opens.

## Modal

A centered dialog, up to 400px wide.

```tsx
<WylletProvider appearance={{ presentation: 'modal' }}>
```

## Mobile bottom sheet

On screens up to 640px wide, the panel opens as a bottom sheet regardless of `presentation`. The sheet has a drag handle: drag it down, or flick it, to dismiss. A short drag snaps back.

Set `mobileSheet` to `false` to keep the configured presentation on phones as well.

```tsx
<WylletProvider appearance={{ presentation: 'modal', mobileSheet: false }}>
```

| Option | Type | Default |
| --- | --- | --- |
| `mobileSheet` | `boolean` | `true` |

## Opening with an anchor

You can open the panel from any element in your UI. To anchor a popover to it, pass the element when you open the panel.

With `useWylletButton()`, the open functions take the element as their first argument:

```tsx
import { useWylletButton } from 'wyllet'

function AccountChip() {
  const { open, openAccount } = useWylletButton()
  return (
    <>
      <button onClick={(e) => open(e.currentTarget)}>Wallet</button>
      <button onClick={(e) => openAccount(e.currentTarget, 'activity')}>Activity</button>
    </>
  )
}
```

With `useWyllet()`, the functions take an options object with an `anchor` field:

```tsx
import { useWyllet } from 'wyllet'

function Toolbar() {
  const { openConnect, openTab } = useWyllet()
  return (
    <>
      <button onClick={(e) => openConnect({ anchor: e.currentTarget })}>Connect</button>
      <button onClick={(e) => openTab('networks', { anchor: e.currentTarget })}>Networks</button>
    </>
  )
}
```

`useWyllet()` also returns `open(view, options)`, `openAccount(options)` and `close()`. `open()` with no view opens the account view when connected and the connect view otherwise. See [Hooks](/docs/hooks).

## Embedded

To show the panel inside your own layout rather than over it, render `<WylletEmbed />` where you want it. It is the same panel with the same theme and options, without an overlay, focus trap or scroll lock. The rest of the site keeps using the presentation you configured. See [WylletEmbed](/docs/components#wylletembed).

## Animations

The panel animates in and out. Set `disableAnimations: true` in `appearance` to turn transitions off. Users who have `prefers-reduced-motion` enabled get reduced motion automatically.

## Related

- [WylletProvider](/docs/provider) for every `appearance` option.
- [WylletButton](/docs/wyllet-button)
- [Account panel](/docs/account-panel)
- Compare the presentations live in the [playground](/playground).

---

# Theming

> Theme presets, design tokens as CSS variables, light and dark mode, and custom themes.

Source: https://wyllet.dev/docs/theming

Every visual decision in Wyllet is a token in a `Theme` object: colors, radii, fonts, shadows and effects. You pick a preset, adjust it with a few knobs, and every token is emitted as a `--wy-*` CSS variable you can also override from your own stylesheet.

## Presets

Wyllet ships four presets. Each one is a function that returns a `Theme`.

| Preset | Look | Accent | Radius | Overlay blur |
| --- | --- | --- | --- | --- |
| `obsidianTheme()` | Deep graphite, dark | Mint `#48ECD2` | `round` | `subtle` |
| `porcelainTheme()` | Warm paper white, light | Ink `#111114` | `round` | `none` |
| `auroraTheme()` | Frosted translucent glass, dark. Best over colorful backgrounds. | Violet `#B69CFF` | `round` | `subtle` |
| `terminalTheme()` | Monospace, phosphor green, dark | Green `#3DFF8F` | `sharp` | `none` |

```tsx
import { terminalTheme, WylletProvider } from 'wyllet'

<WylletProvider theme={terminalTheme()}>
```

Without a `theme` prop, Wyllet uses Porcelain in light mode and Obsidian in dark mode, following the operating system.

## Preset options

Every preset accepts the same `ThemeOptions`:

```tsx
import { obsidianTheme } from 'wyllet'

<WylletProvider
  theme={obsidianTheme({
    accentColor: '#C6F432',
    accentColorForeground: '#1A2400',
    radius: 'soft',
    fontFamily: "'Geist', system-ui, sans-serif",
    overlayBlur: 'heavy',
  })}
>
```

| Option | Type | Description |
| --- | --- | --- |
| `accentColor` | `string` | Brand color for primary actions, focus rings and live indicators. Sets `colors.accent`. |
| `accentColorForeground` | `string` | Text and icon color on top of the accent. Sets `colors.accentForeground`. |
| `accentSecondary` | `string` | Second brand color, blended with the accent in gradients such as the identity card. Sets `colors.accentSecondary`. |
| `radius` | `'sharp' \| 'soft' \| 'round' \| 'pill'` | Corner radius scale. Sets every token in `radii`. |
| `fontFamily` | `string` | Body font. Sets `fonts.body`; the mono font is unchanged. |
| `overlayBlur` | `'none' \| 'subtle' \| 'heavy'` | Blur behind the page overlay. Sets `effects.overlayBlur`. |
| `overrides` | `DeepPartial<Theme>` | Any token, deep-merged on top after the options above. |

The radius scales map to these values:

| Scale | `panel` | `card` | `button` | `badge` | `icon` |
| --- | --- | --- | --- | --- | --- |
| `sharp` | 4px | 3px | 3px | 2px | 3px |
| `soft` | 14px | 10px | 10px | 6px | 9px |
| `round` | 24px | 16px | 14px | 8px | 12px |
| `pill` | 28px | 20px | 999px | 999px | 14px |

The blur scales map to `none`, `blur(3px)` (`subtle`) and `blur(16px) saturate(120%)` (`heavy`).

## Overrides

`overrides` takes a deep partial of the theme, so you only write the tokens you want to change:

```tsx
<WylletProvider
  theme={porcelainTheme({
    accentColor: '#0052FF',
    overrides: {
      colors: { islandBackground: '#0052FF', islandText: '#FFFFFF' },
      radii: { panel: '20px' },
      shadows: { panel: 'none' },
    },
  })}
>
```

## Light and dark mode

Pass a pair of themes to switch between them with the color mode:

```tsx
import { obsidianTheme, porcelainTheme } from 'wyllet'

const accent = { accentColor: '#7B61FF' }

<WylletProvider
  theme={{ light: porcelainTheme(accent), dark: obsidianTheme(accent) }}
  colorMode="auto"
>
```

| `colorMode` | Behavior |
| --- | --- |
| `'auto'` | Follows the OS with `prefers-color-scheme`. The default. |
| `'light'` | Always uses the `light` theme. |
| `'dark'` | Always uses the `dark` theme. |

`colorMode` only applies to a pair. A single theme is used in both modes. Wyllet also sets `color-scheme` on its elements to match the active theme.

If your site has its own light and dark toggle, pass its current value as `colorMode` so Wyllet stays in sync with it.

## createTheme

`createTheme(base, overrides)` deep-merges a partial theme into a full one. Use it to derive a theme from a preset, or to build a complete theme of your own.

```ts
import { createTheme, obsidianTheme } from 'wyllet'

export const brandTheme = createTheme(obsidianTheme(), {
  colors: {
    accent: '#FF5A1F',
    accentForeground: '#1F0A00',
    background: '#101014',
  },
  fonts: { body: "'Inter', sans-serif" },
})
```

Neither argument is mutated.

## Theme tokens

The full `Theme` shape:

```ts
interface Theme {
  colors: {
    accent: string // primary actions, focus, live indicators
    accentForeground: string // text and icons on top of accent
    accentSecondary: string // blended with accent in gradients
    background: string // panel background
    surface: string // rows, cards and secondary buttons
    surfaceHover: string
    surfaceActive: string
    border: string
    text: string // primary text
    textSecondary: string // labels, captions
    textTertiary: string // hints, disabled, kbd
    overlay: string // page overlay behind the panel
    success: string
    danger: string
    warning: string
    islandBackground: string // the Wallet Island button
    islandText: string
    qrForeground: string
    qrBackground: string
  }
  radii: {
    panel: string
    card: string
    button: string
    badge: string // badges, kbd, chips
    icon: string // wallet icons
  }
  fonts: {
    body: string
    mono: string // labels, addresses, numbers, keyboard hints
  }
  shadows: {
    panel: string
    island: string
    toast: string
  }
  effects: {
    overlayBlur: string // backdrop-filter on the page overlay
    panelBlur: string // backdrop-filter on the panel (glass themes)
    glow: string // opacity of the accent glow, '0' to '1'
  }
}
```

All values are CSS strings. `effects.glow` is a number written as a string, such as `'0.35'`.

## CSS variables

Each token becomes a custom property named `--wy-<group>-<token>`, with camelCase converted to kebab-case:

| Token | CSS variable |
| --- | --- |
| `colors.accent` | `--wy-colors-accent` |
| `colors.accentForeground` | `--wy-colors-accent-foreground` |
| `colors.islandBackground` | `--wy-colors-island-background` |
| `colors.textSecondary` | `--wy-colors-text-secondary` |
| `radii.panel` | `--wy-radii-panel` |
| `fonts.mono` | `--wy-fonts-mono` |
| `shadows.toast` | `--wy-shadows-toast` |
| `effects.overlayBlur` | `--wy-effects-overlay-blur` |
| `effects.panelBlur` | `--wy-effects-panel-blur` |

The variables are set on every element Wyllet renders at the top level (the button, the panel, toasts and `<ConnectGate>`), each of which carries a `data-wyllet` attribute. You can use them in your own styles:

```css
.my-badge {
  background: var(--wy-colors-surface);
  border-radius: var(--wy-radii-badge);
}
```

Elements outside Wyllet's own markup do not inherit the variables, so use them inside class names you attach with [`classNames`](/docs/class-names), or set your own values as shown next.

### Overriding variables in CSS

Prefer the `theme` prop, because it keeps everything typed. If you need to override a token from a stylesheet, target the `data-wyllet` attribute with a selector more specific than Wyllet's own theme rule, which is a single attribute selector:

```css
:root [data-wyllet] {
  --wy-colors-accent: #ff5a1f;
  --wy-radii-panel: 16px;
}
```

Hover tints, focus rings and the accent glow are derived from `--wy-colors-accent` with `color-mix()`, so they follow an overridden accent automatically.

### themeToCssVars

`themeToCssVars(theme)` returns the variables for a theme as a plain object, which is useful for previews or for applying a theme to your own elements:

```ts
import { obsidianTheme, themeToCssVars } from 'wyllet'

const vars = themeToCssVars(obsidianTheme())
// { '--wy-colors-accent': '#48ECD2', '--wy-colors-accent-foreground': '#03201B', ... }
```

## Related

- [Class names](/docs/class-names) for per-element classes.
- [WylletProvider](/docs/provider) for `theme` and `colorMode`.
- Build a theme visually in the [playground](/playground) and copy the code.

---

# Class names

> Attach your own classes (including Tailwind) to individual Wyllet elements.

Source: https://wyllet.dev/docs/class-names

The `classNames` prop attaches your own class names to specific Wyllet elements. Use it for layout tweaks, utility classes such as Tailwind, or hooks for your own CSS. For colors, radii, fonts and shadows, the [theme](/docs/theming) is usually the better tool.

## Usage

```tsx
<WylletProvider
  classNames={{
    panel: 'my-wallet-panel',
    island: 'my-connect-button',
    walletRow: 'my-wallet-row',
  }}
>
```

Your classes are added next to Wyllet's own classes. They do not replace them.

## Slots

| Slot | Element | Wyllet class |
| --- | --- | --- |
| `overlay` | The layer behind the panel that dims the page and closes the panel on click. | `wy-overlay` |
| `panel` | The panel container, in every presentation (drawer, popover, modal and sheet). | `wy-surface` |
| `island` | The `<WylletButton>`. | `wy-island` |
| `walletRow` | Each wallet in the connect list. | `wy-row` |
| `primaryButton` | Primary buttons inside the panel, such as "Try again" after a failed connection, "Sign to verify" in the SIWE step and the import token button. | `wy-btn-primary` |
| `identityCard` | The holographic identity card, when `appearance.identityCard` is on. | `wy-card` |
| `toast` | Each toast. | `wy-toast` |

The slot type is exported as `WylletSlot`.

`<WylletButton>` also accepts a `className` prop. It is added after `classNames.island`, so you can style one button differently from the rest.

## Tailwind

Pass utility classes as strings. Tailwind finds them by scanning your source, like any other class.

```tsx
<WylletProvider
  classNames={{
    walletRow: 'hover:translate-x-1',
    panel: 'border border-white/10',
  }}
>
```

### When a utility does not apply

Wyllet's base styles set some properties on these elements, for example `background`, `border-radius`, `box-shadow` and `font-family` on the panel and the button. A utility that sets the same property competes with Wyllet's rule, which has the same specificity and usually loads after your CSS. In Tailwind v4, utilities also live in a cascade layer, which always loses to Wyllet's unlayered styles. Either way, the utility can end up ignored.

For those properties, you have two options:

- Change the matching theme token instead, such as `colors.background`, `radii.panel`, `shadows.panel` or `fonts.body`. See [Theming](/docs/theming).
- Mark the utility as important with Tailwind's important modifier.

```tsx
<WylletProvider
  classNames={{
    // Tailwind v4: trailing !
    panel: 'shadow-2xl!',
    island: 'font-mono!',
  }}
>
```

In Tailwind v3, the modifier goes at the start instead: `!shadow-2xl`.

Properties Wyllet does not set, such as `translate` on wallet rows or `border` on the panel, apply without the modifier.

## Plain CSS

`classNames` works the same with plain CSS or CSS modules:

```css title="wallet.css"
.my-wallet-panel {
  border: 1px solid color-mix(in srgb, var(--wy-colors-accent) 40%, transparent);
}
```

Inside these elements, every theme token is available as a `--wy-*` CSS variable, so your styles can follow the active theme. See [CSS variables](/docs/theming#css-variables).

The same specificity rule applies here: properties Wyllet already sets on an element need a more specific selector, such as `.wy-surface.my-wallet-panel`, or a theme token.

The classes in the third column of the slots table are also stable, prefixed with `wy-`, and can be targeted directly from your stylesheet.

## Related

- [Theming](/docs/theming)
- [WylletButton](/docs/wyllet-button)
- [WylletProvider](/docs/provider)

---

# Translations

> Rename any string or translate the entire interface.

Source: https://wyllet.dev/docs/i18n

Every string in Wyllet's interface comes from a messages object. Pass a partial object to the `messages` prop to rename a few labels or to translate the whole interface.

## Renaming strings

Pass only the keys you want to change. Every other key keeps its English default.

```tsx
<WylletProvider
  messages={{
    connect: 'Sign in',
    connectTo: 'Sign in to {app}',
    disconnect: 'Log out',
  }}
>
```

The `label` prop on `<WylletButton>` overrides the button's disconnected text for that one button, without changing `connect` elsewhere.

## The en object

The English strings are exported as `en`, and their type as `Messages`. Use them as the reference list of keys, or as a base for your own translation.

```ts
import { en, type Messages } from 'wyllet'

console.log(Object.keys(en)) // every key Wyllet uses
```

Typing a translation as `Partial<Messages>` gives you autocomplete and catches misspelled keys. Typing it as `Messages` makes TypeScript list any key you have not translated yet.

## Placeholders

Some strings contain placeholders in curly braces, such as `{name}`. Wyllet replaces them with the actual value when it renders the string. Keep the placeholder in your translation, in whatever position the sentence needs.

| Placeholder | Value | Keys |
| --- | --- | --- |
| `{app}` | Your app name | `connectTo` |
| `{name}` | A wallet name | `continueWith`, `requesting`, `openWallet`, `scanWith`, `getWallet`, `getWalletShort`, `getWalletDescription`, `activityConnected` |
| `{name}` | The shortened address | `connectedAs` |
| `{name}` | A chain name | `activitySwitched` |
| `{network}` | The current chain name | `noTokens`, `receiveNote`, `lookingUpToken`, `notAToken` |
| `{symbol}` | A token symbol | `tokenExists`, `importAction`, `tokenImported` |
| `{query}` | The search text | `noWalletsFound`, `directoryEmpty` |
| `{count}` | Number of wallets in the directory | `directorySearch` |
| `{n}` | Minutes or hours | `minutesAgo`, `hoursAgo` |
| `{terms}`, `{privacy}` | Links built from the `terms` and `privacy` strings | `termsNotice` |

`termsNotice` is shown only when `appInfo.termsUrl` and `appInfo.privacyUrl` are both set. Wyllet turns `{terms}` and `{privacy}` into links labeled with your `terms` and `privacy` strings.

A placeholder with no value is left in the text as written.

## A Spanish example

A partial translation that covers the button, the main connect screens and the account panel:

```ts title="i18n/es.ts"
import type { Messages } from 'wyllet'

export const es: Partial<Messages> = {
  // Button
  connect: 'Conectar',
  connecting: 'Conectando',
  verify: 'Verificar',
  wrongNetwork: 'Red incorrecta',
  close: 'Cerrar',
  back: 'Atrás',

  // Connect panel
  connectTo: 'Conectar a {app}',
  continueWith: 'Continuar con {name}',
  lastUsed: 'Último usado',
  detected: 'Detectadas',
  allWallets: 'Todas las billeteras',
  searchWallets: 'Buscar billeteras…',
  noWalletsFound: 'Nada coincide con “{query}”',
  scanWithPhone: 'Escanear con el móvil',
  noWallet: 'No tengo una billetera',

  // Connecting
  requesting: 'Esperando a {name}',
  confirmInWallet: 'Aprueba la solicitud de conexión en tu billetera para continuar.',
  requestRejected: 'Solicitud rechazada',
  tryAgain: 'Reintentar',
  connected: 'Conectado',

  // Account panel
  copyAddress: 'Copiar',
  receive: 'Recibir',
  explorer: 'Explorador',
  disconnect: 'Desconectar',
  tabTokens: 'Tokens',
  tabActivity: 'Actividad',
  tabNetworks: 'Redes',
  noTokens: 'No hay saldos de tokens en {network}.',
  noActivity: 'Tu actividad aparecerá aquí.',
  minutesAgo: 'hace {n} min',
  hoursAgo: 'hace {n} h',
}
```

```tsx title="providers.tsx"
import { es } from './i18n/es'

<WylletProvider messages={es}>{children}</WylletProvider>
```

Keys you leave out fall back to English, so you can translate incrementally.

## Switching language at runtime

`messages` is a regular prop, so switching language is a matter of passing a different object:

```tsx
import { es } from './i18n/es'

const translations = { en: undefined, es }

<WylletProvider messages={translations[locale]}>{children}</WylletProvider>
```

Define translation objects outside your components, as above, so the same object is passed on every render.

Entries in the activity timeline store their text when they are created. Changing the language later does not rewrite entries that already exist.

## Related

- [WylletProvider](/docs/provider)
- [WylletButton](/docs/wyllet-button)
- [Activity](/docs/activity)

---

# Wallets

> Built-in wallets, EIP-6963 detection, custom wallets and connectors.

Source: https://wyllet.dev/docs/wallets

The wallet list is defined in code and passed to `getDefaultConfig`. Wyllet ships presets for common wallets, detects any installed browser wallet through EIP-6963, and lets you describe your own wallets with a plain object.

```tsx title="wagmi.ts"
import { burnerWallet, defaultWallets, getDefaultConfig } from 'wyllet'
import { base, mainnet } from 'viem/chains'

export const config = getDefaultConfig({
  appName: 'My dApp',
  walletConnectProjectId: process.env.NEXT_PUBLIC_WC_PROJECT_ID,
  chains: [mainnet, base],
  wallets: [...defaultWallets(), burnerWallet()],
})
```

When you leave out `wallets`, `getDefaultConfig` uses `defaultWallets()`. The order of the array is the order of the list.

## Built-in presets

Every preset is a function that returns a `Wallet`. Call it with no arguments, or pass options (see [preset options](#preset-options)).

| Preset | Name | Icon | Connects through |
| --- | --- | --- | --- |
| `metaMaskWallet()` | MetaMask | Official | Extension, or WalletConnect with a MetaMask app link |
| `phantomWallet()` | Phantom | Official | Extension |
| `rabbyWallet()` | Rabby | Official | Extension |
| `okxWallet()` | OKX Wallet | Official | Extension, or WalletConnect with an OKX app link |
| `walletConnectWallet()` | WalletConnect | Generic scan icon | WalletConnect QR code |
| `coinbaseWallet()` | Coinbase Wallet | Neutral monogram | Extension, or WalletConnect with a Coinbase Wallet app link |
| `rainbowWallet()` | Rainbow | Neutral monogram | Extension, or WalletConnect with a Rainbow app link |
| `trustWallet()` | Trust Wallet | Neutral monogram | Extension, or WalletConnect with a Trust Wallet app link |
| `browserWallet()` | Browser Wallet | Generic browser icon | The generic injected (`window.ethereum`) connector |
| `burnerWallet()` | Burner Wallet | Burner icon | A local, in-browser key (development only) |

`defaultWallets()` returns MetaMask, Phantom, Rabby, OKX Wallet and WalletConnect. These are the presets that bundle official artwork from each wallet's brand kit.

Coinbase Wallet, Rainbow and Trust Wallet do not bundle artwork. They show a neutral monogram unless the extension is installed (then the icon it announces is used) or you pass the official icon yourself:

```tsx
import { coinbaseWallet, rainbowWallet, trustWallet } from 'wyllet'

const wallets = [
  coinbaseWallet({ overrides: { icon: '/brand/coinbase-wallet.svg' } }),
  rainbowWallet({ overrides: { icon: '/brand/rainbow.svg' } }),
  trustWallet({ overrides: { icon: '/brand/trust.svg' } }),
]
```

The WalletConnect option only appears when a WalletConnect connector exists, which means a `walletConnectProjectId` is set. With a project ID it becomes the entry point to [All wallets](/docs/all-wallets). See [WalletConnect](/docs/walletconnect) for setup.

### Browser wallet

`browserWallet()` is a fallback for in-app browsers and older extensions that expose `window.ethereum` without announcing themselves through EIP-6963. You rarely need to list it: when no EIP-6963 wallet is announced and `window.ethereum` exists, Wyllet adds it to the top of the list on its own.

### Burner wallet

`burnerWallet()` is a throwaway wallet for local development and demos. It generates a private key on first use, keeps it in `localStorage`, and signs messages, typed data and transactions with it. Other RPC calls go to the chain's transport from your config.

```tsx
burnerWallet({ storageKey: 'my-app.burner' })
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `storageKey` | `string` | `'wyllet.v1.burner.key'` | `localStorage` key that holds the private key |
| `connector` | `() => CreateConnectorFn` | `burner(options)` | Replace the connector |
| `overrides` | `Partial<Wallet>` | | Override name, icon or other fields |

The connector is also exported as `burner()` for hand-written wagmi configs.

> **Warning:** The burner's private key is stored unencrypted in `localStorage`. Never send real funds to it. When it connects on a host other than `localhost`, `127.0.0.1`, `[::1]`, `0.0.0.0` or a `.local`, `.localhost` or `.test` domain, Wyllet logs a console warning. Remove it from production builds.

## The Wallet type

A preset is just a function that returns this object. You can write one by hand for any wallet.

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` | Stable id. Also used as the key for the "last used" wallet |
| `name` | `string` | Display name |
| `icon` | `string` | Image URL or data URI. Installed wallets use the icon they announce instead |
| `iconBackground` | `string` | Color shown behind transparent icons, including the logo in the QR code |
| `rdns` | `string \| readonly string[]` | EIP-6963 reverse-DNS identifier(s) used to detect the extension |
| `connectorId` | `string` | Id of a wagmi connector in your config to use for this wallet |
| `createConnector` | `() => CreateConnectorFn` | A dedicated wagmi connector (SDK wallets, embedded wallets, burner) |
| `walletConnect` | `{ mobileUri?: (uri: string) => string }` | Marks WalletConnect support. `mobileUri` builds the link that opens the app on phones |
| `downloadUrls` | `WalletDownloadUrls` | `browserExtension`, `ios`, `android` and `website` links for the "Get wallet" screen |
| `description` | `string` | Short text shown on the "Get wallet" and onboarding screens |
| `featured` | `boolean` | Default `true`. Wallets with `featured: false` are listed after the others and are left out of onboarding suggestions |

A wallet with no way to connect in the current browser and no `downloadUrls` is hidden from the list.

## How a wallet connects

When a user picks a wallet, Wyllet resolves how to connect at that moment:

1. **Installed extension.** If an EIP-6963 provider whose `rdns` matches is announced, Wyllet connects to it directly.
2. **Dedicated connector.** If the wallet has `createConnector` or a `connectorId` that matches a connector in your config, Wyllet connects with it.
3. **WalletConnect.** If the wallet has `walletConnect` and a WalletConnect connector exists, Wyllet shows a QR code on desktop. On phones it opens the link returned by `mobileUri`.
4. **Get wallet.** Otherwise Wyllet shows a "Get" screen with the wallet's download links.

### Detected wallets

Installed wallets you did not list still appear. Every wallet announced through EIP-6963 is added with the name and icon it announces. Installed and recently used wallets are grouped at the top under **Detected**, and the rest follow under **All wallets**.

## Preset options

Every preset accepts `WalletPresetOptions`:

| Option | Type | Description |
| --- | --- | --- |
| `overrides` | `Partial<Omit<Wallet, 'createConnector'>>` | Replace any field: name, icon, links, description |
| `connector` | `() => CreateConnectorFn` | Replace how the wallet connects |

For example, to connect Coinbase Wallet through its SDK (install `@coinbase/wallet-sdk` first):

```tsx
import { coinbaseWallet as coinbaseSdk } from 'wagmi/connectors'
import { coinbaseWallet } from 'wyllet'

const coinbase = coinbaseWallet({
  connector: () => coinbaseSdk({ appName: 'My dApp' }),
  overrides: { icon: '/brand/coinbase-wallet.svg' },
})
```

## Custom wallets

Describe any wallet with a `Wallet` object and add it to the list.

```tsx title="wallets.ts"
import type { Wallet } from 'wyllet'
import { defaultWallets } from 'wyllet'

const acme: Wallet = {
  id: 'acme',
  name: 'Acme Wallet',
  icon: 'https://acme.xyz/icon.png',
  rdns: 'xyz.acme',
  walletConnect: { mobileUri: (uri) => `acme://wc?uri=${encodeURIComponent(uri)}` },
  downloadUrls: {
    browserExtension: 'https://acme.xyz/download',
    ios: 'https://apps.apple.com/app/acme/id000000000',
  },
  description: 'The Acme self-custody wallet.',
}

export const wallets = [acme, ...defaultWallets()]
```

With this definition, Acme connects directly when its extension is installed, shows a QR code on desktop, opens the Acme app on phones, and falls back to the download links.

## Hand-written wagmi configs

If you build the config with wagmi's `createConfig`, pass the list to the provider instead. Wallets match connectors by `connectorId` or `rdns`, so add any dedicated connectors to your config yourself.

```tsx
import { burner, burnerWallet, defaultWallets, WylletProvider } from 'wyllet'
import { createConfig, http, injected } from 'wagmi'
import { mainnet } from 'viem/chains'

const config = createConfig({
  chains: [mainnet],
  transports: { [mainnet.id]: http() },
  connectors: [injected(), burner()],
})

// Inside WagmiProvider and QueryClientProvider:
<WylletProvider wallets={[...defaultWallets(), burnerWallet()]} appInfo={{ name: 'My dApp' }}>
  {children}
</WylletProvider>
```

For QR codes and mobile wallets with a hand-written config, see [WalletConnect](/docs/walletconnect#hand-written-configs).

## Keyboard

The connect list is built for the keyboard:

| Key | Action |
| --- | --- |
| `↑` / `↓` | Move through the list (wraps around) |
| `Enter` | Connect the highlighted wallet |
| `1`–`9` | Connect the wallet at that position |

Number keys work while the search field is empty and no modifier key is held. If any wallet's name starts with that digit, the keystroke goes to search instead.

The last wallet the user connected with appears at the top as **Continue with** followed by its name, and it is always position `1`. It is hidden while searching. Wyllet remembers the three most recent wallets in `localStorage`.

A search field appears when `appearance.walletSearch` is `true`, or when it is `'auto'` (the default) and the list has six or more wallets. To open the panel from anywhere with a shortcut such as `mod+k`, set the `shortcut` prop on [WylletProvider](/docs/provider).

---

# All wallets

> The searchable WalletConnect directory with official logos and per-wallet app links.

Source: https://wyllet.dev/docs/all-wallets

**All wallets** is a searchable grid of the wallets listed in the WalletConnect registry. Each entry uses the logo and app link the wallet submitted to the registry, so a user can pick their exact wallet instead of scanning a generic code.

## When it appears

All wallets replaces the plain WalletConnect option in the connect list when all of these are true:

- A WalletConnect project ID is configured (`walletConnectProjectId` on `getDefaultConfig`, or on `WylletProvider` for hand-written configs).
- A WalletConnect connector exists in the wagmi config.
- `appearance.walletDirectory` is not `false` (it defaults to `true`).

The row reads **All wallets** with the subtitle "Hundreds of wallets via WalletConnect". Picking it opens the directory instead of a QR code. See [WalletConnect](/docs/walletconnect) for getting a project ID.

## What it shows

- **EVM wallets only.** Listings that declare chains but no `eip155:` chain are filtered out. Listings without a logo are skipped.
- **Search.** The field searches the registry by name. Its placeholder shows the registry's total count, around 570 wallets at the time of writing.
- **Pages of 40.** The first 40 wallets load when the view opens. **Show more** loads the next page.
- **Official logos.** Logos come from the registry, as submitted by each wallet.

If the list fails to load, the view shows "Couldn't load the wallet list." with a **Retry** button.

## What happens when a user picks a wallet

| Situation | Result |
| --- | --- |
| The wallet's extension is installed (its registry `rdns` matches an EIP-6963 provider) | Connects directly to the extension |
| Desktop | A QR code with the wallet's logo in the center, to scan from inside that wallet's app |
| Phone, and the wallet has a mobile link | Opens that exact app with the WalletConnect request |
| Phone, and the wallet has no mobile link | Shows the "Get" screen with the wallet's store, extension or website links |

The QR screen also has **Copy link** and, when the registry lists download links, a **Get** button for that wallet. On desktop, the directory has a **Use a generic QR code** button at the bottom for wallets that are not listed.

### Mobile links

On phones Wyllet builds the link the same way Reown's own modal does, so every registry wallet opens as its developers expect:

- If the wallet has a universal link, Wyllet opens `UNIVERSAL_LINK/wc?uri=ENCODED_URI`.
- Otherwise, if it has a native scheme, Wyllet opens `SCHEME://wc?uri=ENCODED_URI`.

A wallet without either link is not sent a bare `wc:` link, because on a phone that opens whichever wallet the operating system picks. The user sees the install screen instead. [WalletConnect](/docs/walletconnect#mobile-links) explains the bare-link problem in more detail.

## Network requests

The directory is the only network request Wyllet makes on its own. It calls the WalletConnect registry at `https://explorer-api.walletconnect.com/v3/wallets` with your project ID, and only when a user opens All wallets. Logos load from the URLs the registry returns. Each page and search result is cached in memory until the page reloads. Failed requests are not cached, so **Retry** really retries.

If your site has a Content Security Policy, allow `https://explorer-api.walletconnect.com` in `connect-src` and the registry's logo host in `img-src`.

## Turning it off

```tsx
<WylletProvider appearance={{ walletDirectory: false }}>
  {children}
</WylletProvider>
```

With the directory off, the WalletConnect option shows a generic QR code on desktop. On phones it is labeled "Other wallet app" and opens the default wallet app. Your other wallets, including presets with their own mobile links, are not affected.

---

# WalletConnect

> Project IDs, domain allowlists, QR codes and how mobile app links work.

Source: https://wyllet.dev/docs/walletconnect

WalletConnect lets users connect a mobile wallet by scanning a QR code on desktop, or by opening the wallet app on a phone. It is optional. Without it, Wyllet still connects browser extensions and any dedicated connectors.

## Setup

### 1. Get a project ID

Create a free project at [cloud.reown.com](https://cloud.reown.com) and copy its project ID.

### 2. Install the provider

`@walletconnect/ethereum-provider` is an optional peer dependency, so you choose and pin its version.

```bash
pnpm add @walletconnect/ethereum-provider
```

### 3. Pass the project ID

```tsx title="wagmi.ts"
import { getDefaultConfig } from 'wyllet'
import { base, mainnet } from 'viem/chains'

export const config = getDefaultConfig({
  appName: 'My dApp',
  appDescription: 'Trade on Base',
  appIcon: 'https://mydapp.xyz/icon.png',
  walletConnectProjectId: process.env.NEXT_PUBLIC_WC_PROJECT_ID,
  chains: [mainnet, base],
})
```

`getDefaultConfig` adds wagmi's `walletConnect` connector with Wyllet's own QR screen (`showQrModal: false`). Wallets see your `appName`, `appDescription` (defaults to `appName`), `appUrl` (defaults to `window.location.origin`) and `appIcon` when they connect.

The connector is only added when at least one wallet in your list supports WalletConnect. `defaultWallets()` includes `walletConnectWallet()`, so the default list always does.

### 4. Allow your domains

In Reown Cloud, add every domain that serves your dApp (production, staging and preview hosts) to the project's allowed domains. Connections from a domain that is not on the list fail, even though the same code works locally.

## Hand-written configs

If you create the wagmi config yourself, add the connector and pass the project ID to the provider so Wyllet can open [All wallets](/docs/all-wallets).

```tsx
import { createConfig, http, injected } from 'wagmi'
import { walletConnect } from 'wagmi/connectors'
import { mainnet } from 'viem/chains'

const projectId = process.env.NEXT_PUBLIC_WC_PROJECT_ID!

const config = createConfig({
  chains: [mainnet],
  transports: { [mainnet.id]: http() },
  connectors: [
    injected(),
    walletConnect({
      projectId,
      showQrModal: false,
      metadata: { name: 'My dApp', description: 'My dApp', url: 'https://mydapp.xyz', icons: [] },
    }),
  ],
})

// Inside WagmiProvider and QueryClientProvider:
<WylletProvider walletConnectProjectId={projectId} appInfo={{ name: 'My dApp' }}>
  {children}
</WylletProvider>
```

Keep `showQrModal: false`, or WalletConnect's own modal opens on top of Wyllet's.

## How connections work

### QR codes on desktop

On desktop, picking a WalletConnect wallet shows a QR code. When the user picked a specific wallet such as MetaMask, the code carries that wallet's logo and the screen says to open that app and tap its scan button. The footer's **Scan with phone** button and the generic WalletConnect option show a plain code for any wallet. Every QR screen has a **Copy link** button.

### Mobile links

On a phone there is nothing to scan. Wyllet requests a WalletConnect URI and sends the user to the wallet with the link from that wallet's `mobileUri`. For example, `metaMaskWallet()` opens `https://metamask.app.link/wc?uri=` followed by the encoded URI. The connecting screen also shows an **Open** button with the same link, in case the browser blocked the redirect.

The plain `walletConnectWallet()` option has no app of its own, so its mobile link is the bare `wc:` URI. A bare link opens whichever wallet app the operating system picks, and iOS shows no chooser. That is why, on phones, the plain option is labeled **Other wallet app** with the note "Opens your default wallet app".

[All wallets](/docs/all-wallets) solves this. With a project ID, the WalletConnect option opens the registry directory, where every wallet has its own universal or native link. Picking a wallet there opens that exact app. Wallets with no mobile link show an install screen instead of a bare link.

Inside a wallet's in-app browser, the wallet injects a provider, so Wyllet connects to it directly without WalletConnect.

## Troubleshooting

**The WalletConnect option and "Scan with phone" are missing.** No WalletConnect connector exists. Check that `walletConnectProjectId` is set and not `undefined` at build time, and that at least one wallet in `wallets` has a `walletConnect` field.

**A module-not-found error for `@walletconnect/ethereum-provider`.** Install the package. wagmi's connector loads it when WalletConnect is configured.

**Connecting works locally but fails in production.** Add the production domain to the project's allowed domains in Reown Cloud.

**On a phone, the wrong wallet opens.** The user picked the plain WalletConnect option, which uses a bare `wc:` link. Keep `appearance.walletDirectory` enabled so the option opens All wallets, or list presets with their own app links.

**All wallets does not appear.** With a hand-written config, pass `walletConnectProjectId` to `WylletProvider`. Also check that `appearance.walletDirectory` is not `false`.

**All wallets shows "Couldn't load the wallet list."** The request to `explorer-api.walletconnect.com` failed. Check your Content Security Policy and any network filters, then use **Retry**.

**The QR code keeps loading.** Wyllet is waiting for a URI from WalletConnect. Check the browser console for errors from the WalletConnect provider, such as an invalid project ID.

---

# Chains

> popularChains, customChain() and arranging the Networks tab with chainOrder.

Source: https://wyllet.dev/docs/chains

Networks are defined in code, so every user sees the same set in the order you choose. Mix Wyllet's presets, any chain from `viem/chains`, and your own chains built with `customChain()`.

```tsx title="wagmi.ts"
import { sepolia } from 'viem/chains'
import { customChain, getDefaultConfig, popularChains } from 'wyllet'

const myChain = customChain({
  id: 424242,
  name: 'My Chain',
  rpcUrl: 'https://rpc.mychain.xyz',
  explorerUrl: 'https://scan.mychain.xyz',
  nativeCurrency: { name: 'My Token', symbol: 'MYT', decimals: 18 },
  icon: '/mychain.svg',
  nativeIcon: '/myt.svg',
})

export const config = getDefaultConfig({
  appName: 'My dApp',
  chains: [myChain, ...popularChains, sepolia],
})
```

## Chain order

The order of `chains` is the priority order, and the first chain is the default. The Networks tab lists chains in the same order unless you set `chainOrder` (see [below](#arranging-the-networks-tab)).

`getDefaultConfig` uses each chain's public RPC by default. Use your own RPC in production with `transports`:

```tsx
import { http } from 'wagmi'

getDefaultConfig({
  appName: 'My dApp',
  chains: [mainnet, base],
  transports: { [base.id]: http('https://base.my-rpc.xyz') },
})
```

Chains you leave out of `transports` keep the public RPC.

## Presets

`popularChains` and `popularTestnets` are arrays of viem chains, ready to spread into `chains`.

| Preset | Chains, in order |
| --- | --- |
| `popularChains` | Ethereum, Base, OP Mainnet, Arbitrum One, Polygon, BNB Smart Chain, Avalanche, ZKsync Era, Linea Mainnet, Scroll |
| `popularTestnets` | Sepolia, Base Sepolia, OP Sepolia, Arbitrum Sepolia, Polygon Amoy |

Spread a preset and add to it, or pick individual chains from `viem/chains` instead. Nothing in Wyllet requires the presets.

## Custom chains

`customChain()` defines any EVM chain in one call, such as your own L2, an appchain or a devnet. It returns a viem `Chain` that works anywhere wagmi and viem expect one, and it carries Wyllet's icon metadata.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `number` | Yes | Chain ID |
| `name` | `string` | Yes | Display name |
| `rpcUrl` | `string` | Yes | HTTPS JSON-RPC endpoint |
| `nativeCurrency` | `{ name: string; symbol: string; decimals: number }` | No | Defaults to Ether, `ETH`, 18 decimals |
| `explorerUrl` | `string` | No | Block explorer base URL. Enables explorer links for addresses and transactions |
| `testnet` | `boolean` | No | Shows a Testnet tag in the Networks tab |
| `icon` | `string` | No | Chain logo URL or data URI |
| `color` | `string` | No | Brand color for the generated monogram. Setting it skips the built-in icon for that chain ID |
| `nativeIcon` | `string` | No | Icon for the native currency in the Tokens tab |

Wyllet stores `icon`, `color` and `nativeIcon` on the chain under `custom.wyllet` (the `ChainExtras` type). You can add the same field to a viem chain to give it a native currency icon:

```tsx
import { base } from 'viem/chains'

const baseWithIcons = { ...base, custom: { wyllet: { nativeIcon: '/eth.svg' } } }
```

## Chain icons

Wyllet bundles official logos for these networks and their testnets: Ethereum (including Sepolia and Holesky), OP, Arbitrum, Base, Polygon, Avalanche, ZKsync, Linea, Scroll, Gnosis, Zora and Blast. Local dev chains with ID `31337` (Hardhat, Anvil) get a generic developer mark.

Any other chain gets a monogram: the first letter of its name on a color derived from the name. This includes BNB Smart Chain, which is in `popularChains` but has no bundled artwork.

Icons resolve in this order:

1. The `chainIcons` prop on `WylletProvider`
2. `icon` from `customChain()`
3. The built-in logo for the chain ID
4. A monogram, using `color` when you set one

Override any chain's icon by ID with `chainIcons`:

```tsx
<WylletProvider chainIcons={{ 56: '/brand/bnb.svg', 424242: '/mychain.svg' }}>
  {children}
</WylletProvider>
```

## Arranging the Networks tab

`chainOrder` moves chain IDs to the front of the Networks tab, in the order given. The remaining chains follow in config order. It does not change the default chain.

```tsx
<WylletProvider chainOrder={[8453, 424242]}>
  {children}
</WylletProvider>
```

This shows Base, then My Chain, then everything else.

## Switching networks

The Networks tab switches with wagmi's `switchChain`. If an injected wallet reports that it does not know the chain, wagmi asks it to add the network using the name, RPC URL, explorer and native currency from your chain definition. The user approves the new network in their wallet, and the switch continues. No extra setup is needed for custom chains.

When the wallet is on a chain that is not in your config, Wyllet shows the wrong-network state. See [Account panel](/docs/account-panel#wrong-network).

## useWylletChains

Returns your configured chains, arranged by `chainOrder`. Use it to build your own network picker.

```tsx
import { ChainIcon, useWylletChains } from 'wyllet'
import { useSwitchChain } from 'wagmi'

function NetworkList() {
  const { chains } = useWylletChains()
  const { mutate: switchChain } = useSwitchChain()
  return chains.map((chain) => (
    <button key={chain.id} onClick={() => switchChain({ chainId: chain.id })}>
      <ChainIcon chainId={chain.id} size={20} />
      {chain.name}
    </button>
  ))
}
```

## ChainIcon

Renders a chain's icon as an `img`, using the resolution order above. It must be rendered inside `WylletProvider`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `chainId` | `number` | | Chain to show |
| `size` | `number` | `20` | Width and height in pixels |
| `className` | `string` | | Extra class name |

The image's `alt` text is the chain name when the chain is in your config.

---

# Tokens

> Token lists, withDefaultTokens, pinning, sorting and user token import.

Source: https://wyllet.dev/docs/tokens

The Tokens tab in the account panel shows the native balance of the connected chain, followed by the ERC-20 tokens you list for that chain. You define the list in code, so every user sees the same tokens in the same order.

## The tokens prop

Set `tokens` on `WylletProvider`:

| Value | Result |
| --- | --- |
| `'default'` | Wyllet's blue-chip list (`defaultTokens`). This is the default |
| `false` | Native balance only |
| `TokenEntry[]` | Only your tokens, as a flat list with `chainId` on each entry |
| `TokenList` | Only your tokens, as a map of chain ID to `Token[]` |

```tsx
<WylletProvider
  tokens={[
    { chainId: 8453, address: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913', symbol: 'USDC', decimals: 6, pinned: true },
    { chainId: 8453, address: '0x4200000000000000000000000000000000000006', symbol: 'WETH', decimals: 18 },
  ]}
>
  {children}
</WylletProvider>
```

The same list as a `TokenList`:

```tsx
const tokens: TokenList = {
  8453: [
    { address: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913', symbol: 'USDC', decimals: 6, pinned: true },
    { address: '0x4200000000000000000000000000000000000006', symbol: 'WETH', decimals: 18 },
  ],
}
```

`toTokenList()` converts a flat `TokenEntry[]` into a `TokenList` if you need the map form.

### Default tokens

`defaultTokens` covers five chains:

| Chain | Tokens |
| --- | --- |
| Ethereum (1) | USDC, USDT, DAI, WETH, WBTC |
| Base (8453) | USDC, WETH, DAI |
| OP Mainnet (10) | USDC, USDT, WETH, OP |
| Arbitrum One (42161) | USDC, USDT, WETH, ARB |
| Polygon (137) | USDC, USDT, WETH |

Other chains show only the native balance unless you list tokens for them.

### Adding to the defaults

`withDefaultTokens()` puts your tokens first, then the default tokens for each chain, with duplicate addresses removed.

```tsx
import { withDefaultTokens } from 'wyllet'

const tokens = withDefaultTokens([
  { chainId: 8453, address: '0x...', symbol: 'MYTKN', decimals: 18, icon: '/mytkn.svg', pinned: true },
  { chainId: 424242, address: '0x...', symbol: 'USDC', decimals: 6 },
])

<WylletProvider tokens={tokens}>{children}</WylletProvider>
```

It accepts a `TokenEntry[]` or a `TokenList` and returns a `TokenList`.

## Token fields

| Field | Type | Description |
| --- | --- | --- |
| `address` | `Address` | Contract address |
| `symbol` | `string` | Symbol shown in the list |
| `decimals` | `number` | Token decimals, used to format balances |
| `name` | `string` | Optional. Shown under the symbol |
| `icon` | `string` | Optional. Image URL or data URI. Falls back to a built-in icon, then a monogram |
| `pinned` | `boolean` | Optional. Always show this token at the top, regardless of balance |

A `TokenEntry` is a `Token` plus `chainId: number`.

## Ordering

List order is the display order. `pinned: true` keeps a token at the top, and pinned tokens keep their list order among themselves. `appearance.tokenSort` decides the rest:

| Value | Order |
| --- | --- |
| `'balance'` (default) | Pinned tokens, then tokens the user holds, then the rest. Each group stays in list order |
| `'list'` | Pinned tokens, then every other token in exactly your list order |

The native balance is always the first row. Tokens with a zero balance are dimmed.

## Add to wallet

Every ERC-20 row has an **Add to wallet** button. It asks the connected wallet to track the token (`wallet_watchAsset` through wagmi), passing the address, symbol, decimals and your `icon` when one is set.

## User token import

Set `allowTokenImport` to let each user add their own ERC-20s.

```tsx
<WylletProvider allowTokenImport>{children}</WylletProvider>
```

The Tokens tab then shows an **Import token** button when the user is on a configured chain. The user pastes a contract address, and Wyllet reads the token's `name`, `symbol`, `decimals` and the user's balance onchain. A contract without a readable symbol and decimals is rejected, as is an address already in the list.

Imported tokens:

- Are saved in the user's browser (`localStorage`), per chain. They are not sent anywhere.
- Appear after your listed tokens with a **Custom** tag, and follow the same `tokenSort` rules.
- Can be removed with the remove button on their row.
- Only show while `allowTokenImport` is `true`.

## useWylletTokens

Returns the token list for a chain: your configured tokens in list order, followed by the user's imported tokens. It defaults to the connected chain.

```tsx
import { useWylletTokens } from 'wyllet'

const { tokens, importToken, removeToken, canImport } = useWylletTokens()
const onBase = useWylletTokens(8453)
```

| Field | Type | Description |
| --- | --- | --- |
| `tokens` | `ListedToken[]` | Configured tokens, then imported ones. Imported tokens have `custom: true` |
| `importToken` | `(token: Token, chainId?: number)` | Save a token for the user. Defaults to the hook's chain |
| `removeToken` | `(address: string, chainId?: number)` | Remove an imported token |
| `canImport` | `boolean` | The value of `allowTokenImport` |

`tokens` is not sorted by balance. The Tokens tab applies `tokenSort` on top of it.

## TokenIcon

Renders a token logo with an optional chain badge in the corner.

```tsx
import { TokenIcon } from 'wyllet'

<TokenIcon symbol="USDC" chainId={8453} size={28} />
```

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `symbol` | `string` | | Token symbol. Picks the built-in icon and the alt text |
| `src` | `string` | | Custom icon URL. If it fails to load, the built-in icon is used |
| `chainId` | `number` | | Draws a small `ChainIcon` badge for this chain |
| `size` | `number` | `32` | Width and height in pixels |
| `className` | `string` | | Extra class name |

Built-in icons cover ETH, WETH, USDC, USDT, DAI, WBTC, LINK, UNI, OP, ARB, POL, MATIC and AVAX. Any other symbol, including BNB, gets a monogram. `tokenIconUri(symbol)` returns the same icon as a data URI.

---

# Account panel

> Account summary, identity card, tokens, activity, networks and receive.

Source: https://wyllet.dev/docs/account-panel

Once a user is connected, the panel shows their account: who they are, quick actions, and tabs for tokens, activity and networks. It opens when they click the connected [WylletButton](/docs/wyllet-button), or when you open it from code.

## Layout

From top to bottom, the account view has:

- A header with the current network chip and a close button. Clicking the chip jumps to the Networks tab.
- The account summary, or the identity card when `identityCard` is on.
- Quick actions: Receive, Explorer and Disconnect (plus Copy with the identity card).
- The tabs set by `accountTabs`. Only the tab content scrolls. The summary and tabs stay in place.
- A "Powered by Wyllet" badge, unless `appearance.branding` is `false`.

## Account summary

By default the top of the panel is a compact summary: the user's avatar, their ENS name or shortened address, and their native balance on the current chain. Clicking the name copies the full address.

ENS names and avatars are resolved on Ethereum mainnet. They only load when mainnet is in your config and the `ens` prop is not `false`.

## Identity card

Set `appearance.identityCard` to replace the summary with a generative holographic card. Its colors are derived from the address, so every address gets its own card. The card shows the avatar, the current network, the native balance, the ENS name when there is one, and the shortened address.

```tsx
<WylletProvider appearance={{ identityCard: true, cardTilt: true }}>
  {children}
</WylletProvider>
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `identityCard` | `boolean` | `false` | Show the identity card instead of the compact summary |
| `cardTilt` | `boolean` | `true` | 3D tilt and a light sheen that follow the pointer |

Tilt is not applied to touch input, and it is off when `appearance.disableAnimations` is `true`. Add classes to the card with the `identityCard` slot in [class names](/docs/class-names).

## Quick actions

| Action | What it does |
| --- | --- |
| Copy | Copies the address. Shown as a button with the identity card. In the compact summary, click the name instead |
| Receive | Opens a QR code of the user's address, the full address, a copy button and a note to only send assets on the current network |
| Explorer | Opens the address on the current chain's block explorer. Hidden when the chain has no explorer |
| Disconnect | Disconnects the wallet and closes the panel. With an [auth adapter](/docs/siwe), it also signs the user out |

## Tabs

`appearance.accountTabs` sets which tabs appear and in what order. The default is all three.

```tsx
<WylletProvider appearance={{ accountTabs: ['activity', 'tokens'] }}>
  {children}
</WylletProvider>
```

Pass an empty array to hide the tabs and show only the summary and quick actions.

### Tokens

The native balance followed by your token list for the connected chain, with balances read onchain. See [Tokens](/docs/tokens) for lists, pinning, sorting, user import and the **Add to wallet** button.

### Activity

The account's timeline: transactions, connects, disconnects, network switches, sign-ins and your own entries, grouped by day. Transaction entries link to the block explorer. **Clear** removes the current account's entries. See [Activity and transactions](/docs/activity).

### Networks

A grid of your configured chains, arranged by `chainOrder`. The current chain is checked. Clicking another chain asks the wallet to switch, and the panel shows "Approve in wallet" while it waits. If the wallet cannot switch, the tab says so. Testnets get a Testnet tag.

Above the grid, a live gas price for the current chain is shown in gwei. It refreshes every 12 seconds.

See [Chains](/docs/chains) for ordering, icons and how wallets add unknown networks.

## Wrong network

When the wallet is on a chain that is not in your config:

- The button shows "Wrong network". Clicking it opens the account panel on the Networks tab.
- The header's network chip shows a warning and "Wrong network".
- The panel switches to the Networks tab (unless `accountTabs` is empty), with the message "This app doesn't support your current network. Pick one below."

Use [ConnectGate](/docs/connect-gate) to hide parts of your own UI until the user is on a supported network.

## Opening the panel from code

`useWyllet()` controls the panel from anywhere inside `WylletProvider`.

```tsx
import { useWyllet } from 'wyllet'

function Toolbar() {
  const { openAccount, openTab, isConnected } = useWyllet()
  return (
    <>
      <button disabled={!isConnected} onClick={(e) => openTab('activity', { anchor: e.currentTarget })}>
        Activity
      </button>
      <button disabled={!isConnected} onClick={() => openAccount({ tab: 'networks' })}>
        Networks
      </button>
    </>
  )
}
```

| Function | Description |
| --- | --- |
| `open(view?, options?)` | Opens `'account'` when connected and `'connect'` otherwise, unless you pass a view |
| `openAccount(options?)` | Opens the account view |
| `openTab(tab, options?)` | Opens the account view on `'tokens'`, `'activity'` or `'networks'` |
| `close()` | Closes the panel |

`options` is `{ anchor?: Element | null; tab?: AccountTab }`. Pass `anchor` so the [popover presentation](/docs/presentations) anchors to your element. If you ask for a tab that is not in `accountTabs`, the first configured tab is shown. The account view only renders while a wallet is connected.

See [Hooks](/docs/hooks) for everything `useWyllet()` returns.

---

# Activity and transactions

> Track transactions and log custom events in the activity timeline.

Source: https://wyllet.dev/docs/activity

Every connected account gets an activity timeline in the account panel's Activity tab. Wyllet records connects, network switches and sign-ins on its own. You add transactions, which are tracked live, and any custom entries you want.

## Tracking a transaction

Call `addTransaction` with the hash as soon as you have it:

```tsx
import { useWriteContract } from 'wagmi'
import { useWylletActivity } from 'wyllet'

function MintButton() {
  const { writeContractAsync } = useWriteContract()
  const { addTransaction } = useWylletActivity()

  async function mint() {
    const hash = await writeContractAsync({ address, abi, functionName: 'mint', args: [1n] })
    addTransaction({ hash, description: 'Mint 1 NFT' })
  }

  return <button onClick={mint}>Mint</button>
}
```

Wyllet then:

1. Adds a pending entry to the timeline, titled with your `description`.
2. Shows a "Transaction pending" toast with the description and a **View** link to the block explorer (when the chain has one).
3. Waits for the receipt and updates the entry and the toast to "Transaction confirmed" or "Transaction failed".

A reverted transaction, or an error while waiting, is marked failed.

### addTransaction

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `hash` | `Hash` | | Transaction hash |
| `description` | `string` | Shortened hash | Entry title and toast description |
| `chainId` | `number` | Connected chain | Chain the transaction was sent on |
| `account` | `Address` | Connected account | Account the entry belongs to |
| `toast` | `boolean` | `true` | Set `false` to track without toasts |

It returns `true` when the transaction is tracked, and `false` when no account or chain is known. Pass `account` and `chainId` explicitly if the wallet might disconnect before you call it.

Calling it again with the same hash replaces the earlier entry instead of adding a second one.

### Reloads and timeouts

- **After a reload.** When the provider mounts, Wyllet resumes watching transactions that are still pending and less than 24 hours old. These resumed watches update the timeline without toasts.
- **After 30 minutes.** If no receipt arrives within 30 minutes, Wyllet stops watching and dismisses the pending toast. The entry stays pending, because the transaction may still be mined or may have been dropped. It is not marked failed.

## Custom entries

`log` adds your own entry to the current account's timeline.

```tsx
const { log } = useWylletActivity()

log({ title: 'Staked 10 ETH', status: 'success' })
log({ title: 'Joined the allowlist', description: 'Season 2' })
```

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | | Entry title |
| `description` | `string` | | Optional detail |
| `status` | `'pending' \| 'success' \| 'failed' \| 'info'` | `'info'` | Sets the entry's icon |
| `account` | `Address` | Connected account | Account the entry belongs to |

The entry is tagged with the connected chain. `log` returns `false` when no account is known, and `true` otherwise. It does not show a toast. Use [toasts](/docs/toasts) for that.

## Automatic entries

| Event | Entry |
| --- | --- |
| Connect | "Connected" followed by the connector name. Restored sessions after a reload are not logged |
| Disconnect | "Disconnected", on the account that was connected |
| Network switch | "Switched to" followed by the chain name |
| Sign-in | "Signed in", after a successful [SIWE](/docs/siwe) step in the panel |

All titles come from the [messages](/docs/i18n) object, so you can rename or translate them.

## useWylletActivity

```tsx
const { activity, addTransaction, log, clearActivity } = useWylletActivity()
```

| Field | Type | Description |
| --- | --- | --- |
| `activity` | `ActivityItem[]` | Entries for the connected account, newest first. Empty when disconnected |
| `addTransaction` | `(tx) => boolean` | Track a transaction |
| `log` | `(entry) => boolean` | Add a custom entry |
| `clearActivity` | `() => void` | Remove every entry for the connected account |

## ActivityItem

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` | Unique id. For transactions, the hash |
| `kind` | `'transaction' \| 'connect' \| 'disconnect' \| 'network' \| 'signIn' \| 'custom'` | Entry type (`ActivityKind`) |
| `title` | `string` | Entry title |
| `description` | `string` | Optional detail |
| `status` | `'pending' \| 'success' \| 'failed' \| 'info'` | Current status (`ActivityStatus`) |
| `account` | `Address` | Account the entry belongs to, lower-cased |
| `chainId` | `number` | Optional chain |
| `hash` | `Hash` | Transaction hash, for transactions |
| `timestamp` | `number` | Creation time in milliseconds |

## Storage

The timeline is stored in the browser's `localStorage` under `wyllet.v1.activity`. Each account keeps its newest 50 entries, and older ones are dropped. Entries never leave the browser. Stored data is validated when it is read, so malformed entries are ignored.

---

# Toasts

> Themed, promise-aware notifications with useWylletToast.

Source: https://wyllet.dev/docs/toasts

Wyllet includes a themed toast system. It is the same one used for transaction updates, so your own notifications match. Toasts render in a portal at the edge of the screen and follow your [theme](/docs/theming).

```tsx
import { useWylletToast } from 'wyllet'

function SaveButton() {
  const toast = useWylletToast()
  return <button onClick={() => toast.success('Saved', { description: 'Your settings were updated.' })}>Save</button>
}
```

## The toast API

`useWylletToast()` returns a function with helper methods attached.

| Call | Returns | Description |
| --- | --- | --- |
| `toast(options)` | `string` | Show a toast with full `ToastOptions`. Returns its id |
| `toast.success(title, options?)` | `string` | Success toast |
| `toast.error(title, options?)` | `string` | Error toast |
| `toast.loading(title, options?)` | `string` | Loading toast with a spinner. It stays until you update or dismiss it |
| `toast.update(id, options)` | `void` | Change an existing toast in place. Does nothing if the id is not showing |
| `toast.dismiss(id?)` | `void` | Dismiss one toast, or all toasts when called without an id |
| `toast.promise(promise, messages)` | `Promise` | Loading toast that turns into success or error with the promise |

The helpers take the same options as `toast()`, without `title` and `status`.

### Promises

`toast.promise` shows `messages.loading` until the promise settles, then replaces it with `messages.success` or `messages.error`. Both can be functions that receive the resolved value or the error. It returns the promise's value, and rethrows its error, so you can keep using the result.

```tsx
const receipt = await toast.promise(bridge(amount), {
  loading: 'Bridging to Base...',
  success: (r) => `Bridged ${r.amount} ETH`,
  error: (e) => (e instanceof Error ? e.message : 'Bridge failed'),
})
```

### Updating a toast

Pass an `id` to reuse a toast instead of stacking a new one. Calling `toast()` with an id that is already showing updates it.

```tsx
const id = toast.loading('Uploading...')
try {
  await upload(file)
  toast.update(id, { status: 'success', title: 'Uploaded' })
} catch {
  toast.update(id, { status: 'error', title: 'Upload failed' })
}
```

## ToastOptions

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `ReactNode` | | Main text. Required for `toast()` |
| `description` | `ReactNode` | | Secondary text |
| `status` | `'info' \| 'success' \| 'error' \| 'loading'` | `'info'` | Icon and color |
| `duration` | `number` | `4500`, or `7000` for errors | Milliseconds before it closes. `Infinity` keeps it open |
| `action` | `{ label: ReactNode; href?: string; onClick?: () => void }` | | A button, or a link when `href` is set |
| `id` | `string` | Generated | Reuse an id to update a toast in place |

Loading toasts never close on their own, whatever the `duration`. Every toast has a close button. An `action` with `href` opens in a new tab.

```tsx
toast({
  status: 'success',
  title: 'Order filled',
  description: '2.4 ETH at 3,120 USDC',
  action: { label: 'View', href: 'https://basescan.org/tx/0x...' },
  duration: 10_000,
})
```

At most six toasts are kept at once. Showing a seventh drops the oldest.

## Position

Set `appearance.toastPosition`:

```tsx
<WylletProvider appearance={{ toastPosition: 'bottom-right' }}>
  {children}
</WylletProvider>
```

| Value | Notes |
| --- | --- |
| `'top-center'` | Default |
| `'top-left'`, `'top-right'` | Top corners |
| `'bottom-left'`, `'bottom-center'`, `'bottom-right'` | Bottom edge |

## Styling

Add your own classes to every toast with the `toast` slot:

```tsx
<WylletProvider classNames={{ toast: 'shadow-xl' }}>
  {children}
</WylletProvider>
```

Toasts respect `appearance.disableAnimations` and the user's reduced-motion setting. Error toasts are announced to screen readers as alerts, and the rest as status messages. See [Class names](/docs/class-names) and [Theming](/docs/theming) for more.

---

# Sign-In With Ethereum

> Add a SIWE verification step to the connect flow with an auth adapter.

Source: https://wyllet.dev/docs/siwe

Sign-In With Ethereum (EIP-4361) proves that the user controls the connected address. Pass an auth adapter to `WylletProvider` and Wyllet adds a sign-in step to the connect flow. Your backend issues the nonce, verifies the signature and owns the session.

## How it works

1. The user connects a wallet.
2. Before the panel closes, Wyllet shows a sign-in step ("Prove it's you") with a **Sign to verify** button.
3. On click, Wyllet calls `getNonce()`, builds a SIWE message, and asks the wallet to sign it. Signing is free and sends no transaction.
4. Wyllet passes the message and signature to `verify()`. If it returns `true`, the user is signed in and the panel closes.

**Not now** on the sign-in step disconnects the wallet and closes the panel. If `verify()` returns `false` or throws, the step shows "Verification failed" and the user can try again.

A session belongs to one address. Wyllet calls `signOut()` and clears the session when the wallet disconnects, when the user switches to another account, or when they press Disconnect in the account panel. If a restored session belongs to a different address than the connected one, Wyllet signs it out.

While a connected user is not signed in, the button reads "Verify" and opens the sign-in step.

## The adapter

```ts
import type { WylletAuthAdapter } from 'wyllet'
```

| Method | Required | Description |
| --- | --- | --- |
| `getNonce()` | Yes | Fetch a fresh nonce from your backend. Returns `Promise<string>` |
| `verify(args)` | Yes | Verify the signature on your backend and start a session. Receives `{ message, signature, address, chainId }`. Returns `Promise<boolean>` |
| `signOut()` | Yes | End the session. Returns `Promise<void>`. Errors are ignored and the local session is cleared anyway |
| `getSession()` | No | Restore an existing session on page load. Returns `Promise<{ address } \| null>` |
| `createMessage(args)` | No | Build your own message. Receives `{ address, chainId, nonce, domain, uri }` and returns a string |
| `statement` | No | A human-readable statement inserted in the default message |

By default the message is built with `createSiweMessage` from `viem/siwe`, using `window.location.host` as the domain, `window.location.origin` as the URI, version `1`, the connected chain ID, your nonce, your `statement`, and the current time as `issuedAt`.

## Client

```tsx title="app/auth.ts"
'use client'
import type { WylletAuthAdapter } from 'wyllet'

export const auth: WylletAuthAdapter = {
  statement: 'Sign in to My dApp.',
  getNonce: () => fetch('/api/siwe/nonce').then((r) => r.text()),
  verify: ({ message, signature }) =>
    fetch('/api/siwe/verify', {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({ message, signature }),
    }).then((r) => r.ok),
  signOut: () => fetch('/api/siwe/logout', { method: 'POST' }).then(() => undefined),
  getSession: () => fetch('/api/siwe/session').then((r) => (r.ok ? r.json() : null)),
}
```

```tsx title="app/providers.tsx"
<WylletProvider auth={auth}>{children}</WylletProvider>
```

Send only the message and signature to the server. The server reads the address and chain from the signed message, not from the request.

## Server

A sketch with Next.js App Router route handlers and `viem/siwe`. `verifySiweMessage` checks the message fields (domain, nonce, address, time) and the signature. Because it runs through a public client, it also supports smart contract accounts.

The session helpers are placeholders. Back them with your session library or an encrypted, signed cookie.

```ts title="lib/session.ts"
import type { Address } from 'viem'

export declare function createSession(address: Address): Promise<void>
export declare function readSession(): Promise<{ address: Address } | null>
export declare function destroySession(): Promise<void>
```

```ts title="app/api/siwe/nonce/route.ts"
import { cookies } from 'next/headers'
import { generateSiweNonce } from 'viem/siwe'

export async function GET() {
  const nonce = generateSiweNonce()
  const jar = await cookies()
  jar.set('siwe-nonce', nonce, { httpOnly: true, secure: true, sameSite: 'strict', path: '/', maxAge: 300 })
  return new Response(nonce)
}
```

```ts title="app/api/siwe/verify/route.ts"
import { cookies } from 'next/headers'
import { createPublicClient, http } from 'viem'
import { base, mainnet } from 'viem/chains'
import { parseSiweMessage } from 'viem/siwe'
import { createSession } from '@/lib/session'

// Must equal window.location.host on the client, e.g. 'mydapp.xyz' or 'localhost:3000'.
const DOMAIN = process.env.SIWE_DOMAIN!

const clients = {
  [mainnet.id]: createPublicClient({ chain: mainnet, transport: http() }),
  [base.id]: createPublicClient({ chain: base, transport: http() }),
}

export async function POST(request: Request) {
  const { message, signature } = await request.json()

  // A nonce can be used once.
  const jar = await cookies()
  const nonce = jar.get('siwe-nonce')?.value
  jar.delete('siwe-nonce')
  if (!nonce) return new Response('Missing nonce', { status: 400 })

  const { address, chainId } = parseSiweMessage(message)
  const client = chainId ? clients[chainId as keyof typeof clients] : undefined
  if (!address || !client) return new Response('Unsupported chain', { status: 400 })

  const valid = await client.verifySiweMessage({ message, signature, domain: DOMAIN, nonce })
  if (!valid) return new Response('Invalid signature', { status: 401 })

  await createSession(address)
  return Response.json({ address })
}
```

```ts title="app/api/siwe/session/route.ts"
import { readSession } from '@/lib/session'

export async function GET() {
  const session = await readSession()
  return session ? Response.json({ address: session.address }) : new Response(null, { status: 401 })
}
```

```ts title="app/api/siwe/logout/route.ts"
import { destroySession } from '@/lib/session'

export async function POST() {
  await destroySession()
  return new Response(null, { status: 204 })
}
```

If you only need EOA support, you can verify with `verifyMessage` from `viem` after checking the parsed nonce and domain yourself. The [playground](/playground) does this in a client-only demo adapter.

> **Warning:** The sign-in step proves wallet ownership to your backend only if the backend checks it. Never treat a client-side `true` as a session.

## Security checklist

- **Verify the nonce on the server.** Issue it server-side, store it in an httpOnly cookie or your session store, accept it once, and expire it quickly.
- **Check the domain.** Compare the message's domain with your own host, so a signature collected on another site cannot sign in to yours. `verifySiweMessage` does this when you pass `domain`.
- **Use httpOnly cookies for the session.** Set `secure` and `sameSite`, and keep session tokens out of `localStorage`, where any script on the page can read them.
- **Trust the message, not the request.** Read the address and chain ID from the parsed message.
- **End sessions on the server.** `signOut()` should invalidate the session, not just clear a client flag.

## useWylletAuth

```tsx
import { useWylletAuth } from 'wyllet'

function AuthStatus() {
  const { enabled, status, signIn, signOut } = useWylletAuth()
  if (!enabled) return null
  if (status === 'authenticated') return <button onClick={signOut}>Sign out</button>
  return <button onClick={(e) => signIn({ anchor: e.currentTarget })}>Sign in</button>
}
```

| Field | Type | Description |
| --- | --- | --- |
| `enabled` | `boolean` | `true` when an `auth` adapter is set |
| `status` | `'loading' \| 'unauthenticated' \| 'authenticated'` | For the connected account. `'loading'` while `getSession()` resolves |
| `signIn` | `(options?: OpenOptions) => void` | Opens the panel at the sign-in step, connecting first if needed |
| `signOut` | `() => Promise<void>` | Calls the adapter's `signOut()` and clears the session |

`useWyllet()` also returns `authStatus`, which is the same status, or `undefined` when no adapter is set.

## Gating content

[ConnectGate](/docs/connect-gate) renders its children only when the user is signed in, when an adapter is set. Pass `requireAuth={false}` to gate on the connection alone.

---

# ConnectGate

> Render content only when users are connected, on a supported network and signed in.

Source: https://wyllet.dev/docs/connect-gate

`ConnectGate` renders its children only when the user is ready: connected, on a supported network, and signed in when you use [SIWE](/docs/siwe). Otherwise it shows a prompt with a button that opens the right step of the panel.

```tsx
import { ConnectGate } from 'wyllet'

export function VaultPage() {
  return (
    <ConnectGate description="Connect a wallet to open the vault.">
      <Vault />
    </ConnectGate>
  )
}
```

It must be rendered inside `WylletProvider`.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | | Content shown when every requirement is met |
| `requireSupportedChain` | `boolean` | `true` | Also require a chain that is in your config |
| `requireAuth` | `boolean` | `true` | Also require a SIWE session. Only applies when an `auth` adapter is set |
| `fallback` | `ReactNode \| ((reason: GateReason) => ReactNode)` | | Replaces the default prompt |
| `title` | `ReactNode` | "Connect to continue" | Title of the default prompt when disconnected |
| `description` | `ReactNode` | "This area needs a connected wallet." | Body of the default prompt when disconnected |
| `className` | `string` | | Extra class name on the default prompt |

`title` and `description` only change the disconnected prompt. The wrong-network and sign-in prompts use their own text from the [messages](/docs/i18n) object.

## Reasons

The gate checks requirements in order and stops at the first one that fails. The result is a `GateReason`:

| Reason | When | Default prompt button |
| --- | --- | --- |
| `'disconnected'` | No wallet is connected | **Connect** opens the connect panel |
| `'wrongNetwork'` | Connected to a chain that is not in your config, and `requireSupportedChain` is `true` | **Networks** opens the account panel on the Networks tab |
| `'unauthenticated'` | An auth adapter is set, `requireAuth` is `true`, and the connected account has no session | **Verify** opens the sign-in step |

The prompt's button anchors the panel to itself, so the [popover presentation](/docs/presentations) opens next to it.

While the adapter's `getSession()` is still resolving, the gate treats the user as not signed in and shows the sign-in prompt.

## Custom fallback

Pass a node to show the same fallback for every reason:

```tsx
<ConnectGate fallback={<p>Connect your wallet to see your positions.</p>}>
  <Positions />
</ConnectGate>
```

Or pass a function to handle each reason yourself:

```tsx
import { ConnectGate, useWyllet, type GateReason } from 'wyllet'

function Prompt({ reason }: { reason: GateReason }) {
  const { openConnect, openTab } = useWyllet()
  if (reason === 'wrongNetwork') return <button onClick={() => openTab('networks')}>Switch network</button>
  if (reason === 'unauthenticated') return <button onClick={() => openConnect()}>Sign in</button>
  return <button onClick={() => openConnect()}>Connect wallet</button>
}

<ConnectGate fallback={(reason) => <Prompt reason={reason} />}>
  <Dashboard />
</ConnectGate>
```

Opening the connect panel while connected but not signed in goes straight to the sign-in step.

## Loosening requirements

```tsx
// Connected is enough, on any chain, signed in or not.
<ConnectGate requireSupportedChain={false} requireAuth={false}>
  <Profile />
</ConnectGate>
```

## Server rendering

The wallet connection only exists in the browser, so `ConnectGate` never renders its children on the server or during the first client render. Until it mounts:

- With a `fallback`, it renders the fallback.
- Without one, it renders the default prompt with `visibility: hidden`, so the space is reserved and nothing flashes.

After mounting, it renders the children or the prompt for the current state. This keeps server and client markup the same and avoids hydration errors in [Next.js](/docs/nextjs).

> **Note:** `ConnectGate` hides UI. It does not protect data. Check the session on your server before returning anything private.

---

# Hooks

> API reference for every Wyllet hook: useWyllet, useWylletButton, useWylletToast, useWylletActivity, useWylletAuth and more.

Source: https://wyllet.dev/docs/hooks

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

```tsx
import {
  useCopyToClipboard,
  useWalletOptions,
  useWyllet,
  useWylletActivity,
  useWylletAuth,
  useWylletButton,
  useWylletChains,
  useWylletToast,
  useWylletTokens,
} from 'wyllet'
```

## useWyllet

Controls the Wyllet panel from anywhere in your app.

```ts
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`).

```tsx
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](/docs/wyllet-button) for a full walkthrough.

```ts
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.

```tsx
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](/docs/toasts).

```ts
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.

```tsx
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](/docs/activity).

```ts
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.

```tsx
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](/docs/siwe).

```ts
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. |

```tsx
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](/docs/tokens).

```ts
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`.

```tsx
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](/docs/chains).

```ts
function useWylletChains(): { chains: Chain[] }
```

```tsx
const { chains } = useWylletChains()
// With chainOrder={[8453]}: Base first, then the rest of your config
```

`chainOrder` 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`.

```ts
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. |

```tsx
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.

```ts
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.

```tsx
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>
    ))
}
```

---

# Components

> API reference for every Wyllet component: WylletButton, ConnectGate, Avatar, ChainIcon, TokenIcon, QRCode and more.

Source: https://wyllet.dev/docs/components

Wyllet exports nine components and one helper function for avatars. `WylletButton`, `WylletEmbed`, `ConnectGate`, `Avatar` and `ChainIcon` read Wyllet's context and must be rendered inside `WylletProvider`. `WylletMark` and `QRCode` work anywhere. `TokenIcon` works anywhere unless you pass `chainId`, which renders a `ChainIcon` badge.

```tsx
import {
  Avatar,
  addressGradient,
  ChainIcon,
  ConnectGate,
  QRCode,
  TokenIcon,
  WylletButton,
  WylletEmbed,
  WylletMark,
  WylletProvider,
} from 'wyllet'
```

## WylletProvider

Holds Wyllet's state, renders the panel and toasts, and injects the styles. Place it inside `WagmiProvider` and `QueryClientProvider`.

```tsx
<WagmiProvider config={config}>
  <QueryClientProvider client={queryClient}>
    <WylletProvider>{children}</WylletProvider>
  </QueryClientProvider>
</WagmiProvider>
```

Every prop is documented on [WylletProvider](/docs/provider).

## WylletButton

The Island button. A call to action when disconnected, and the account's avatar, name, network badge and balance when connected. See [WylletButton](/docs/wyllet-button).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | `messages.connect` (`'Connect'`) | Text shown when disconnected. |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Button size. |
| `display` | `'full' \| 'compact' \| 'avatar'` | `'full'` | `full`: avatar, name and balance. `compact`: avatar and name. `avatar`: avatar only. |
| `className` | `string` | | Extra class on the button. |

```tsx
<WylletButton size="lg" display="compact" label="Enter app" />
```

When connected, the button shows "Verify" if a sign-in is still needed and "Wrong network" when the wallet is on a chain your config does not include. Clicking it in the wrong-network state opens the Networks tab.

The button renders inside an error boundary. If it ever crashes, it is replaced with a plain connect button that still opens the panel. For a fully custom button, use [`useWylletButton`](/docs/hooks#usewylletbutton).

## ConnectGate

Renders its children only when the user is connected, on a supported network and, if an `auth` adapter is set, signed in. Otherwise it renders a prompt with a button that opens the right step. See [ConnectGate](/docs/connect-gate).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | | Content to show when every requirement is met. |
| `requireSupportedChain` | `boolean` | `true` | Also require a chain from your config. |
| `requireAuth` | `boolean` | `true` | Also require Sign-In With Ethereum when an `auth` adapter is set. |
| `fallback` | `ReactNode \| ((reason: GateReason) => ReactNode)` | | Replaces the built-in prompt. |
| `title` | `ReactNode` | `messages.gateTitle` | Prompt title in the disconnected state. |
| `description` | `ReactNode` | `messages.gateBody` | Prompt text in the disconnected state. |
| `className` | `string` | | Extra class on the prompt. |

`GateReason` is `'disconnected' | 'wrongNetwork' | 'unauthenticated'`.

```tsx
<ConnectGate requireAuth={false} fallback={(reason) => <p>Blocked: {reason}</p>}>
  <Dashboard />
</ConnectGate>
```

Children are never rendered on the server or during the first client render, so gated content does not leak into server HTML.

## WylletEmbed

The real Wyllet panel rendered inline, inside your own layout, instead of in an overlay. Use it for a connect card on a sign-in page, an account panel in a sidebar, or a live preview. It shows the connect view while the user is disconnected and the account view once they are connected (and signed in, when you use SIWE).

```tsx
import { WylletEmbed } from 'wyllet'

export function SignInPage() {
  return (
    <main className="grid place-items-center">
      <WylletEmbed />
    </main>
  )
}
```

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `view` | `'auto' \| 'connect' \| 'account'` | `'auto'` | Which view to show. `auto` follows the connection state |
| `fill` | `boolean` | `false` | Stretch to the parent's height, like the drawer, instead of sizing to the content |
| `className` | `string` | | Class on the outer wrapper |

It uses the provider's theme, wallets, tokens and options, and the `panel` class name slot. Its navigation is local: connecting, switching tabs or going back never opens the drawer, and there is no close button. Wallet detection only exists in the browser, so it renders after mount and outputs an empty box during server rendering. It is at most 420px wide.

## Avatar

An address avatar. Shows the ENS avatar when one exists and ENS is enabled, otherwise a gradient generated from the address. If you pass a custom `avatar` component to `WylletProvider`, `Avatar` renders that instead.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `address` | `string` | | The address to draw. |
| `size` | `number` | `24` | Width and height in pixels. |
| `className` | `string` | | Extra class, added after `wy-avatar`. |

```tsx
<Avatar address="0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" size={40} />
```

ENS names that fail normalization are ignored instead of throwing, so a malicious reverse record cannot crash the avatar.

### addressGradient

```ts
function addressGradient(address: string): string
```

Returns the CSS `background` value `Avatar` uses: a deterministic gradient, so the same address gets the same colors everywhere. Use it to match Wyllet's avatars in your own UI.

```tsx
<div style={{ width: 32, height: 32, borderRadius: '50%', background: addressGradient(address) }} />
```

## ChainIcon

A chain logo as an `img`. The source is chosen in this order: the provider's `chainIcons` prop, the `icon` passed to `customChain`, a built-in official mark, then a colored monogram.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `chainId` | `number` | | The chain id. |
| `size` | `number` | `20` | Width and height in pixels. |
| `className` | `string` | | Extra class, added after `wy-chain-icon`. |

```tsx
<ChainIcon chainId={8453} size={24} />
```

Built-in marks cover Ethereum, OP, Arbitrum, Base, Polygon, Avalanche, zkSync, Linea, Scroll, Gnosis, Zora and Blast, and their testnets. BNB Chain gets a monogram because its brand guidelines require approval first.

## TokenIcon

A token logo with an optional chain badge in the corner.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `symbol` | `string` | | Token symbol. Used to pick a built-in mark and as the image's `alt` text. |
| `src` | `string` | | Custom icon URL. If it fails to load, the built-in mark or monogram is used. |
| `chainId` | `number` | | Draws a `ChainIcon` badge at 42% of `size`. |
| `size` | `number` | `32` | Width and height in pixels. |
| `className` | `string` | | Extra class on the wrapper. |

```tsx
<TokenIcon symbol="USDC" chainId={8453} size={28} />
```

Built-in marks: ETH, WETH, USDC, USDT, DAI, WBTC, OP, ARB, POL, MATIC, AVAX, LINK and UNI. Any other symbol gets a generated monogram. To get the icon URL without rendering, use [`tokenIconUri`](/docs/utilities#tokeniconuri).

## WylletMark

Wyllet's logo as an inline SVG. It makes no image request and is hidden from assistive technology (`aria-hidden`).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `number` | `16` | Width and height in pixels. |
| `className` | `string` | | Class on the `svg`. |

```tsx
<WylletMark size={20} />
```

## QRCode

The QR code Wyllet uses for WalletConnect and the Receive screen, rendered as an SVG. The encoder is built in. See [Pretty QR codes that still scan](/blog/qr-codes-that-scan) for how the design was tested.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | | Text to encode. |
| `size` | `number` | `256` | Width and height in pixels. |
| `logo` | `string` | | Image URL drawn in the center. The modules behind it are removed. |
| `logoBackground` | `string` | `'transparent'` | Fill behind the logo. |

```tsx
<div style={{ background: '#fff', color: '#111', padding: 8, display: 'inline-block' }}>
  <QRCode value="0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" size={240} />
</div>
```

How it renders:

- Modules are drawn in `currentColor` on a transparent background. Put it on a light background with a dark `color`, as in the example.
- It uses error correction level Q. A center logo covers about 24% of the code's width, with one extra module cleared around it.
- A 2-module quiet zone is included inside the SVG's bounds.
- Wyllet's scan test runs at 240px, so avoid rendering it smaller than that.

---

# Utilities and types

> Helper functions and the TypeScript types Wyllet exports.

Source: https://wyllet.dev/docs/utilities

Besides components and hooks, Wyllet exports helper functions for configuration, chains, tokens, theming, translations and formatting, plus the TypeScript types behind every public API. Everything on this page is a named export of `wyllet`.

## Configuration

### getDefaultConfig

Creates a wagmi config with EIP-6963 discovery, WalletConnect (when you pass a project id), your wallet list and app metadata. It is covered in [Configuration](/docs/configuration).

```ts
import { getDefaultConfig } from 'wyllet'
import { base, mainnet } from 'viem/chains'

const config = getDefaultConfig({
  appName: 'My dApp',
  walletConnectProjectId: process.env.NEXT_PUBLIC_WC_PROJECT_ID,
  chains: [mainnet, base],
})
```

## Chains

### customChain

Defines any EVM chain in one call. The result is a regular viem `Chain` (built with viem's `defineChain`) that also carries Wyllet's icon metadata under `chain.custom.wyllet`.

```ts
function customChain(input: CustomChainInput): Chain
```

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `number` | | Chain id. |
| `name` | `string` | | Display name. |
| `rpcUrl` | `string` | | HTTPS JSON-RPC endpoint. |
| `nativeCurrency` | `{ name, symbol, decimals }` | Ether, `ETH`, `18` | Native currency. |
| `explorerUrl` | `string` | | Block explorer base URL. A trailing slash is removed. |
| `testnet` | `boolean` | | Marks the chain as a testnet (shown with a tag in the Networks tab). |
| `icon` | `string` | | Chain logo URL or data URI. |
| `color` | `string` | | Brand color for the generated monogram when there is no icon. |
| `nativeIcon` | `string` | | Icon for the native currency in the Tokens tab. |

```ts
const myChain = customChain({
  id: 424242,
  name: 'My Chain',
  rpcUrl: 'https://rpc.mychain.xyz',
  explorerUrl: 'https://scan.mychain.xyz',
  nativeCurrency: { name: 'My Token', symbol: 'MYT', decimals: 18 },
  icon: '/mychain.svg',
})
```

### popularChains

A readonly array of viem chains with built-in icons: Ethereum, Base, OP, Arbitrum, Polygon, BNB Smart Chain, Avalanche, zkSync, Linea and Scroll, in that order.

### popularTestnets

A readonly array of testnets: Sepolia, Base Sepolia, OP Sepolia, Arbitrum Sepolia and Polygon Amoy.

```ts
getDefaultConfig({
  appName: 'My dApp',
  chains: [...popularChains, ...popularTestnets],
})
```

See [Chains](/docs/chains) for ordering and the Networks tab.

## Tokens

### defaultTokens

A `TokenList` of blue-chip tokens, used when `tokens` is `'default'` (the provider's default):

| Chain | Tokens |
| --- | --- |
| Ethereum (1) | USDC, USDT, DAI, WETH, WBTC |
| Base (8453) | USDC, WETH, DAI |
| OP (10) | USDC, USDT, WETH, OP |
| Arbitrum (42161) | USDC, USDT, WETH, ARB |
| Polygon (137) | USDC, USDT, WETH |

### withDefaultTokens

```ts
function withDefaultTokens(custom: TokenList | TokenEntry[]): TokenList
```

Your tokens first, then `defaultTokens` for each chain, with duplicates (same address, case-insensitive) removed.

```tsx
const tokens = withDefaultTokens([
  { chainId: 8453, address: '0x…', symbol: 'MYTKN', decimals: 18, pinned: true },
])

<WylletProvider tokens={tokens} />
```

### toTokenList

```ts
function toTokenList(input: TokenList | TokenEntry[]): TokenList
```

Turns a flat `TokenEntry[]` (each entry has a `chainId`) into a `TokenList` keyed by chain id, keeping order. A `TokenList` is returned unchanged.

### tokenIconUri

```ts
function tokenIconUri(symbol: string): string
```

Returns the icon `TokenIcon` uses for a symbol: built-in official artwork when bundled (matched as given, then upper-cased), otherwise a generated monogram as an SVG data URI. It never throws, including for emoji or markup in the symbol.

See [Tokens](/docs/tokens) for pinning, sorting and user token import.

## Theming

### Theme presets

Four presets, each a function that takes optional `ThemeOptions` and returns a `Theme`:

| Preset | Look |
| --- | --- |
| `obsidianTheme` | Deep graphite with a mint accent. The default dark theme. |
| `porcelainTheme` | Paper white with ink-black actions. The default light theme. |
| `auroraTheme` | Translucent glass with a violet to cyan glow. Best over colorful backgrounds. |
| `terminalTheme` | Monospace, sharp corners, phosphor green. |

`ThemeOptions`:

| Option | Type | Description |
| --- | --- | --- |
| `accentColor` | `string` | Brand color for primary actions, focus and live indicators. |
| `accentColorForeground` | `string` | Text color on top of the accent. |
| `accentSecondary` | `string` | Second brand color used in gradients. |
| `radius` | `'sharp' \| 'soft' \| 'round' \| 'pill'` | Corner radius scale. |
| `fontFamily` | `string` | Body font stack. |
| `overlayBlur` | `'none' \| 'subtle' \| 'heavy'` | Blur behind the panel overlay. |
| `overrides` | `DeepPartial<Theme>` | Deep-merged after the options above. |

```tsx
<WylletProvider theme={obsidianTheme({ accentColor: '#C6F432', radius: 'soft' })} />
```

### createTheme

```ts
function createTheme(base: Theme, overrides?: DeepPartial<Theme>): Theme
```

Deep-merges `overrides` into `base` without mutating either.

```ts
const brand = createTheme(porcelainTheme(), {
  colors: { accent: '#5B3DF5', islandBackground: '#F7F5FF' },
  radii: { button: '999px' },
})
```

### themeToCssVars

```ts
function themeToCssVars(theme: Theme): Record<string, string>
```

Flattens a theme into the CSS custom properties Wyllet uses, named `--wy-<group>-<token>` in kebab case. For example `colors.accentForeground` becomes `--wy-colors-accent-foreground` and `radii.panel` becomes `--wy-radii-panel`. Useful for styling your own UI to match. See [Theming](/docs/theming).

## Translations

### en

The English strings object. Every user-facing string Wyllet renders is a key in `en`. Pass a partial object to the provider's `messages` prop to rename or translate. Placeholders such as `{name}` are filled in at render time.

```tsx
import { en } from 'wyllet'

<WylletProvider messages={{ connect: 'Conectar', connectTo: 'Conectar a {app}' }} />
```

See [Translations](/docs/i18n).

## Formatting

### formatAmount

```ts
function formatAmount(value: bigint, decimals: number, maxSignificant?: number): string
```

Formats a raw token amount for display. `maxSignificant` defaults to `4`.

| Raw value (18 decimals) | Output |
| --- | --- |
| 0 | `0` |
| 0.00001 | `<0.0001` |
| 0.1234567 | `0.1235` |
| 1.5 | `1.5` |
| 12.3456 | `12.35` |
| 12345 | `12.3K` |
| 2500000 | `2.5M` |

Values of a billion or more use a `B` suffix. Invalid `decimals` (not an integer from 0 to 77) fall back to 18.

### shortenAddress

```ts
function shortenAddress(address: string, chars?: number): string
```

Keeps `chars` characters (default `4`) on each side: `0x1234567890abcdef1234567890abcdef12345678` becomes `0x1234…5678`. Strings already short enough are returned unchanged.

## Wallets

The wallet presets (`metaMaskWallet`, `phantomWallet`, `rabbyWallet`, `okxWallet`, `walletConnectWallet`, `coinbaseWallet`, `rainbowWallet`, `trustWallet`, `browserWallet`, `burnerWallet`) and `defaultWallets` are covered in [Wallets](/docs/wallets).

### burner

```ts
function burner(options?: BurnerOptions): CreateConnectorFn
```

The wagmi connector behind `burnerWallet()`: an in-browser wallet whose private key is generated and kept unencrypted in `localStorage` (key `wyllet.v1.burner.key` unless you pass `storageKey`). Non-signing RPC calls go to the chain's transport from your config. Use it only for local development and demos. It logs a console warning the first time it connects on a host that is not local (`localhost`, `127.0.0.1`, `[::1]`, `0.0.0.0`, or a `.local`, `.localhost` or `.test` domain).

```ts
import { createConfig, http } from 'wagmi'
import { sepolia } from 'viem/chains'
import { burner } from 'wyllet'

const config = createConfig({
  chains: [sepolia],
  transports: { [sepolia.id]: http() },
  connectors: [burner()],
})
```

> **Warning:** Never hold real funds in a burner wallet. Anyone with access to the browser's storage, including any script running on the page, can read the key.

## Types

All types are exported from `wyllet` and can be imported with `import type`.

```ts
import type { Theme, Wallet, WylletAuthAdapter } from 'wyllet'
```

### Provider and configuration

| Type | Description |
| --- | --- |
| `WylletProviderProps` | Props of `WylletProvider`. |
| `DefaultConfigParameters` | Parameters of `getDefaultConfig`. |
| `AppInfo` | App metadata: `name`, `description`, `url`, `icon`, `learnMoreUrl`, `termsUrl`, `privacyUrl`. |
| `Appearance` | The provider's `appearance` prop. |
| `Presentation` | `'drawer' \| 'popover' \| 'modal'`. |
| `PanelView` | `'connect' \| 'account'`. |
| `AccountTab` | `'tokens' \| 'activity' \| 'networks'`. |
| `OpenOptions` | `anchor` and `tab` options for opening the panel. |
| `WylletSlot` | Elements that accept `classNames`: `'overlay' \| 'panel' \| 'island' \| 'walletRow' \| 'primaryButton' \| 'identityCard' \| 'toast'`. |
| `CustomAvatarProps` | Props passed to a custom `avatar` component: `address`, `ensImage`, `size`. |

### Components and hooks

| Type | Description |
| --- | --- |
| `WylletButtonProps` | Props of `WylletButton`. |
| `WylletButtonState` | Return type of `useWylletButton`. |
| `ConnectGateProps` | Props of `ConnectGate`. |
| `GateReason` | `'disconnected' \| 'wrongNetwork' \| 'unauthenticated'`. |
| `AvatarProps` | Props of `Avatar`. |
| `ChainIconProps` | Props of `ChainIcon`. |
| `TokenIconProps` | Props of `TokenIcon`. |
| `QRCodeProps` | Props of `QRCode`. |
| `ListedToken` | `Token` plus `custom?: boolean` for user-imported tokens. |
| `WalletOption` | One entry from `useWalletOptions`. |
| `WalletGroup` | A group from `useWalletOptions`: `id` (`'installed' \| 'popular' \| 'more'`) and `wallets`. |

### Theming

| Type | Description |
| --- | --- |
| `Theme` | Every design token, in five groups: `colors`, `radii`, `fonts`, `shadows`, `effects`. |
| `ThemeInput` | A `Theme`, or a `{ light, dark }` pair. |
| `ThemeOptions` | Options accepted by the presets. |
| `ColorMode` | `'light' \| 'dark' \| 'auto'`. |
| `RadiusScale` | `'sharp' \| 'soft' \| 'round' \| 'pill'`. |
| `BlurScale` | `'none' \| 'subtle' \| 'heavy'`. |
| `DeepPartial` | Recursive `Partial`, used for theme overrides. |

### Wallets

| Type | Description |
| --- | --- |
| `Wallet` | A wallet in the connect view: `id`, `name`, `icon`, and optional `iconBackground`, `rdns`, `connectorId`, `createConnector`, `walletConnect`, `downloadUrls`, `description`, `featured`. |
| `WalletDownloadUrls` | `browserExtension`, `ios`, `android`, `website`. |
| `WalletPresetOptions` | Options for every preset: `connector` and `overrides`. |
| `BurnerOptions` | Options for `burner` and `burnerWallet`: `storageKey`. |

### Chains and tokens

| Type | Description |
| --- | --- |
| `CustomChainInput` | Input of `customChain`. |
| `ChainExtras` | Wyllet's chain metadata: `icon`, `color`, `nativeIcon`. |
| `Token` | `address`, `symbol`, `decimals`, and optional `name`, `icon`, `pinned`. |
| `TokenEntry` | `Token` plus `chainId`, for flat lists. |
| `TokenList` | Tokens keyed by chain id. |

### Auth

| Type | Description |
| --- | --- |
| `WylletAuthAdapter` | The `auth` adapter: `getNonce`, `verify`, `signOut`, and optional `createMessage`, `getSession`, `statement`. |
| `AuthStatus` | `'loading' \| 'unauthenticated' \| 'authenticated'`. |

### Toasts and activity

| Type | Description |
| --- | --- |
| `ToastApi` | Return type of `useWylletToast`. |
| `ToastOptions` | Options for a toast. |
| `Toast` | A toast in the store: `ToastOptions` plus `id`, `status`, `createdAt`, `dismissed`. |
| `ToastStatus` | `'info' \| 'success' \| 'error' \| 'loading'`. |
| `ToastPosition` | `'top-left' \| 'top-center' \| 'top-right' \| 'bottom-left' \| 'bottom-center' \| 'bottom-right'`. |
| `ActivityItem` | One timeline entry: `id`, `kind`, `title`, `description`, `status`, `account`, `chainId`, `hash`, `timestamp`. |
| `ActivityKind` | `'transaction' \| 'connect' \| 'disconnect' \| 'network' \| 'signIn' \| 'custom'`. |
| `ActivityStatus` | `'pending' \| 'success' \| 'failed' \| 'info'`. |

### Translations

| Type | Description |
| --- | --- |
| `Messages` | The shape of `en`: every string key Wyllet uses. |

---

# Security

> Zero direct runtime dependencies, provenance, CSP and what Wyllet does and does not do.

Source: https://wyllet.dev/docs/security

A wallet connector runs on the same page as your users' wallets, so everything it ships and everything it does in the browser matters. This page covers what Wyllet depends on, how releases are published and how to verify them, what it sends over the network, what it stores, how to run it under a Content Security Policy, and what it does not do.

## Zero direct runtime dependencies

The `wyllet` package has no `dependencies` field. At runtime it only imports libraries your dApp already has, declared as peer dependencies:

| Peer | Range |
| --- | --- |
| `react` | `>=18` |
| `react-dom` | `>=18` |
| `wagmi` | `^3.0.0` |
| `viem` | `^2.15.0` |
| `@tanstack/react-query` | `>=5.0.0` |
| `@walletconnect/ethereum-provider` | `^2.21.1` (optional) |

Because they are peers, your lockfile decides which versions run, and you can audit and update them on your own schedule.

WalletConnect is an optional peer. If you do not pass `walletConnectProjectId`, you do not need to install it. If you do, you install `@walletconnect/ethereum-provider` yourself and pin the version you trust. Wyllet's bundle never imports it directly: wagmi's `walletConnect` connector loads it when WalletConnect is used.

```bash
npm view wyllet dependencies
# prints nothing: there are none
```

Small pieces that a library would usually pull from npm are written in the package instead. The most notable is the QR code encoder.

## The dependency policy test

`packages/wyllet/test/policy.test.ts` runs in CI on every push and pull request. It fails the build if:

1. `package.json` has any entry in `dependencies`.
2. `peerDependencies` contains anything other than the six packages above.
3. The built bundle (`dist/index.js`) imports any package outside that list. The test scans every `import` and `from` specifier in the bundle, so a runtime import of any other package fails the build even if `package.json` looks clean.

CI runs the build before the tests so the bundle check always has a fresh `dist` to scan.

## The built-in QR encoder

Wyllet draws WalletConnect and Receive QR codes with its own encoder (`src/qr/encode.ts`). It supports byte mode only, which covers everything Wyllet encodes, and follows Project Nayuki's reference implementation.

Two tests keep it honest:

- `test/qr.test.ts` compares our output module-for-module with `uqr`, a port of the reference encoder, at all four error-correction levels (L, M, Q, H). The inputs include addresses, an `ethereum:` URI, Unicode and emoji, WalletConnect URIs of several lengths and a 1,200-character string.
- `test/qr-scan.test.ts` rasterizes the exact styled geometry Wyllet draws at 240px on a 1x raster with 3x3 supersampling, then decodes it with `jsQR`. It covers 30 addresses and 10 WalletConnect URIs, with and without a center logo, and fails if a single code does not decode to its input.

`uqr` and `jsqr` are dev dependencies. They are never shipped to your users.

## Network requests

Wyllet makes no network requests of its own, with one opt-in exception: the **All wallets** directory.

When WalletConnect is configured with a project id and `appearance.walletDirectory` is not `false`, opening **All wallets** fetches pages of 40 wallets from WalletConnect's registry at `explorer-api.walletconnect.com`, sending your project id and the user's search text. Logos are then loaded from the image URLs the registry returns. Nothing is fetched until a user opens the directory. Results are cached in memory for the rest of the page session, and failed requests are not cached, so "Retry" really retries.

```tsx
<WylletProvider appearance={{ walletDirectory: false }} />
```

Other traffic you will see comes from the libraries you configured, not from Wyllet itself:

- **RPC calls** go through your wagmi transports: balances, token balances and metadata, ENS names and avatars (only when mainnet is in your config and `ens` is on), gas price (polled every 12 seconds while the Networks tab is open) and transaction receipts. `getDefaultConfig` uses each chain's public RPC unless you pass `transports`. Use your own RPC in production.
- **WalletConnect** connects to WalletConnect's relay when a user connects through it.
- **ENS avatar images** load from whatever URL the ENS record points to.

Wyllet has no analytics, telemetry or tracking code.

## Releases and npm provenance

Releases are published from GitHub Actions, never from a developer's machine.

- Pushing a version tag (for example `v1.0.0`) runs `.github/workflows/release.yml`.
- The workflow checks that the tag matches the version in `packages/wyllet/package.json`.
- It installs with `pnpm install --frozen-lockfile`, and `prepublishOnly` re-runs the typecheck, the full test suite and the build before anything is uploaded.
- It publishes with npm Trusted Publishing. GitHub's OIDC token proves to npm which repository and workflow is publishing. No npm token is stored in the repository or its secrets, and npm only accepts publishes for `wyllet` from this workflow.
- `publishConfig.provenance` is `true`, so every version carries a signed provenance attestation that links the tarball to the exact commit and workflow run that built it.

### Verify a release

In a project that has `wyllet` installed:

```bash
npm audit signatures
```

This checks the registry signatures and provenance attestations of your installed packages, including `wyllet`.

On the [npm package page](https://www.npmjs.com/package/wyllet), the provenance section links to the source commit and the GitHub Actions run that published each version.

## Content Security Policy

By default Wyllet injects its base stylesheet in a `<style>` element. To serve it as a file instead, turn injection off and import the stylesheet:

```tsx title="app/providers.tsx"
import 'wyllet/styles.css'

<WylletProvider injectStyles={false}>{children}</WylletProvider>
```

> **Warning:** `injectStyles={false}` only moves the base stylesheet. In 1.0, Wyllet always renders one small inline `<style>` element with the active theme's CSS variables, and some elements use inline `style` values (sizes, popover position, avatar gradients). There is no nonce option yet, so a `style-src` without `'unsafe-inline'` blocks the theme element. If you need that, open an issue.

The other directives to check:

| Directive | What to allow |
| --- | --- |
| `script-src` | Nothing extra. Wyllet does not use `eval` or inject scripts. |
| `img-src` | `data:` for the built-in wallet, chain and token icons. Hosts of any icon URLs you configure. `https:` if you show ENS avatars, which can point anywhere. With All wallets, the host the registry serves wallet logos from (check your browser's network panel for the exact host). |
| `connect-src` | Your RPC endpoints. With WalletConnect, the relay and API endpoints listed in WalletConnect's own documentation, plus `https://explorer-api.walletconnect.com` for the All wallets directory. |

WalletConnect's endpoints are maintained by WalletConnect, so take the current list from their documentation rather than from this page.

## What Wyllet stores

Wyllet uses `localStorage` with keys prefixed `wyllet.v1.`. The version in the prefix changes if a stored format ever changes.

| Key | Contents |
| --- | --- |
| `wyllet.v1.recentWallets` | Ids of the last three wallets used, for "Continue with" |
| `wyllet.v1.activity` | The activity timeline, up to 50 entries per account |
| `wyllet.v1.customTokens` | Tokens the user imported, per chain (only used with `allowTokenImport`) |
| `wyllet.v1.burner.key` | Burner wallet private key (only if you use `burnerWallet()`) |
| `wyllet.v1.burner.key.connected` | Burner connection flag |
| `wyllet.v1.burner.key.chain` | Burner's last chain id |

The first three are validated on every read. Anything that is not valid JSON or has the wrong shape is discarded, and malformed entries are dropped while valid ones are kept. For example, imported tokens must have a valid address and integer decimals from 0 to 77. Storage access never throws, so private browsing modes and blocked storage do not break the UI.

Wyllet does not store signatures or sessions. Sign-In With Ethereum sessions live on your backend, and Wyllet restores them through your adapter's `getSession`. wagmi keeps its own connection state in storage under its own keys.

## The burner wallet is for development

`burnerWallet()` keeps an unencrypted private key in `localStorage`. The first time it connects on a host that is not local (anything other than `localhost`, `127.0.0.1`, `[::1]`, `0.0.0.0` or a `.local`, `.localhost` or `.test` domain), it logs a console warning telling you to remove it from production builds. It does not block the connection, so keep it out of your production wallet list.

```ts
const wallets = process.env.NODE_ENV === 'development' ? [...defaultWallets(), burnerWallet()] : defaultWallets()
```

## Wyllet's UI cannot take down your app

The panel, the toasts and the Island button each render inside their own error boundary. These boundaries wrap Wyllet's own UI only, never your children.

- If the panel crashes, it closes and the error is logged with a `[wyllet]` prefix.
- If the button crashes, it is replaced with a plain connect button that still opens the panel.
- Each boundary resets on the next relevant change, such as a new connection status or toast.

One error is deliberately loud: rendering a Wyllet component outside `WylletProvider` throws, because that is a setup mistake you should see in development.

## Hostile onchain data

ENS names and token symbols are controlled by whoever registered them. Wyllet treats them as untrusted:

- ENS names that fail normalization are ignored instead of throwing.
- Generated monograms escape markup and handle emoji and broken Unicode without throwing.
- Text is rendered through React, which escapes it. Wyllet does not use `dangerouslySetInnerHTML`.

These cases are covered by `test/hardening.test.tsx`.

## What Wyllet does not do

- **It never holds keys.** Wallets sign. Wyllet only asks them to. The one exception is the development burner wallet described above.
- **It does not custody funds** or move them on its own. Every transaction comes from your code and is approved in the user's wallet.
- **It does not proxy RPC.** Calls go straight from the browser to the transports in your wagmi config.
- **It does not verify signatures.** With Sign-In With Ethereum, your backend's `verify` decides whether a signature is valid.

## Reporting a vulnerability

Please do not open a public issue for security problems. Report them privately through a [GitHub security advisory](https://github.com/wyllet/wyllet/security/advisories/new) or by email to [support@wyllet.dev](mailto:support@wyllet.dev). Include the version, steps to reproduce and the impact you expect.

---

# Migrate from RainbowKit

> Map RainbowKit concepts to Wyllet and switch a dApp over step by step.

Source: https://wyllet.dev/docs/migrate-from-rainbowkit

RainbowKit and Wyllet solve the same problem on the same foundation: both sit on top of wagmi, viem and react-query, and both give you a provider, a connect button and a config helper. Most of a migration is renaming. This guide maps RainbowKit's concepts to Wyllet's, walks through the switch step by step, and lists what works differently. For a side-by-side of features, licenses and dependencies, see [How Wyllet compares](/compare#rainbowkit).

> **Note:** Wyllet requires wagmi v3 and viem 2. If your app is still on an older wagmi major, upgrade wagmi first using wagmi's own migration guide, then switch the connect layer.

## Concept map

| RainbowKit | Wyllet |
| --- | --- |
| `RainbowKitProvider` | `WylletProvider` |
| `ConnectButton` | `WylletButton` |
| `ConnectButton.Custom` | `useWylletButton()` |
| `getDefaultConfig` | `getDefaultConfig` (same idea, `walletConnectProjectId` instead of `projectId`) |
| `darkTheme()` / `lightTheme()` | `obsidianTheme()` / `porcelainTheme()` (also `auroraTheme()`, `terminalTheme()`) |
| `useConnectModal().openConnectModal` | `useWyllet().openConnect` |
| `useAccountModal().openAccountModal` | `useWyllet().openAccount` |
| `useChainModal().openChainModal` | `useWyllet().openTab('networks')` |
| `RainbowKitAuthenticationProvider` + adapter | `auth` prop on `WylletProvider` |
| Custom wallet objects | `Wallet` objects |
| Wallet groups (`groupName`) | A flat `wallets` array |
| `useAddRecentTransaction` | `useWylletActivity().addTransaction` |
| `import '@rainbow-me/rainbowkit/styles.css'` | Not needed (styles are injected) |

## Step by step

### 1. Swap the packages

```bash
npm uninstall @rainbow-me/rainbowkit
npm install wyllet

# Only if you use WalletConnect (QR codes and mobile wallets):
npm install @walletconnect/ethereum-provider
```

Wyllet's peers are `react`, `react-dom`, `wagmi`, `viem` and `@tanstack/react-query`, which your app already has. `@walletconnect/ethereum-provider` is an optional peer you install and pin yourself.

### 2. Update the config

Wyllet's `getDefaultConfig` takes the same kind of input and returns a wagmi config. Rename `projectId` to `walletConnectProjectId`. Other wagmi `createConfig` options, such as `ssr`, pass straight through.

```ts title="Before"
import { getDefaultConfig } from '@rainbow-me/rainbowkit'
import { base, mainnet } from 'wagmi/chains'

export const config = getDefaultConfig({
  appName: 'My dApp',
  projectId: 'YOUR_PROJECT_ID',
  chains: [mainnet, base],
  ssr: true,
})
```

```ts title="After"
import { getDefaultConfig } from 'wyllet'
import { base, mainnet } from 'viem/chains'

export const config = getDefaultConfig({
  appName: 'My dApp',
  walletConnectProjectId: 'YOUR_PROJECT_ID',
  chains: [mainnet, base],
  ssr: true,
})
```

Wyllet's `getDefaultConfig` also accepts `appDescription`, `appUrl`, `appIcon`, `transports`, `wallets` and extra `connectors`. See [Configuration](/docs/configuration).

### 3. Replace the provider

Keep `WagmiProvider` and `QueryClientProvider` as they are. Replace `RainbowKitProvider` with `WylletProvider` and delete the RainbowKit stylesheet import.

```tsx title="app/providers.tsx"
'use client'

import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { WagmiProvider } from 'wagmi'
import { WylletProvider } from 'wyllet'
import { config } from './wagmi'

const queryClient = new QueryClient()

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        <WylletProvider>{children}</WylletProvider>
      </QueryClientProvider>
    </WagmiProvider>
  )
}
```

A few RainbowKit provider props have direct counterparts:

| RainbowKit prop | Wyllet |
| --- | --- |
| `theme` | `theme` (a theme, or a `{ light, dark }` pair) |
| `appInfo.appName` | `appName` in `getDefaultConfig`, or `appInfo.name` on the provider |
| `appInfo.learnMoreUrl` | `appInfo.learnMoreUrl` |
| `appInfo.disclaimer` | `disclaimer` |
| `avatar` | `avatar` (receives `address`, `ensImage` and `size`) |
| `locale` | `messages` (override any string; see [Translations](/docs/i18n)) |
| `initialChain` | The first chain in your config is the default |

### 4. Replace the button

```tsx
// Before
<ConnectButton label="Sign in" />

// After
<WylletButton label="Sign in" />
```

`WylletButton` has a `display` prop instead of `accountStatus` and `showBalance`: `'full'` shows the avatar, name and balance, `'compact'` the avatar and name, and `'avatar'` the avatar only. The network appears as a badge on the avatar, so there is no separate chain button. See [WylletButton](/docs/wyllet-button).

### 5. Replace custom buttons

`ConnectButton.Custom` is a render prop. Wyllet uses a hook instead, so you can call it in any component.

```tsx
import { useWylletButton } from 'wyllet'

function CustomButton() {
  const { mounted, account, chain, openConnect, openAccount } = useWylletButton()
  if (!mounted) return null
  if (!account) return <button onClick={(e) => openConnect(e.currentTarget)}>Connect</button>
  if (chain?.unsupported) return <button onClick={(e) => openAccount(e.currentTarget, 'networks')}>Wrong network</button>
  return <button onClick={(e) => openAccount(e.currentTarget)}>{account.displayName}</button>
}
```

| `ConnectButton.Custom` | `useWylletButton()` |
| --- | --- |
| `mounted` | `mounted` |
| `account.displayName` | `account.displayName` |
| `account.displayBalance` | `account.balance.formatted` and `account.balance.symbol` |
| `chain.unsupported` | `chain.unsupported` |
| `openConnectModal()` | `openConnect(anchor?)` |
| `openAccountModal()` | `openAccount(anchor?)` |
| `openChainModal()` | `openAccount(anchor, 'networks')` |
| `authenticationStatus` | `authStatus` |

Passing the clicked element as `anchor` lets the `popover` presentation position itself next to your button.

### 6. Replace the modal hooks

```tsx
const { openConnect, openAccount, openTab, close } = useWyllet()

openConnect()          // was openConnectModal()
openAccount()          // was openAccountModal()
openTab('networks')    // was openChainModal()
```

### 7. Move the theme

```tsx
// Before
<RainbowKitProvider theme={darkTheme({ accentColor: '#7b3fe4', accentColorForeground: 'white' })} />

// After
<WylletProvider theme={obsidianTheme({ accentColor: '#7b3fe4', accentColorForeground: 'white' })} />
```

`accentColor` and `accentColorForeground` keep their names. The other knobs differ: `radius` takes `'sharp' | 'soft' | 'round' | 'pill'`, `overlayBlur` takes `'none' | 'subtle' | 'heavy'`, and `fontFamily` takes any font stack. To follow the OS color scheme, pass a pair:

```tsx
<WylletProvider theme={{ light: porcelainTheme(), dark: obsidianTheme() }} colorMode="auto" />
```

Every token is also a CSS variable (such as `--wy-colors-accent`), and the `classNames` prop attaches your own classes to individual elements. See [Theming](/docs/theming) and [Class names](/docs/class-names).

### 8. Move authentication

In RainbowKit you wrap the app in `RainbowKitAuthenticationProvider`, pass an adapter, and supply the authentication `status` yourself. In Wyllet you pass an adapter to the `auth` prop and Wyllet tracks the status.

```tsx
import type { WylletAuthAdapter } from 'wyllet'

const auth: WylletAuthAdapter = {
  getNonce: () => fetch('/api/nonce').then((r) => r.text()),
  verify: ({ message, signature }) =>
    fetch('/api/verify', { method: 'POST', body: JSON.stringify({ message, signature }) }).then((r) => r.ok),
  signOut: () => fetch('/api/logout', { method: 'POST' }).then(() => {}),
  getSession: () => fetch('/api/me').then((r) => (r.ok ? r.json() : null)),
}

<WylletProvider auth={auth}>{children}</WylletProvider>
```

- `createMessage` is optional. By default Wyllet builds an EIP-4361 message with `viem/siwe`.
- `getSession` restores an existing session on page load. Return `{ address }` or `null`.
- Disconnecting or switching accounts calls `signOut`.
- Read the status with `useWylletAuth()`.

Your backend nonce and verify endpoints do not need to change. See [Sign-In With Ethereum](/docs/siwe).

### 9. Move the wallet list

RainbowKit groups wallets under a `groupName`. Wyllet takes one ordered array of called presets, and groups wallets in the UI on its own: detected and recently used first, then the rest.

```ts title="Before"
wallets: [{ groupName: 'Recommended', wallets: [metaMaskWallet, rainbowWallet, walletConnectWallet] }]
```

```ts title="After"
import { metaMaskWallet, rainbowWallet, walletConnectWallet } from 'wyllet'

wallets: [metaMaskWallet(), rainbowWallet(), walletConnectWallet()]
```

Wallets with `featured: false` are listed in a lower group. Installed browser wallets you did not list are still detected through EIP-6963. Wyllet bundles official artwork only for its default wallets (MetaMask, Phantom, Rabby, OKX and WalletConnect). `coinbaseWallet()`, `rainbowWallet()` and `trustWallet()` show a neutral monogram unless the extension is installed or you pass an icon through `overrides`. See [Wallets](/docs/wallets).

### 10. Port custom wallets

A custom wallet is a plain object. The main renames are `iconUrl` to `icon` and the mobile WalletConnect link to `walletConnect.mobileUri`.

```ts
import type { Wallet } from 'wyllet'

const acme: Wallet = {
  id: 'acme',
  name: 'Acme',
  icon: 'https://acme.xyz/icon.png',
  iconBackground: '#ffffff',
  rdns: 'xyz.acme',
  walletConnect: { mobileUri: (uri) => `acme://wc?uri=${encodeURIComponent(uri)}` },
  downloadUrls: { browserExtension: 'https://acme.xyz/download', ios: '…', android: '…' },
}
```

To give a wallet a dedicated wagmi connector, set `createConnector` to a function that takes no arguments and returns a wagmi `CreateConnectorFn`.

### 11. Move recent transactions

```tsx
const { addTransaction } = useWylletActivity()

const hash = await writeContractAsync({ /* ... */ })
addTransaction({ hash, description: 'Mint 1 NFT' })
```

There is no `showRecentTransactions` flag. Transactions appear in the account panel's Activity tab, with pending and confirmed toasts. See [Activity and transactions](/docs/activity).

## What works differently

- **Presentations.** The panel opens as a side drawer by default. Set `appearance.presentation` to `'popover'` to anchor it to the button, or `'modal'` for a centered dialog. Phones get a draggable bottom sheet. See [Presentations](/docs/presentations).
- **Activity.** The Activity tab records connects, disconnects, network switches and sign-ins as well as transactions, and you can add your own entries with `log`. Pending transactions are watched again after a reload.
- **Toasts.** `useWylletToast()` gives you themed, promise-aware notifications that match the panel. See [Toasts](/docs/toasts).
- **Tokens.** The account panel has a Tokens tab with balances for a token list you define in code, with pinning, sorting and optional user import. See [Tokens](/docs/tokens).
- **Networks.** Switching networks happens in the account panel's Networks tab, which also shows the live gas price and a wrong-network banner.
- **Gating.** `ConnectGate` renders content only when the user is connected, on a supported network and signed in. See [ConnectGate](/docs/connect-gate).
- **All wallets.** With a WalletConnect project id, the WalletConnect option opens a searchable directory of wallets from the WalletConnect registry, and each opens its own app on phones. See [All wallets](/docs/all-wallets).
- **Styles.** Wyllet injects its CSS, so there is no stylesheet import. Set `injectStyles={false}` and import `wyllet/styles.css` if you want to load it yourself.
- **Keyboard.** Set `shortcut="mod+k"` to toggle the panel from the keyboard. In the wallet list, arrow keys move and number keys pick a wallet.
- **Dependencies.** Wyllet has no third-party runtime dependencies. See [Security](/docs/security).

## Checklist

- `@rainbow-me/rainbowkit` removed from `package.json` and the lockfile.
- The RainbowKit stylesheet import removed.
- `projectId` renamed to `walletConnectProjectId`.
- `@walletconnect/ethereum-provider` installed if you use WalletConnect.
- Every `ConnectButton`, `ConnectButton.Custom` and modal hook replaced.
- The auth adapter moved to the `auth` prop, with `getSession` if you restore sessions.
- Your app still connects, switches networks and signs in. Try it in the [playground](/playground) first if you want to compare settings.

---

# FAQ

> Answers to common questions about Wyllet: pricing, wallets, chains, Next.js, styling, security and data collection.

Source: https://wyllet.dev/docs/faq

Short answers to the questions we hear most. Each one links to the page with the details.

## Is Wyllet free?

Yes. Wyllet is open source under the MIT license, so you can use it in commercial and closed-source projects. The source is on [GitHub](https://github.com/wyllet/wyllet).

## Does it work without WalletConnect?

Yes. Without a `walletConnectProjectId`, Wyllet connects browser extensions (detected through EIP-6963 or `window.ethereum`) and any wallets with a dedicated wagmi connector. You also skip installing `@walletconnect/ethereum-provider`. Add a project id when you want QR codes and mobile wallets. See [WalletConnect](/docs/walletconnect).

## Which wallets are supported?

`defaultWallets()` lists MetaMask, Phantom, Rabby, OKX Wallet and WalletConnect, each with its official icon. Presets also exist for Coinbase Wallet, Rainbow and Trust Wallet. Any other extension that announces itself through EIP-6963 is detected automatically. With WalletConnect enabled, **All wallets** opens a searchable directory from the WalletConnect registry. You can also define your own wallets. See [Wallets](/docs/wallets) and [All wallets](/docs/all-wallets).

## Does it support Solana or other non-EVM chains?

No. Wyllet is built on wagmi and viem, so it connects EVM accounts only. Multi-chain wallets such as Phantom connect through their EVM provider, and the All wallets directory only lists wallets that support EVM chains.

## Can I add a custom or private chain?

Yes. Any EVM chain works. Use a chain from `viem/chains`, or define one with `customChain({ id, name, rpcUrl })` and optionally give it an icon, an explorer and a native currency. See [Chains](/docs/chains).

## Does it work with Next.js and server rendering?

Yes. The build ships with the `'use client'` directive, and Wyllet does not touch `window`, `document` or `localStorage` while rendering on the server. Put the providers in a client component. Content inside `ConnectGate` is never rendered into server HTML. See [Next.js](/docs/nextjs).

## Which React version do I need?

React 18 or later. The other peers are wagmi v3, viem 2 (`^2.15.0`) and `@tanstack/react-query` v5. See [Installation](/docs/installation).

## What does it add to my bundle?

Wyllet has no direct runtime dependencies. It only imports React, wagmi, viem and react-query, which your app already uses, plus the optional WalletConnect provider if you enable it. Even the QR code encoder is built in. A test in CI fails if any other import appears in the build. See [Security](/docs/security).

## Does Wyllet collect data or include analytics?

No. Wyllet has no analytics or telemetry and makes no network requests of its own. The one exception is opt-in: when WalletConnect is enabled and a user opens All wallets, it loads the wallet list and logos from WalletConnect's registry. Turn that off with `appearance={{ walletDirectory: false }}`. RPC traffic goes through the transports in your wagmi config.

## Can I use my own button?

Yes. `useWylletButton()` returns the connection state and `open` functions, so you can render any element. `useWyllet()` opens and closes the panel from anywhere. See [WylletButton](/docs/wyllet-button) and [Hooks](/docs/hooks).

## Does it work with Tailwind?

Yes. Pass Tailwind classes per element with the `classNames` prop (slots: `overlay`, `panel`, `island`, `walletRow`, `primaryButton`, `identityCard`, `toast`). Every design token is also a CSS variable you can set from your own CSS. See [Class names](/docs/class-names) and [Theming](/docs/theming).

## Can I use it with a strict Content Security Policy?

Partly. Set `injectStyles={false}` and import `wyllet/styles.css` to load the base stylesheet as a file. Wyllet still renders a small inline `<style>` element for theme variables, so `style-src` needs to allow inline styles in 1.0. You also need `img-src data:` for the built-in icons and `connect-src` entries for your RPC and WalletConnect. See [Security](/docs/security#content-security-policy).

## Does it work on mobile?

Yes. On phones the panel opens as a draggable bottom sheet (set `appearance.mobileSheet` to `false` to turn that off). WalletConnect wallets open through their own app links instead of a QR code, and the All wallets directory opens the exact wallet the user picks. See [All wallets](/docs/all-wallets).

## How do I report a bug?

Open an issue at [github.com/wyllet/wyllet/issues](https://github.com/wyllet/wyllet/issues) with the Wyllet, wagmi and React versions, your browser and wallet, and steps to reproduce. For security problems, use a [private security advisory](https://github.com/wyllet/wyllet/security/advisories/new) instead.

## How do I get help?

Email [support@wyllet.dev](mailto:support@wyllet.dev), or follow [@wylletdev on X](https://x.com/wylletdev) for releases and updates. The [AI assistants guide](/docs/ai-assistants) explains how to get correct answers from coding assistants.

---

# How Wyllet compares

> How Wyllet compares with RainbowKit, ConnectKit, Reown AppKit, Dynamic, Privy, thirdweb and Web3-Onboard: license, wagmi version, dependencies and features.

Source: https://wyllet.dev/compare

Checked on October 12, 2026. Versions, licenses and dependency counts come from the npm registry; features, chains and pricing from each project’s documentation and pricing page.

## Choose Wyllet when

- Your dApp is on wagmi v3, or you are upgrading to it.
- Users should see their tokens and activity without you building those screens.
- You want a drawer, popover or inline panel instead of only a modal.
- You want no hosted service, account or usage-based pricing, and no extra dependencies.

## Choose RainbowKit or ConnectKit when

- Your app is on wagmi v2 and will stay there for now.
- A modal connect flow is all you need.
- With ConnectKit: you want its optional email and passkey sign-up.

## Choose a hosted platform when

- People sign up with email, phone or social accounts.
- You need embedded wallets created for users who have none.
- You support Solana, Bitcoin or other non-EVM chains.
- Wyllet does none of these, by design.

## Open-source connect kits

Free libraries you install and theme yourself. These are the closest alternatives to Wyllet.

| | Wyllet | RainbowKit | ConnectKit | Web3-Onboard |
| --- | --- | --- | --- | --- |
| License | MIT | MIT | BSD-2-Clause | MIT |
| Built on | wagmi v3 and viem | wagmi v2 and viem | wagmi v2 and viem (v3 in progress) | Its own stack (wagmi v2 module) |
| Direct runtime dependencies | 0 | 7 | 9 | 12 (core) |
| Presentations | Drawer, popover, modal, mobile sheet and inline | Modal | Modal | Modal and a corner account widget |
| After connecting | Tokens, activity, networks and receive QR | Balance, chain switcher, and transactions your app registers | Balance and network switcher | Balance, up to 5 tokens and network switcher |
| Sign-In With Ethereum | Built in | NextAuth add-on | Built in | Not built in |
| Theming | 4 presets, CSS variable tokens, per-element class names | 3 presets and custom themes | 8 presets and experimental CSS variables | Presets and CSS variables |
| Latest release | 1.1.0, Oct 2026 | 2.2.11, May 2026 | 1.9.2, Mar 2026 | 2.24.1, Apr 2025 |

## Hosted wallet platforms

Services with sign-up, embedded wallets and more chains, tied to an account and priced by monthly active users.

| | Wyllet | Reown AppKit | Dynamic | Privy | thirdweb Connect |
| --- | --- | --- | --- | --- | --- |
| License | MIT | Reown Community License (source-available) | MIT SDK, hosted service | Apache-2.0 SDK, hosted service | Apache-2.0 SDK, hosted service |
| Account and pricing | None, free | Project ID; free up to 500 MAU | Environment ID; free up to 1,000 MAU | App ID; free up to 499 MAU | Client ID required |
| Email and social login | No | Yes | Yes | Yes | Yes |
| Embedded wallets | No | Yes | Yes | Yes | Yes |
| Chains | EVM | EVM, Solana, Bitcoin and more | EVM, Solana, Bitcoin and more | EVM, Solana and Bitcoin | EVM |
| wagmi | Built on wagmi v3 | Adapter for v2 (v3 in beta) | Optional connector (v2) | Optional package | Own stack (v2 adapter) |
| Direct runtime dependencies | 0 | 13 | 29 | 42 | 31 |
| Presentations | Drawer, popover, modal, mobile sheet and inline | Modal | Modal, dropdown and inline | Modal | Modal and inline |

## Wyllet vs RainbowKit

RainbowKit is the closest alternative: a free, MIT-licensed React kit on wagmi and viem with a provider, a connect button and a config helper. Its latest release (2.2.11) supports wagmi v2 only, while Wyllet is built for wagmi v3.

RainbowKit opens its connect, account and chain screens as modals. Its account modal shows the native balance, and recent transactions appear only when your app registers each one. Wyllet adds drawer, popover and inline presentations, a token list, an activity timeline and toasts. RainbowKit has seven direct runtime dependencies (vanilla-extract among them); Wyllet has none.

Most of a switch is renaming. The migration guide maps every RainbowKit concept to its Wyllet equivalent.

Sources: [npm](https://www.npmjs.com/package/@rainbow-me/rainbowkit), [Docs](https://rainbowkit.com/docs/introduction), [Recent transactions](https://rainbowkit.com/docs/recent-transactions)

## Wyllet vs ConnectKit

ConnectKit, from Family, is a free React kit on wagmi with eight visual presets and built-in SIWE. Its latest release (1.9.2) targets wagmi v2 and declares React 17 and 18 as peers, so it doesn't yet list React 19; a wagmi v3 version is in progress.

It can optionally offer email, phone and passkey sign-up through Aave Account, which Wyllet does not. Its account view shows the balance and a network switcher, with no token list or activity timeline. It has nine direct runtime dependencies, including styled-components and framer-motion.

Sources: [npm](https://www.npmjs.com/package/connectkit), [Docs](https://family.co/docs/connectkit)

## Wyllet vs Reown AppKit

AppKit, formerly Web3Modal, is the connect UI from the company behind WalletConnect. It covers EVM, Solana and Bitcoin, adds email and social login, and ships views for tokens, activity, send, swap and on-ramp. It runs on React, Vue, Svelte, vanilla JS and mobile.

It is source-available under the Reown Community License rather than an open-source license: free up to 500 monthly active users, with paid plans above that, and it uses Reown’s hosted services. Its wagmi adapter supports wagmi v2, with v3 in beta. Pick AppKit if you need several chain families or social login; pick Wyllet for an MIT-licensed, EVM-only kit with no usage limits.

Sources: [License](https://github.com/reown-com/appkit/blob/main/LICENSE.md), [Pricing](https://reown.com/pricing), [Docs](https://docs.reown.com/appkit/overview)

## Wyllet vs Dynamic

Dynamic is a hosted authentication and wallet platform: email and social sign-in, embedded wallets, and a widget that opens as a modal, a dropdown or inline. It supports EVM, Solana, Bitcoin and many other chains.

You configure it in Dynamic’s dashboard with an environment ID. It is free up to 1,000 monthly active users and paid above that. The React SDK has 29 direct runtime dependencies, and wagmi is an optional connector (v2). Choose Dynamic when sign-up and embedded wallets matter more than owning the UI.

Sources: [Pricing](https://www.dynamic.xyz/pricing), [Docs](https://www.dynamic.xyz/docs)

## Wyllet vs Privy

Privy is a hosted login and embedded-wallet service: email, SMS, social accounts and passkeys, with wallets created for users who don’t have one. It supports EVM, Solana and Bitcoin, and React, React Native and native mobile.

It is free up to 499 monthly active users and paid above that. Its UI is a login modal; there is no prebuilt account panel with balances or activity. The React SDK has 42 direct runtime dependencies. Privy and Wyllet solve different problems: Privy onboards people without wallets, Wyllet gives people with wallets a polished way to connect and manage them.

Sources: [Pricing](https://www.privy.io/pricing), [Docs](https://docs.privy.io)

## Wyllet vs thirdweb Connect

thirdweb’s ConnectButton is part of the thirdweb SDK, which runs on its own stack rather than wagmi. It offers a modal or inline connect UI, email, phone, passkey and social login with in-app wallets, and a full account screen with tokens, NFTs, history, send, receive and buy.

It needs a thirdweb client ID, and removing thirdweb branding is a paid-plan feature. The SDK package has 31 direct runtime dependencies. Choose thirdweb if you already use its platform; choose Wyllet to stay on plain wagmi with no account or branding requirements.

Sources: [ConnectButton](https://portal.thirdweb.com/react/v5/ConnectButton), [Pricing](https://thirdweb.com/pricing)

## Wyllet vs Web3-Onboard

Web3-Onboard is a framework-agnostic connect library with its own Svelte-based UI, plus React, Vue and Solid wrappers. It is MIT licensed and adds a corner Account Center showing the balance and up to five extra tokens.

It does not build on wagmi (a separate module supports wagmi v2) and has no built-in SIWE. The core package was last published in April 2025, and the project now lives under the thirdweb organization on GitHub.

Sources: [npm](https://www.npmjs.com/package/@web3-onboard/core), [GitHub](https://github.com/thirdweb-dev/web3-onboard)