TON Connect UI

TonConnect UI is a UI kit for TonConnect SDK. Use it to connect your app to TON wallets via TonConnect protocol.

If you use React for your dapp, take a look at TonConnect UI React kit.

If you want to use TonConnect on the server side, you should use the TonConnect SDK.

You can find more details and the protocol specification in the docs.

Latest API documentation

Getting started

Installation with cdn

Add the script to your HTML file:

1<script src="https://unpkg.com/@tonconnect/ui@latest/dist/tonconnect-ui.min.js"></script>

ℹ️ If you don't want auto-update the library, pass concrete version instead of latest, e.g.

1<script src="https://unpkg.com/@tonconnect/ui@0.0.9/dist/tonconnect-ui.min.js"></script>

You can find TonConnectUI in global variable TON_CONNECT_UI, e.g.

1<script>
2    const tonConnectUI = new TON_CONNECT_UI.TonConnectUI({
3        manifestUrl: 'https://<YOUR_APP_URL>/tonconnect-manifest.json',
4        buttonRootId: '<YOUR_CONNECT_BUTTON_ANCHOR_ID>'
5    });
6</script>

Installation with npm

npm i @tonconnect/ui

Usage

Create TonConnectUI instance

1import TonConnectUI from '@tonconnect/ui'
2
3const tonConnectUI = new TonConnectUI({
4    manifestUrl: 'https://<YOUR_APP_URL>/tonconnect-manifest.json',
5    buttonRootId: '<YOUR_CONNECT_BUTTON_ANCHOR_ID>'
6});

See all available options:

TonConnectUiOptionsWithManifest

TonConnectUiOptionsWithConnector

Change options if needed

1tonConnectUI.uiOptions = {
2    language: 'ru',
3    uiPreferences: {
4        theme: THEME.DARK
5    }
6};

UI element will be rerendered after assignation. You should pass only options that you want to change. Passed options will be merged with current UI options. Note, that you have to pass object to tonConnectUI.uiOptions to keep reactivity.

DON'T do this:

1/* WRONG, WILL NOT WORK */ tonConnectUI.uiOptions.language = 'ru'; 

See all available options

Fetch wallets list

1const walletsList = await tonConnectUI.getWallets();
2
3/* walletsList is 
4{
5    name: string;
6    imageUrl: string;
7    tondns?: string;
8    aboutUrl: string;
9    universalLink?: string;
10    deepLink?: string;
11    bridgeUrl?: string;
12    jsBridgeKey?: string;
13    injected?: boolean; // true if this wallet is injected to the webpage
14    embedded?: boolean; // true if the dapp is opened inside this wallet's browser
15}[] 
16 */

or

1const walletsList = await TonConnectUI.getWallets();

Open connect modal

"TonConnect UI connect button" (which is added at buttonRootId) automatically handles clicks and calls connect. But you are still able to open "connect modal" programmatically, e.g. after click on your custom connect button.

1await tonConnectUI.openModal();

This method opens the modal window and returns a promise that resolves after the modal window is opened.

If there is an error while modal opening, TonConnectUIError or TonConnectError will be thrown depends on situation.

Close connect modal

1tonConnectUI.closeModal();

This method closes the modal window.

Get current modal state

This getter returns the current state of the modal window. The state will be an object with status and closeReason properties. The status can be either 'opened' or 'closed'. If the modal is closed, you can check the closeReason to find out the reason of closing.

1const currentModalState = tonConnectUI.modalState;

Subscribe to the modal window state changes

To subscribe to the changes of the modal window state, you can use the onModalStateChange method. It returns a function which has to be called to unsubscribe.

1const unsubscribeModal = tonConnectUI.onModalStateChange(
2    (state: WalletsModalState) => {
3        // update state/reactive variables to show updates in the ui
4        // state.status will be 'opened' or 'closed'
5        // if state.status is 'closed', you can check state.closeReason to find out the reason
6    }
7);

