Hooks

Every txKit component is built on a public headless hook. Hooks are exported from the package root - import everything from @txkit/react. There are no subpath exports.

Index

useDisplayUri

WalletConnect-only. Captures the pairing URI emitted asynchronously by the WC connector after connect() is called, so you can render a QR code or copy a deep link before the wallet pairs.

import { useDisplayUri } from '@txkit/react'
 
const { displayUri, isLoadingUri } = useDisplayUri(connector, isPending)

The URI is one-shot - after pairing, displayUri becomes undefined. The hook reads connector.emitter (a wagmi runtime property), so it returns undefined for connectors that don't emit display_uri (injected, Coinbase Wallet) - no error, just falsy values.

useFlowState

Subscribes to a single flow entry from the flow store. Place anywhere inside TxKitProvider - powers FlowSteps, FlowProgress, and FlowToast under the hood.

import { useFlowState, DEFAULT_FLOW_ID } from '@txkit/react'
 
const entry = useFlowState() // defaults to DEFAULT_FLOW_ID
 
if (!entry) {
  return null
}
 
const { flow, steps, actions } = entry
return <pre>{flow.status} - step {flow.currentStepIndex} of {steps.length}</pre>

FlowEntry shape: { flow: FlowState; steps: FlowStep[]; actions: FlowActions }. Use useTransactionFlow directly when you want the headless hook (you own the steps array). Use useFlowState when you're building a sibling visualizer that just observes whatever TransactionButton mounted.

useFlowStore

Raw access to the flow store handle. Returns null when used outside TxKitProvider. Power-user tool for registering custom flows or implementing your own compound components.

import { useFlowStore } from '@txkit/react'
 
const store = useFlowStore()
const allFlows = store ? Array.from(store.entries.entries()) : []

The flow store uses useSyncExternalStore semantics - direct mutations on store.entries will not trigger re-renders. Use setFlowEntry and notifyFlowListeners (also exported) for that.

useBalanceInvalidation

Manual refresh of TanStack Query balance caches. Use after operations that change balances outside of txKit's awareness - external bridges, faucet funding, manual wagmi writeContract calls.

import { useBalanceInvalidation } from '@txkit/react'
 
const { invalidateAll, invalidateAffected } = useBalanceInvalidation()
 
// After a faucet drip
invalidateAll()
 
// After a custom tx whose receipt logs you have
invalidateAffected(receipt.logs, senderAddress)

useTransactionFlow calls invalidateAffected automatically after each step completes - you only need this hook for balance changes that happen outside the flow.

useBalanceContext

Read access to the BalanceWatcher context value. BalanceWatcher is the invisible component inside TxKitProvider that watches useWatchBlockNumber and throttles balance-query invalidations on new blocks (configurable via config.blockWatching.{ enabled, throttleMs }). It is also gated by useActiveBrowserTab - background tabs do not invalidate.

import { useBalanceContext } from '@txkit/react'
 
const balanceCtx = useBalanceContext()
 
if (balanceCtx) {
  console.log('Last block:', balanceCtx.lastBlockNumber)
  balanceCtx.invalidateBalance(myAddress, USDC_ADDRESS)
}

This is the lowest-level hook - prefer useBalanceInvalidation for app code, prefer useTokenBalance for rendering. Reach for useBalanceContext only when building a custom block-aware component.

See also

• TxKitProvider - root provider, useTxKit
• ConnectWallet - useWalletState
• TokenBalance - useTokenBalance, useTokenBalances, useTokenPrice
• TransactionButton - useTransactionFlow