React UI components

Installation via npm

npm install @okxconnect/tonui-react

Add OKXTonConnectUIProvider

Add OKXTonConnectUIProvider to the root directory of your application. You can specify UI options using props. All OKXConnectUI hooks calls and <OKXTonConnectButton /> components should be placed inside <OKXTonConnectUIProvider>.

import { OKXTonConnectUIProvider } from '@okxconnect/tonui-react';

export function App() {
    return (
        <OKXTonConnectUIProvider
            uiPreferences = {{theme: THEME.DARK}}
            dappMetaData = {{
                name: "application name",
                icon: "application url"
            }}
            restoreConnection = {true}
            language = {'zh_CN'}
            actionsConfiguration = {{returnStrategy:"tg://resolve",tmaReturnUrl:'back'}}
        >
            { /* Your app */}
        </OKXTonConnectUIProvider>
    );
}

Add OKXTonConnectButton

The TonConnect button is a generic UI component used to initialise the connection. After the wallet is connected, it converts to the wallet menu. It is recommended to place it in the top right corner of the application.

export const Header = () => {
    return (
        <header>
            <span>My App with React UI</span>
            <OKXTonConnectButton />
        </header>
    );
};

Connecting to a wallet

Connecting to a wallet goes to get the wallet address, which serves as the identifier and the necessary parameters used to sign the transaction. The ‘Connect Button’ (added to buttonRootId) automatically handles the click and invokes the connection. If no buttonRootId is added, this method needs to be called.

await okxTonConnectUI.openModal();

Example

const [okxTonConnectUI, setOptions] = useOKXTonConnectUI();
await okxTonConnectUI.openModal();

Monitoring wallet status changes

Wallet statuses are: successful connection, successful restoration of connection, disconnection, etc. You can use this method to get the status. [Method details same as OKXTonConnect.onStatusChange](https://www.okx.com/web3/build/docs/sdks/app-connect-ton#%E7%9B%91%E5%90%AC%E9%92%B1%E5%8C%85% e7%8a%b6%e6%80%81%e5%8f%98%e5%8c%96)

Example

const [okxTonConnectUI, setOptions] = useOKXTonConnectUI();
okxTonConnectUI.onStatusChange((value: ConnectedWallet | null) => {
    //
});

Get the currently connected wallet address

Use this to get the user's current ton wallet address. Pass the boolean parameter isUserFriendly to select the format of the address. If the wallet is not connected, an empty string will be returned.

import { useTonAddress } from '@okxconnect/tonui-react';

export const Address = () => {
    const userFriendlyAddress = useTonAddress();
    const rawAddress = useTonAddress(false);

    return (
        address && (
            <div>
                <span>User-friendly address: {userFriendlyAddress}</span>
                <span>Raw address: {rawAddress}</span>
            </div>
        )
    );
};

Get currently connected wallet

Use this to get the user's current ton wallet. If the wallet is not connected, null is returned.

import { useOKXTonWallet } from '@okxconnect/tonui-react';

export const Wallet = () => {
    const wallet = useOKXTonWallet();

    return (
        wallet && (
            <div>
                <span>Connected wallet: {wallet.name}</span>
                <span>Device: {wallet.device.appName}</span>
            </div>
        )
    );
};

useTonConnectUI

Use it to access OKXTonConnectUI instances and UI option update features

import { Locales, useOKXTonConnectUI } from '@okxconnect/tonui-react';

export const Settings = () => {
    const [okxTonConnectUI, setOptions] = useOKXTonConnectUI();

    const onLanguageChange = (lang: string) => {
        setOptions({ language: lang as Locales });
    };

    const myTransaction = {
        validUntil: Math.floor(Date.now() / 1000) + 60, // 60 sec
        messages: [
            {
                address: "EQBBJBB3HagsujBqVfqeDUPJ0kXjgTPLWPFFffuNXNiJL0aA",
                amount: "10000000",
                // stateInit: "base64bocblahblahblah==" // just for instance. Replace with your transaction initState or remove
            },
            {
                address: "EQDmnxDMhId6v1Ofg_h5KR5coWlFG6e86Ro3pc7Tq4CA0-Jn",
                amount: "60000000",
                // payload: "base64bocblahblahblah==" // just for instance. Replace with your transaction payload or remove
            }
        ]
    }

    return (
        <div>
            <button onClick={() => okxTonConnectUI.sendTransaction(myTransaction)}>
                Send transaction
            </button>

            <div>
                <label>language</label>
                <select onChange={e => onLanguageChange(e.target.value)}>
                    <option value="en_US">en</option>
                    <option value="ru_RU">ru</option>
                    <option value="zh_CN">zh_CN</option>
                </select>
            </div>
        </div>
    );
};

Whether the connection has been restored

Displays the status of the connection recovery process.

import { useIsConnectionRestored } from '@okxconnect/tonui-react';

export const EntrypointPage = () => {
    const connectionRestored = useIsConnectionRestored();

    if (!connectionRestored) {
        return <Loader>Please wait...</Loader>;
    }

    return <MainPage />;
};

Add connection request parameters (ton_proof)

Use the OKXTonConnectUI.setConnectRequestParameters function to pass the connection request parameters (ton_proof). If you need to set tonProof, set state:‘loading’, before preparing the tonProof parameter. When ready, set state to ‘ready’ and add value;. The loading state can also be removed by setting setConnectRequestParameters(null);

const [okxtonConnectUI] = useOKXTonConnectUI();

okxtonConnectUI.setConnectRequestParameters({ state: 'loading' });

const tonProofPayload: string | null = await fetchTonProofPayloadFromBackend();

if (!tonProofPayload) {
    okxtonConnectUI.setConnectRequestParameters(null);
} else {
    okxtonConnectUI.setConnectRequestParameters({
        state: "ready",
        value: { tonProof: tonProof }
    });
}