Call unsubscribeModal() later to save resources when you don't need to listen for updates anymore.

Wallets Modal Control

The tonConnectUI provides methods for managing the modal window, such as openModal(), closeModal() and other, which are designed for ease of use and cover most use cases.

1const { modal } = tonConnectUI;
2
3// Open and close the modal
4await modal.open();
5modal.close();
6
7// Get the current modal state
8const currentState = modal.state;
9
10// Subscribe and unsubscribe to modal state changes
11const unsubscribe = modal.onStateChange(state => { /* ... */ });
12unsubscribe();

While tonConnectUI internally delegates these calls to the modal, it is recommended to use the tonConnectUI methods for a more straightforward and consistent experience. The modal is exposed in case you need direct access to the modal window's state and behavior, but this should generally be avoided unless necessary.

Open specific wallet

The methods described in this section are marked as experimental and are subject to change in future releases.

To open a modal window for a specific wallet, use the openSingleWalletModal() method. This method accepts the wallet app_name as a parameter (please refer to the wallets-list.json) and opens the corresponding wallet modal. It returns a promise that resolves after the modal window is successfully opened.

1await tonConnectUI.openSingleWalletModal('wallet_identifier');

To close the currently open specific wallet modal, use the closeSingleWalletModal() method:

1tonConnectUI.closeSingleWalletModal();

To subscribe to the state changes of the specific wallet modal, use the onSingleWalletModalStateChange((state) => {}) method. It accepts a callback function that will be called with the current modal state.

1const unsubscribe = tonConnectUI.onSingleWalletModalStateChange((state) => {
2    console.log('Modal state changed:', state);
3});
4
5// Call `unsubscribe` when you want to stop listening to the state changes
6unsubscribe();

To get the current state of the specific wallet modal window, use the singleWalletModalState property:

1const currentState = tonConnectUI.singleWalletModalState;
2console.log('Current modal state:', currentState);

Get current connected Wallet and WalletInfo

You can use special getters to read current connection state. Note that this getter only represents current value, so they are not reactive. To react and handle wallet changes use onStatusChange method.

1const currentWallet = tonConnectUI.wallet;
2const currentWalletInfo = tonConnectUI.walletInfo;
3const currentAccount = tonConnectUI.account;
4const currentIsConnectedStatus = tonConnectUI.connected;

Subscribe to the connection status changes

To subscribe to the changes of the connection status, you can use the onStatusChange method. It returns a function which has to be called to unsubscribe.

1const unsubscribe = tonConnectUI.onStatusChange(
2    walletAndwalletInfo => {
3        // update state/reactive variables to show updates in the ui
4    } 
5);

Call unsubscribe() later to save resources when you don't need to listen for updates anymore.

Disconnect wallet

Call to disconnect the wallet.

1await tonConnectUI.disconnect();

Send transaction

Wallet must be connected when you call sendTransaction. Otherwise, an error will be thrown.

1const transaction = {
2    validUntil: Math.floor(Date.now() / 1000) + 60, // 60 sec
3    messages: [
4        {
5            address: "EQBBJBB3HagsujBqVfqeDUPJ0kXjgTPLWPFFffuNXNiJL0aA",
6            amount: "20000000",
7         // stateInit: "base64bocblahblahblah==" // just for instance. Replace with your transaction initState or remove
8        },
9        {
10            address: "EQDmnxDMhId6v1Ofg_h5KR5coWlFG6e86Ro3pc7Tq4CA0-Jn",
11            amount: "60000000",
12         // payload: "base64bocblahblahblah==" // just for instance. Replace with your transaction payload or remove
13        }
14    ]
15}
16
17try {
18    const result = await tonConnectUI.sendTransaction(transaction);
19
20    // you can use signed boc to find the transaction 
21    const someTxData = await myAppExplorerService.getTransaction(result.boc);
22    alert('Transaction was sent successfully', someTxData);
23} catch (e) {
24    console.error(e);
25}

