TON Connect for React
The recommended SDK for React Apps is a UI React SDK. It is a React component that provides a high-level way to interact with TON Connect.
Implementation
Installation
To start integrating TON Connect into your DApp, you need to install the @tonconnect/ui-react
package. You can use npm or yarn for this purpose:
- npm
- Yarn
- pnpm
npm i @tonconnect/ui-react
yarn add @tonconnect/ui-react
pnpm add @tonconnect/ui-react
TON Connect Initiation
After installing the package, you should create a manifest.json
file for your application. More information on how to create a manifest.json file can be found here.
After creating the manifest file, import TonConnectUIProvider to the root of your Mini App and pass the manifest URL:
import { TonConnectUIProvider } from '@tonconnect/ui-react';
export function App() {
return (
<TonConnectUIProvider manifestUrl="https://<YOUR_APP_URL>/tonconnect-manifest.json">
{ /* Your app */ }
</TonConnectUIProvider>
);
}
Connect to the Wallet
Add the TonConnectButton
. The TonConnect Button is a universal UI component for initializing a connection. After the wallet is connected, it transforms into a wallet menu. It is recommended to place it in the top right corner of your app.
export const Header = () => {
return (
<header>
<span>My App with React UI</span>
<TonConnectButton />
</header>
);
};
You can add className and style props to the button as well. Note that you cannot pass child to the TonConnectButton:
<TonConnectButton className="my-button-class" style={{ float: "right" }}/>
Moreover, you can always initiate the connection manually using the useTonConnectUI
hook and openModal method.
export const Header = () => {
const [tonConnectUI, setOptions] = useTonConnectUI();
return (
<header>
<span>My App with React UI</span>
<button onClick={() => tonConnectUI.openModal()}>
Connect Wallet
</button>
</header>
);
};
Connect with a specific wallet
To open a modal window for a specific wallet, use the openSingleWalletModal()
method. This method takes the wallet's app_name
as a parameter (refer to the wallets-list.json file) and opens the corresponding wallet modal. It returns a promise that resolves once the modal window has successfully opened.
<button onClick={() => tonConnectUI.openSingleWalletModal('tonwallet')}>
Connect Wallet
</button>
Redirects
If you want to redirect the user to a specific page after wallet connection, you can use useTonConnectUI
hook and customize your return strategy.
Telegram Mini Apps
If you want to redirect the user to a Telegram Mini App after wallet connection, you can customize the TonConnectUIProvider
element:
<TonConnectUIProvider
// ... other parameters
actionsConfiguration={{
twaReturnUrl: 'https://t.me/<YOUR_APP_NAME>'
}}
>
</TonConnectUIProvider>
UI customization
To customize UI of the modal you can use the useTonConnectUI
hook and the setOptions
function. See more about useTonConnectUI hook in Hooks section.
Hooks
If you want to use some low-level TON Connect UI SDK features in your React app, you can use hooks from the @tonconnect/ui-react
package.
useTonAddress
Use it to get user's current ton wallet address. Pass the boolean parameter isUserFriendly
(default is true
) to choose the format of the address. If the wallet is not connected, the hook will return an empty string.
import { useTonAddress } from '@tonconnect/ui-react';
export const Address = () => {
const userFriendlyAddress = useTonAddress();
const rawAddress = useTonAddress(false);
return (
userFriendlyAddress && (
<div>
<span>User-friendly address: {userFriendlyAddress}</span>
<span>Raw address: {rawAddress}</span>
</div>
)
);
};
useTonConnectModal
Use this hook to access the functions for opening and closing the modal window. The hook returns an object with the current modal state and methods to open and close the modal.
import { useTonConnectModal } from '@tonconnect/ui-react';
export const ModalControl = () => {
const { state, open, close } = useTonConnectModal();
return (
<div>
<div>Modal state: {state?.status}</div>
<button onClick={open}>Open modal</button>
<button onClick={close}>Close modal</button>
</div>
);
};
useTonWallet
Use this hook to retrieve the user's current TON wallet.
If the wallet is not connected, the hook will return null
. The wallet
object provides common data such as the user's address, provider, TON proof, and other attributes (see the Wallet interface).
Additionally, you can access more specific details about the connected wallet, such as its name, image, and other attributes (refer to the WalletInfo interface).
import { useTonWallet } from '@tonconnect/ui-react';
export const Wallet = () => {
const wallet = useTonWallet();
return (
wallet && (
<div>
<span>Connected wallet address: {wallet.account.address}</span>
<span>Device: {wallet.device.appName}</span>
<span>Connected via: {wallet.provider}</span>
{wallet.connectItems?.tonProof?.proof && <span>Ton proof: {wallet.connectItems.tonProof.proof}</span>}
<div>Connected wallet info:</div>
<div>
{wallet.name} <img src={wallet.imageUrl} />
</div>
</div>
)
);
};