Install AppKit in a React app

Install AppKit’s React packages, create an AppKit instance, and mount the providers that AppKit hooks rely on.

Install packages

npm i @ton/appkit @ton/appkit-react @tanstack/react-query @tonconnect/ui-react @ton/core

Package	Use
@ton/appkit	Core runtime: actions, connectors, types.
@ton/appkit-react	React layer: hooks, components, default stylesheet.
@tanstack/react-query	Cache backing every query and mutation hook.
@tonconnect/ui-react	TON Connect transport. @ton/appkit-react re-exports <TonConnectButton /> from this package.
@ton/core	TON address and cell primitives.

Complete the Preparation step first. The Buffer polyfill it sets up is required for AppKit to run in the browser.

Create the AppKit instance

Create the AppKit instance in a dedicated module. An empty configuration is enough to start — connectors, networks, and DeFi providers are added on the following pages.

// src/appkit.ts
import { AppKit } from "@ton/appkit-react"

export const appKit = new AppKit({});

Wrap the application

AppKit hooks read from two React contexts: the AppKit instance and a TanStack Query cache. Mount both at the application root.

1. AppKit provider

   AppKitProvider exposes the AppKit instance to descendant hooks and components, removing the need to thread it through props.

   import { AppKitProvider } from '@ton/appkit-react'
   import { appKit } from './appkit'
   
   function App() {
     return (
       <AppKitProvider appKit={appKit}>
         {/** ... */}
       </AppKitProvider>
     )
   }
   
2. TanStack Query provider

   QueryClientProvider owns the cache used by every query and mutation hook. Create one QueryClient per application and mount it inside AppKitProvider.

   import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
   import { AppKitProvider } from '@ton/appkit-react'
   import { appKit } from './appkit'
   
   const queryClient = new QueryClient()
   
   function App() {
     return (
       <AppKitProvider appKit={appKit}>
         <QueryClientProvider client={queryClient}>
           {/** ... */}
         </QueryClientProvider>
       </AppKitProvider>
     )
   }
   

Import styles

To use the bundled components from @ton/appkit-react (<TonConnectButton />, <SendTonButton />, <NftItem />), import the default stylesheet once at the application root. Without it, the components render unstyled.

import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { AppKitProvider } from '@ton/appkit-react'
import { appKit } from './appkit'

import '@ton/appkit-react/styles.css'

const queryClient = new QueryClient()

function App() {
  return (
    <AppKitProvider appKit={appKit}>
      <QueryClientProvider client={queryClient}>
        {/** ... */}
      </QueryClientProvider>
    </AppKitProvider>
  )
}

Next steps

Connectors

Register wallet connectors on the AppKit instance and render the connect button.

Basic getter hooks

Read wallet, balance, and transaction state from React.