sendTransaction will automatically render informational modals and notifications. You can change its behaviour:

1const result = await tonConnectUI.sendTransaction(defaultTx, {
2    modals: ['before', 'success', 'error'],
3    notifications: ['before', 'success', 'error']
4});

Default configuration is:

1const defaultBehaviour = {
2    modals: ['before'],
3    notifications: ['before', 'success', 'error']
4}

You can also modify this behaviour for all actions calls using uiOptions setter:

1tonConnectUI.uiOptions = {
2        actionsConfiguration: {
3            modals: ['before', 'success', 'error'],
4            notifications: ['before', 'success', 'error']
5        }
6    };

Universal links redirecting issues (IOS)

Some operating systems, and especially iOS, have restrictions related to universal link usage. For instance, if you try to open a universal link on an iOS device via window.open, you can face the following problem: the mobile browser won't redirect the user to the wallet app and will open the fallback tab instead. That's because universal links can only be opened synchronously after a user's action in the browser (button click/...). This means that you either can't perform any asynchronous requests after the user clicks an action button in your dapp, either you can't redirect the user to the connected wallet on some devices.

So, by default, if the user's operating system is iOS, they won't be automatically redirected to the wallet after the dapp calls tonConnectUI.sendTransaction. You can change this behavior using the skipRedirectToWallet option:

1const result = await tonConnectUI.sendTransaction(defaultTx, {
2    modals: ['before', 'success', 'error'],
3    notifications: ['before', 'success', 'error'],
4    skipRedirectToWallet: 'ios' //'ios' (default), or 'never', or 'always'
5});

1tonConnectUI.uiOptions = {
2        actionsConfiguration: {
3            skipRedirectToWallet: 'ios'
4        }
5    };

1// use skipRedirectToWallet: 'never' for better UX
2const onClick = async ()  => {
3    const txBody = packTxBodySynchrone();
4    tonConnectUI.sendTransaction(txBody, { skipRedirectToWallet: 'never' });
5
6    const myApiResponse = await notifyBackend();
7    //...
8}

1// DON'T use skipRedirectToWallet: 'never', you should use skipRedirectToWallet: 'ios' 
2const onClick = async ()  => {
3    const myApiResponse = await notifyBackend();
4    
5    const txBody = packTxBodySynchrone();
6    tonConnectUI.sendTransaction(txBody, { skipRedirectToWallet: 'ios' });
7    //...
8}

Add the return strategy

Return strategy (optional) specifies return strategy for the deeplink when user signs/declines the request.

'back' (default) means return to the app which initialized deeplink jump (e.g. browser, native app, ...), 'none' means no jumps after user action; a URL: wallet will open this URL after completing the user's action. Note, that you shouldn't pass your app's URL if it is a webpage. This option should be used for native apps to work around possible OS-specific issues with 'back' option.

You can set it globally with uiOptions setter, and it will be applied for connect request and all subsequent actions (send transaction/...).

1tonConnectUI.uiOptions = {
2        actionsConfiguration: {
3            returnStrategy: 'none'
4        }
5    };

Or you can set it directly when you send a transaction (will be applied only for this transaction request)

1const result = await tonConnectUI.sendTransaction(defaultTx, {
2    returnStrategy: '<protocol>://<your_return_url>' // Note, that you shouldn't pass your app's URL if it is a webpage.
3     // This option should be used for native apps to work around possible OS-specific issues with 'back' option.
4});

Use inside TMA (Telegram Mini Apps)

TonConnect UI will work in TMA in the same way as in a regular website! Basically, no changes are required from the dApp's developers. The only thing you have to set is a dynamic return strategy.

Currently, it is impossible for TMA-wallets to redirect back to previous opened TMA-dApp like native wallet-apps do. It means, that you need to specify the return strategy as a link to your TMA that will be only applied if the dApp is opened in TMA mode.

