# Wyllet

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

Wyllet is published on npm as `wyllet` (current version 1.1.0, MIT). Install: `pnpm add wyllet wagmi viem @tanstack/react-query`. Source: https://github.com/wyllet/wyllet

Key facts:
- Peer dependencies only: react >=18, react-dom >=18, wagmi ^3, viem ^2.15, @tanstack/react-query >=5. Optional: @walletconnect/ethereum-provider for QR and mobile wallets.
- Main exports: WylletProvider, WylletButton, WylletEmbed, getDefaultConfig, useWyllet, useWylletButton, useWylletToast, useWylletActivity, useWylletAuth, ConnectGate, customChain, popularChains, withDefaultTokens, obsidianTheme, porcelainTheme, auroraTheme, terminalTheme.
- Every page below is available as Markdown by adding `.md` to its URL, or by requesting it with `Accept: text/markdown`.

**Rules for AI coding assistants**

Follow these when generating a Wyllet integration. Full guide: https://wyllet.dev/docs/ai-assistants.md

- Install `wyllet wagmi viem @tanstack/react-query`. Add `@walletconnect/ethereum-provider` only when `walletConnectProjectId` is set.
- Build the wagmi config with `getDefaultConfig({ appName, chains, walletConnectProjectId })` from `wyllet`. The first chain is the default. Use `customChain()` for chains not in `viem/chains`.
- Put providers in a `'use client'` component, nested `WagmiProvider` > `QueryClientProvider` > `WylletProvider`. All Wyllet components and hooks render inside `WylletProvider`.
- Do not import any CSS: Wyllet injects its styles.
- Render `<WylletButton />` for the connect button. For a custom trigger use `useWylletButton()`, whose `open(el)` takes an element; `useWyllet().openConnect({ anchor })` takes an options object.
- The `⌘K` shortcut is opt-in: `shortcut="mod+k"`. The popover presentation needs an anchor element.
- In Next.js set `appUrl` and `ssr: true` in `getDefaultConfig`, and create the `QueryClient` inside `useState`.
- `burnerWallet()` is for local development only. Never use it in production.
- Only use props, hooks and options documented on this site.

**Minimal integration**

```tsx
'use client'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { useState, type ReactNode } from 'react'
import { base, mainnet } from 'viem/chains'
import { WagmiProvider } from 'wagmi'
import { getDefaultConfig, WylletButton, WylletProvider } from 'wyllet'

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

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

// Anywhere inside <Providers>: <WylletButton />
```

## Getting started

