Headless

💡 Headless is in early-access at the moment and available to limited users. Contact us to get access.

AppKit Headless allows developers to build a fully customizable “Connect” experience powered by AppKit’s existing features without using the AppKit modal. Headless exposes wallet discovery, rendering WalletConnect QR codes, and social provider flows via simple hooks and utility functions.

Installation

Headless requires AppKit to be configured with the headless flag. See the installation docs before getting started and make sure you’re enabling headless as expected.

createAppKit({
  ...
  features: {
    headless: true
  }
})

useAppKitWallets

The essential hook for accessing all types of wallets and methods to build your custom connection user interface.

useAppKitWallets.tsx

const { wallets, wcWallets, isFetchingWallets, isFetchingWcUri, isInitialized, wcUri, wcError, connectingWallet, page, count, fetchWallets, connect, resetWcUri } =
  useAppKitWallets()

Returns

wallets · WalletItem[]

List of wallets for the initial connect view including WalletConnect wallets and injected wallets together. If the user doesn’t have any injected wallets, it’ll fill the list with the most ranked WalletConnect wallets.

wcWallets · WalletItem[]

List of WalletConnect wallets from Wallet Guide API. Useful to display all available WalletConnect wallets in a separate Search Wallets view.

isFetchingWallets · boolean

Boolean that indicates if WalletConnect wallets are being fetched.

isFetchingWcUri · boolean

Boolean that indicates if a WalletConnect URI is being fetched.

isInitialized · boolean

Boolean that indicates if the AppKit is initialized. It’s useful to render a fallback UI when the AppKit initializes and detects all injected wallets.

wcUri · string | undefined

The current WalletConnect URI for QR code display. This is set when connecting to a WalletConnect wallet. Reset with resetWcUri().

wcError · boolean

Boolean that indicates if there was an error fetching the WalletConnect URI.

connectingWallet · WalletItem | undefined

The wallet currently being connected to. This is set when a connection is initiated and cleared when it completes or fails. For WalletConnect wallets, resetWcUri() should be called to clear the state.

page · number

The current page number of WalletConnect wallets.

count · number

The total number of available WalletConnect wallets based on the AppKit configurations and given parameters.

fetchWallets · (options?: FetchWalletsOptions) => Promise<void>

Function to fetch WalletConnect wallets from the explorer API. Allows you to list, search, and paginate through the wallets.

interface FetchWalletsOptions {
  /** Page number to fetch (default: 1) */
  page?: number
  /** @deprecated Use `search` instead */
  query?: string
  /** Search query to filter wallets. When provided, switches to search mode. */
  search?: string
  /** Number of entries per page. Defaults to 40 for list mode, 100 for search mode. */
  entries?: number
  /** Filter wallets by badge type ('none' | 'certified') */
  badge?: 'none' | 'certified'
  /** Wallet IDs to include. Overrides the global includeWalletIds config when provided. */
  include?: string[]
  /** Wallet IDs to exclude. Overrides the default exclude list when provided. */
  exclude?: string[]
}

connect · (wallet: WalletItem, namespace?: ChainNamespace) => Promise<void>

Function to connect to a wallet. For WalletConnect wallets: initiates WC connection and returns the URI with the wcUri state. For injected connectors: triggers the extension/wallet directly.

resetWcUri · () => void

Function to reset the WC URI. Useful to keep the connectingWallet state in sync with the WC URI. Can be called when the QR code is closed.

Examples

Build a Connect UI

The useAppKitWallets hook returns a list of injected and WalletConnect wallets that let you render directly in the connect page.

If you configure your AppKit as multi-chain, we suggest rendering a namespace selection component where users should select which namespace to connect when using browser extensions. This could be achieved with the connectors array of the WalletItem.

If a user selects a WalletConnect wallet, you can show the QR code to the users and let them scan it with their preferred wallets. To handle the QR flows, you can use the isFetchingWcUri, wcUri, and resetWcUri props from the useAppKitWallets hook.

ConnectView.tsx

import React, { useState } from 'react'
import type { WalletItem } from '@reown/appkit'
import type { ChainNamespace } from '@reown/appkit/networks'
import { useAppKitWallets } from '@reown/appkit/react'
import { NamespaceSelectionDialog } from './NamespaceDialog'
import { WalletConnectQRDialog } from './WalletConnectQRDialog'

function ConnectView() {
  const { wallets, connect } = useAppKitWallets()
  const [selectedWallet, setSelectedWallet] = useState<WalletItem | null>(null)

  async function handleConnect(wallet: WalletItem, namespace?: ChainNamespace) {
    await connect(wallet, namespace)
      .then(() => {
        toast({ title: 'Connected', status: 'success' })
      })
      .catch(() => {
        toast({ title: 'Connection declined', status: 'error' })
      })
  }

  return (
    <>
      {wallets.map(wallet => (
        <WalletListItem
          key={wallet.id}
          wallet={wallet}
          onConnect={() => {
            if (wallet.connectors.length > 1) {
              setSelectedWallet(wallet)
            } else {
              handleConnect(wallet, wallet.connectors[0]?.chain)
            }
          }}
        />
      ))}
      <NamespaceSelectionDialog
        wallet={selectedWallet}
        onSelect={handleConnect}
        onClose={() => setSelectedWallet(null)}
      />
      <WalletConnectQRDialog />
    </>
  )
}

Search and Connect to WalletConnect Wallets

WalletConnect supports 500+ wallets. You can let users search for their own wallets to connect to your app.

AllWalletsView.tsx

import React, { useState, useEffect } from 'react'
import { useAppKitWallets } from '@reown/appkit/react'

function AllWalletsView() {
  const { wcWallets, isFetchingWcUri, isFetchingWallets, fetchWallets, connect, page } =
    useAppKitWallets()
  const [inputValue, setInputValue] = useState('')
  const searchQuery = useDebounceValue(inputValue, 500)

  useEffect(() => {
    fetchWallets?.()
  }, [])

  useEffect(() => {
    if (searchQuery.length > 0) {
      fetchWallets?.({ search: searchQuery })
    } else {
      fetchWallets?.()
    }
  }, [searchQuery])

  function handleLoadMore() {
    if (searchQuery.length > 0) {
      fetchWallets?.({ page: page + 1, search: searchQuery })
    } else {
      fetchWallets?.({ page: page + 1 })
    }
  }

  return (
    <>
      <input
        type="text"
        placeholder="Search wallets..."
        value={inputValue}
        onChange={e => setInputValue(e.target.value)}
      />
      {isFetchingWallets && <div>Loading wallets...</div>}
      {wcWallets.map(wallet => {
        return <WalletListItem key={wallet.id} wallet={wallet} onConnect={connect} />
      })}
      <button onClick={handleLoadMore} disabled={isFetchingWallets}>
        Load More
      </button>
    </>
  )
}

Demo

Headless Playground

You can check our demo app to play around with an example Headless implementation

Source code

See the source code of the example Headless implementation.