1tonConnectUI.uiOptions = {
2    twaReturnUrl: 'https://t.me/durov'
3};

In other words, TonConnect UI will automatically handle the return strategy based on the environment. The following pseudo-code demonstrates the internal logic of TonConnect UI:

Please note that you don't need to add this code to your dApp. It's just an example of how TonConnect UI processes the return strategy internally.

1let finalReturnStrategy;
2
3// Determine if the provided link opens Telegram (using protocols tg:// or domain t.me).
4if (isLinkToTelegram('https://example.com')) {
5    // In the Telegram Mini Apps environment,
6    if (isInTWA()) {
7        // preference is given to 'twaReturnUrl',
8        finalReturnStrategy = actionsConfiguration.twaReturnUrl;
9
10        // but if it's not set, fallback to 'returnStrategy'.
11        if (!finalReturnStrategy) {
12            finalReturnStrategy = actionsConfiguration.returnStrategy;
13        }
14    }
15    // If not in a TMA environment,
16    else {
17        // the return strategy is set to 'none'.
18        finalReturnStrategy = 'none';
19    }
20}
21// When the link does not open Telegram,
22else {
23    // use the predefined 'returnStrategy'.
24    finalReturnStrategy = actionsConfiguration.returnStrategy;
25}
26
27// Now, 'finalReturnStrategy' contains the correct strategy based on the link's destination and the dApp's environment.

Detect end of the connection restoring process

Before restoring previous connected wallet TonConnect has to set up SSE connection with bridge, so you have to wait a little while connection restoring. If you need to update your UI depending on if connection is restoring, you can use tonConnectUI.connectionRestored promise.

Promise that resolves after end of th connection restoring process (promise will fire after onStatusChange, so you can get actual information about wallet and session after when promise resolved). Resolved value true/false indicates if the session was restored successfully.

1tonConnectUI.connectionRestored.then(restored => {
2    if (restored) {
3        console.log(
4            'Connection restored. Wallet:',
5            JSON.stringify({
6                ...tonConnectUI.wallet,
7                ...tonConnectUI.walletInfo
8            })
9        );
10    } else {
11        console.log('Connection was not restored.');
12    }
13});

UI customisation

TonConnect UI provides an interface that should be familiar and recognizable to the user when using various apps. However, the app developer can make changes to this interface to keep it consistent with the app interface.

Customise UI using tonconnectUI.uiOptions

All such updates are reactive -- change tonconnectUI.uiOptions and changes will be applied immediately.

See all available options

Change border radius

There are three border-radius modes: 'm', 's' and 'none'. Default is 'm'. You can change it via tonconnectUI.uiOptions, or set on tonConnectUI creating:

1/* Pass to the constructor */
2const tonConnectUI = new TonConnectUI({
3    manifestUrl: 'https://<YOUR_APP_URL>/tonconnect-manifest.json',
4    uiPreferences: {
5        borderRadius: 's'
6    }
7});
8
9
10/* Or update dynamically */
11tonConnectUI.uiOptions = {
12        uiPreferences: {
13            borderRadius: 's'
14        }
15    };

Note, that uiOptions is a setter which will merge new options with previous ones. So you doesn't need to merge it explicitly. Just pass changed options.

1/* DON'T DO THIS. SEE DESCRIPTION ABOVE */
2tonConnectUI.uiOptions = {
3        ...previousUIOptions,
4        uiPreferences: {
5            borderRadius: 's'
6        }
7    };
8
9/* Just pass changed property */
10tonConnectUI.uiOptions = {
11    uiPreferences: {
12        borderRadius: 's'
13    }
14};

Change theme

You can set fixed theme: 'THEME.LIGHT' or 'THEME.DARK', or use system theme. Default theme is system.

1import { THEME } from '@tonconnect/ui';
2
3tonConnectUI.uiOptions = {
4        uiPreferences: {
5            theme: THEME.DARK
6        }
7    };