- [Introduction](https://wyllet.dev/docs/introduction.md): What Wyllet is, what it includes, and how it fits into a wagmi + viem dApp.
- [Installation](https://wyllet.dev/docs/installation.md): Install Wyllet and its peer dependencies, and enable WalletConnect.
- [Quick start](https://wyllet.dev/docs/quick-start.md): Add a working connect button to a React dApp in a few minutes.
- [Next.js](https://wyllet.dev/docs/nextjs.md): Use Wyllet with the Next.js App Router, server components and SSR.
- [Build with AI assistants](https://wyllet.dev/docs/ai-assistants.md): Give Cursor, Claude Code, Copilot or ChatGPT the Wyllet docs and the rules for a correct integration.

## Core concepts

- [Configuration](https://wyllet.dev/docs/configuration.md): Create a wagmi config with getDefaultConfig: app info, chains, transports and wallets.
- [WylletProvider](https://wyllet.dev/docs/provider.md): Every WylletProvider prop: theme, appearance, tokens, auth, messages and callbacks.
- [WylletButton](https://wyllet.dev/docs/wyllet-button.md): The Island button, its display options, and building your own trigger with useWylletButton.
- [Presentations](https://wyllet.dev/docs/presentations.md): Open the panel as a drawer, an anchored popover, a modal or a mobile bottom sheet.

## Customization

- [Theming](https://wyllet.dev/docs/theming.md): Theme presets, design tokens as CSS variables, light and dark mode, and custom themes.
- [Class names](https://wyllet.dev/docs/class-names.md): Attach your own classes (including Tailwind) to individual Wyllet elements.
- [Translations](https://wyllet.dev/docs/i18n.md): Rename any string or translate the entire interface.

## Wallets

- [Wallets](https://wyllet.dev/docs/wallets.md): Built-in wallets, EIP-6963 detection, custom wallets and connectors.
- [All wallets](https://wyllet.dev/docs/all-wallets.md): The searchable WalletConnect directory with official logos and per-wallet app links.
- [WalletConnect](https://wyllet.dev/docs/walletconnect.md): Project IDs, domain allowlists, QR codes and how mobile app links work.

## Chains and tokens

- [Chains](https://wyllet.dev/docs/chains.md): popularChains, customChain() and arranging the Networks tab with chainOrder.
- [Tokens](https://wyllet.dev/docs/tokens.md): Token lists, withDefaultTokens, pinning, sorting and user token import.

## Features

- [Account panel](https://wyllet.dev/docs/account-panel.md): Account summary, identity card, tokens, activity, networks and receive.
- [Activity and transactions](https://wyllet.dev/docs/activity.md): Track transactions and log custom events in the activity timeline.
- [Toasts](https://wyllet.dev/docs/toasts.md): Themed, promise-aware notifications with useWylletToast.
- [Sign-In With Ethereum](https://wyllet.dev/docs/siwe.md): Add a SIWE verification step to the connect flow with an auth adapter.
- [ConnectGate](https://wyllet.dev/docs/connect-gate.md): Render content only when users are connected, on a supported network and signed in.

## Reference

- [Hooks](https://wyllet.dev/docs/hooks.md): API reference for every Wyllet hook: useWyllet, useWylletButton, useWylletToast, useWylletActivity, useWylletAuth and more.
- [Components](https://wyllet.dev/docs/components.md): API reference for every Wyllet component: WylletButton, ConnectGate, Avatar, ChainIcon, TokenIcon, QRCode and more.
- [Utilities and types](https://wyllet.dev/docs/utilities.md): Helper functions and the TypeScript types Wyllet exports.

## Guides

- [Security](https://wyllet.dev/docs/security.md): Zero direct runtime dependencies, provenance, CSP and what Wyllet does and does not do.
- [Migrate from RainbowKit](https://wyllet.dev/docs/migrate-from-rainbowkit.md): Map RainbowKit concepts to Wyllet and switch a dApp over step by step.
- [FAQ](https://wyllet.dev/docs/faq.md): Answers to common questions about Wyllet: pricing, wallets, chains, Next.js, styling, security and data collection.

## Blog

- [Introducing Wyllet 1.0](https://wyllet.dev/blog/introducing-wyllet.md): An open-source wallet connector for React dApps, built on wagmi and viem, with its own look and no direct runtime dependencies.
- [How we shipped a wallet connector with zero direct runtime dependencies](https://wyllet.dev/blog/zero-runtime-dependencies.md): Why we removed every third-party runtime package, wrote our own QR encoder, and publish with npm provenance.
- [Pretty QR codes that still scan](https://wyllet.dev/blog/qr-codes-that-scan.md): Our first round-dot QR design decoded in 1 of 40 automated scans. How we measured it, what we shipped, and the test that keeps it honest.
- [Why "WalletConnect" kept opening the wrong wallet](https://wyllet.dev/blog/all-wallets-on-mobile.md): Bare wc: links open the phone's default wallet. The All wallets directory fixes it with each wallet's own app link.

## Comparison

- [How Wyllet compares](https://wyllet.dev/compare.md): How Wyllet compares with RainbowKit, ConnectKit, Reown AppKit, Dynamic, Privy, thirdweb and Web3-Onboard: license, wagmi version, dependencies and features.

## Optional

- [Full documentation in one file](https://wyllet.dev/llms-full.txt)
- [Interactive playground](https://wyllet.dev/playground): every option, with generated code
- [Changelog](https://wyllet.dev/changelog)