TxKitProvider

Root provider component that initializes wagmi, TanStack Query, and txKit context. Wrap your app with TxKitProvider to use any txKit component.

Bundle: 2.1 kB JS (gzip) + 0.3 kB CSS (gzip). Wagmi, viem, and TanStack Query are peer dependencies and not counted - any Web3 app already pays for them.

Import

import { TxKitProvider } from '@txkit/react'

Standalone Mode

Default mode - txKit creates and manages WagmiProvider and QueryClientProvider internally.

import { TxKitProvider, ConnectWallet } from '@txkit/react'
import { mainnet, arbitrum } from 'viem/chains'
import { http } from 'viem'
 
const App = () => (
  <TxKitProvider config={{
    chains: [mainnet, arbitrum],
    transports: {
      [mainnet.id]: http(),
      [arbitrum.id]: http(),
    },
  }}>
    <ConnectWallet />
  </TxKitProvider>
)

Config Props

• chains - At least one chain is required. Each chain needs a matching transport entry.
• transports - Map of chainId to viem transport. Use http() for public RPC or http('https://your-rpc.com') for custom endpoints.
• walletConnectProjectId - Required to enable WalletConnect. Get one at cloud.reown.com.
• variant - Visual style preset. See Theming - Visual Variants.
• autoConnect - When true, reconnects the last used wallet on page reload.
• pollingInterval - Block polling interval in ms. Drives TokenBalance refetch cadence and underlying wagmi watchers.
• licenseKey - Reserved for the Pro tier. Components that gate Pro features (deferred) check this via useTxKit().isProEnabled.

WalletConfig

config.wallets accepts an array of WalletConfig objects. Omit it for the default set (injected wallets, WalletConnect, Coinbase Wallet).

import { injected, walletConnect } from 'wagmi/connectors'
 
<TxKitProvider config={{
  chains: [ mainnet ],
  transports: { [mainnet.id]: http() },
  wallets: [
    {
      id: 'metamask',
      name: 'MetaMask',
      icon: 'https://example.com/metamask.svg',
      createConnector: injected({ target: 'metaMask' }),
    },
    {
      id: 'walletconnect',
      name: 'WalletConnect',
      createConnector: walletConnect({ projectId: 'YOUR_ID' }),
    },
  ],
}}>

Embedded Mode

Use embedded mode when your app already has its own WagmiProvider and QueryClientProvider. txKit will use the existing providers instead of creating new ones.

import { WagmiProvider, createConfig } from 'wagmi'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { TxKitProvider, ConnectWallet } from '@txkit/react'
import { mainnet } from 'viem/chains'
import { http } from 'viem'
import { injected } from 'wagmi/connectors'
 
const wagmiConfig = createConfig({
  chains: [mainnet],
  transports: { [mainnet.id]: http() },
  connectors: [injected()],
})
 
const queryClient = new QueryClient()
 
const App = () => (
  <WagmiProvider config={wagmiConfig}>
    <QueryClientProvider client={queryClient}>
      <TxKitProvider embedded config={{ theme: 'dark' }}>
        <ConnectWallet />
      </TxKitProvider>
    </QueryClientProvider>
  </WagmiProvider>
)

Embedded Config Props

• variant - Visual style preset. See Theming - Visual Variants.

In embedded mode, chains, transports, and wallets are managed by the external WagmiProvider.

Integrating with an Existing Wallet Kit

If your app already uses RainbowKit, AppKit, ConnectKit, Privy, or Dynamic, use embedded mode. txKit will reuse the existing WagmiProvider/QueryClientProvider instead of creating its own.

// RainbowKit + txKit (shared wagmi config)
<WagmiProvider config={config}>
  <QueryClientProvider client={queryClient}>
    <RainbowKitProvider>
      <TxKitProvider embedded config={{ theme: 'dark' }}>
        <App />
      </TxKitProvider>
    </RainbowKitProvider>
  </QueryClientProvider>
</WagmiProvider>

The same pattern works for AppKit, ConnectKit, Privy, Dynamic. See Embedded Mode for the full setup.

useTxKit

Hook to access txKit context from any component inside TxKitProvider.

import { useTxKit } from '@txkit/react'
 
const MyComponent = () => {
  const { theme, setTheme, config } = useTxKit()
 
  return (
    <button onClick={() => setTheme('dark')}>
      Current theme: {theme}
    </button>
  )
}

Return Value

Throws ProviderNotFoundError if used outside of TxKitProvider. See ProviderNotFoundError.

ResolvedConfig

The config field is the resolved snapshot - all defaults applied, all optional fields filled in. Use this when you need to read the wagmi configuration at runtime (e.g. to construct a transport for an out-of-band RPC call):

The chains vs displayChains distinction matters in testnet mode: mainnet is registered with wagmi (so ENS works) but hidden from the chain selector UI to keep test users on Sepolia.

Type reference

txKit's runtime types live in the TxKit global namespace - import them through types-only imports if your build needs explicit declarations:

import type { } from '@txkit/react' // side-effect import to load global types
 
type MyTheme = TxKit.Theme           // 'light' | 'dark' | 'auto'
type MyVariant = TxKit.Variant       // 'default' | 'soft' | 'sharp' | 'rounded'
type MyConfig = TxKit.Config         // discriminated: ConfigTestnet | ConfigCustom
type MyResolved = TxKit.ResolvedConfig
type MyContext = TxKit.Context       // what useTxKit() returns
type MyEmbedded = TxKit.EmbeddedConfig
type MyWallet = TxKit.WalletConfig

TxKit.Config is a discriminated union:

• ConfigTestnet (testnet: true) - chains + transports are optional, filled from Sepolia defaults
• ConfigCustom (testnet?: false) - chains + transports are required