You also can set 'SYSTEM' theme:

1tonConnectUI.uiOptions = {
2        uiPreferences: {
3            theme: 'SYSTEM'
4        }
5    };

You can set theme in the constructor if needed:

1import { THEME } from '@tonconnect/ui';
2
3const tonConnectUI = new TonConnectUI({
4    manifestUrl: 'https://<YOUR_APP_URL>/tonconnect-manifest.json',
5    uiPreferences: {
6        theme: THEME.DARK
7    }
8});

Change colors scheme

You can redefine all colors scheme for each theme or change some colors. Just pass colors that you want to change.

1tonConnectUI.uiOptions = {
2        uiPreferences: {
3            colorsSet: {
4                [THEME.DARK]: {
5                    connectButton: {
6                        background: '#29CC6A'
7                    }
8                }
9            }
10        }
11    };

You can change colors for both themes at the same time:

1tonConnectUI.uiOptions = {
2        uiPreferences: {
3            colorsSet: {
4                [THEME.DARK]: {
5                    connectButton: {
6                        background: '#29CC6A'
7                    }
8                },
9                [THEME.LIGHT]: {
10                    text: {
11                        primary: '#FF0000'
12                    }
13                }
14            }
15        }
16    };
17

You can set colors scheme in the constructor if needed:

1import { THEME } from '@tonconnect/ui';
2
3const tonConnectUI = new TonConnectUI({
4    manifestUrl: 'https://<YOUR_APP_URL>/tonconnect-manifest.json',
5    uiPreferences: {
6        colorsSet: {
7            [THEME.DARK]: {
8                connectButton: {
9                    background: '#29CC6A'
10                }
11            }
12        }
13    }
14});

See all available options

Combine options

It is possible to change all required options at the same time:

1tonConnectUI.uiOptions = {
2        uiPreferences: {
3            theme: THEME.DARK,
4            borderRadius: 's',
5            colorsSet: {
6                [THEME.DARK]: {
7                    connectButton: {
8                        background: '#29CC6A'
9                    }
10                },
11                [THEME.LIGHT]: {
12                    text: {
13                        primary: '#FF0000'
14                    }
15                }
16            }
17        }
18    };

Direct css customisation

It is not recommended to customise TonConnect UI elements via css as it may confuse the user when looking for known and familiar UI elements such as connect button/modals. However, it is possible if needed. You can add css styles to the specified selectors of the UI element. See list of selectors in the table below:

UI components:

Basic UI elements:

Customize the list of displayed wallets

You can customize the list of displayed wallets: change order, exclude wallets or add custom wallets.

Extend wallets list

Pass custom wallets array to extend the wallets list. Passed wallets will be added to the end of the original wallets list.

You can define custom wallet with jsBridgeKey (wallet = browser extension or there is a wallet dapp browser) or with bridgeUrl and universalLink pair (for http-connection compatible wallets), or pass all of these properties.

1import { UIWallet } from '@tonconnect/ui';
2
3const customWallet: UIWallet = {

4    name: '<CUSTOM_WALLET_NAME>',

5    imageUrl: '<CUSTOM_WALLET_IMAGE_URL>',

6    aboutUrl: '<CUSTOM_WALLET_ABOUT_URL>',

7    jsBridgeKey: '<CUSTOM_WALLET_JS_BRIDGE_KEY>',

8    bridgeUrl: '<CUSTOM_WALLET_HTTP_BRIDGE_URL>',

9    universalLink: '<CUSTOM_WALLET_UNIVERSAL_LINK>'
10};
11
12tonConnectUI.uiOptions = {

13    walletsListConfiguration: {

14        includeWallets: [customWallet]
15    }
16}

Add connect request parameters (ton_proof)

Use tonConnectUI.setConnectRequestParameters function to pass your connect request parameters.

This function takes one parameter:

Set state to 'loading' while you are waiting for the response from your backend. If user opens connect wallet modal at this moment, he will see a loader.

1tonConnectUI.setConnectRequestParameters({
2    state: 'loading'
3});

or

Set state to 'ready' and define tonProof value. Passed parameter will be applied to the connect request (QR and universal link).

1tonConnectUI.setConnectRequestParameters({
2    state: 'ready',
3    value: {
4        tonProof: '<your-proof-payload>'
5    }
6});

or

Remove loader if it was enabled via state: 'loading' (e.g. you received an error instead of a response from your backend). Connect request will be created without any additional parameters.

1tonConnectUI.setConnectRequestParameters(null);

You can call tonConnectUI.setConnectRequestParameters multiple times if your tonProof payload has bounded lifetime (e.g. you can refresh connect request parameters every 10 minutes).

1// enable ui loader
2tonConnectUI.setConnectRequestParameters({ state: 'loading' });
3
4// fetch you tonProofPayload from the backend
5const tonProofPayload: string | null = await fetchTonProofPayloadFromBackend();
6
7if (!tonProofPayload) {
8    // remove loader, connect request will be without any additional parameters
9    tonConnectUI.setConnectRequestParameters(null);
10} else {
11    // add tonProof to the connect request
12    tonConnectUI.setConnectRequestParameters({
13        state: "ready",
14        value: { tonProof: tonProofPayload }
15    });
16}
17

You can find ton_proof result in the wallet object when wallet will be connected:

1tonConnectUI.onStatusChange(wallet => {
2        if (wallet && wallet.connectItems?.tonProof && 'proof' in wallet.connectItems.tonProof) {
3            checkProofInYourBackend(wallet.connectItems.tonProof.proof);
4        }
5    });

Troubleshooting

Android Back Handler

If you encounter any issues with the Android back handler, such as modals not closing properly when the back button is pressed, or conflicts with history.pushState() if you are manually handling browser history in your application, you can disable the back handler by setting enableAndroidBackHandler to false:

1const tonConnectUI = new TonConnectUI({
2    // ...
3    enableAndroidBackHandler: false
4});

This will disable the custom back button behavior on Android, and you can then handle the back button press manually in your application.

While we do not foresee any problems arising with the Android back handler, but if you find yourself needing to disable it due to an issue, please describe the problem in on GitHub Issues, so we can assist you further.

Animations not working

If you are experiencing issues with animations not working in your environment, it might be due to a lack of support for the Web Animations API. To resolve this issue, you can use the web-animations-js polyfill.

Using npm

To install the polyfill, run the following command:

1npm install web-animations-js

Then, import the polyfill in your project:

1import 'web-animations-js';

Using CDN

Alternatively, you can include the polyfill via CDN by adding the following script tag to your HTML:

1<script src="https://www.unpkg.com/web-animations-js@latest/web-animations.min.js"></script>

Both methods will provide a fallback implementation of the Web Animations API and should resolve the animation issues you are facing.

Warning about 'encoding' module in Next.js

If you are using Next.js and see a warning similar to the following:

 ⚠ ./node_modules/node-fetch/lib/index.js
Module not found: Can't resolve 'encoding' in '.../node_modules/node-fetch/lib'

Import trace for requested module:
./node_modules/node-fetch/lib/index.js
./node_modules/@tonconnect/isomorphic-fetch/index.mjs
./node_modules/@tonconnect/sdk/lib/esm/index.mjs
./node_modules/@tonconnect/ui/lib/esm/index.mjs

Please note that this is just a warning and should not affect the functionality of your application. If you wish to suppress the warning, you have two options:

1. (Recommended) Wait for us to remove the dependency on @tonconnect/isomorphic-fetch in future releases. This dependency will be removed when we drop support for Node.js versions below 18.

2. (Optional) Install the encoding package, to resolve the warning:

1npm install encoding