TON Connect for JS
This guide will help you integrate TON Connect into your JavaScript app for user authentication and transactions.
If using React for your DApp, look at the TON Connect UI React SDK.
Implementation
Installation
- CDN
- NPM
Add the script to the <head>
element of your website:
<script src="https://unpkg.com/@tonconnect/ui@latest/dist/tonconnect-ui.min.js"></script>
Install the @tonconnect/ui package:
- npm
- Yarn
- pnpm
- Bun
npm i @tonconnect/ui
yarn add @tonconnect/ui
pnpm add @tonconnect/ui
bun add @tonconnect/ui
Set up TON Connect
After installing the package, create a tonconnect-manifest.json
file for your app.
See the manifest creation guide for details.
Add a container element with the id ton-connect
to host the connect button:
<div id="ton-connect"></div>
After this tag, add a script for tonConnectUI
in the <body>
part of the app page:
<script>
const tonConnectUI = new TON_CONNECT_UI.TonConnectUI({
manifestUrl: 'https://<YOUR_APP_URL>/tonconnect-manifest.json',
buttonRootId: 'ton-connect'
});
</script>
Connect to the wallet
The element specified by buttonRootId
renders the connect button and handles clicks automatically.
You can also open the connect modal programmatically; for example, from a custom button’s click handler:
<script>
async function connectToWallet() {
// Open the connect modal programmatically
await tonConnectUI.openModal();
}
// Call the function
connectToWallet().catch(error => {
console.error("Error connecting to wallet:", error);
});
</script>
Redirects
Customizing return strategy
To redirect the user to a specific URL after connection, you can customize your return strategy.
Telegram Mini Apps
To redirect the user to a Telegram Mini App after wallet connection, use the twaReturnUrl
option:
tonConnectUI.uiOptions = {
actionsConfiguration: {
twaReturnUrl: 'https://t.me/YOUR_APP_NAME'
}
};
Read more in SDK documentation
UI customization
TON Connect UI provides an interface that should be familiar and recognizable to the user when using various apps. However, the app developer can modify this interface to keep it consistent with the app's interface.
SDK documentation
Usage
Let's look at an example of using TON Connect UI in an app.
Sending messages
Here's an example of sending a transaction using the TON Connect UI:
import { TonConnectUI } from '@tonconnect/ui';
const tonConnectUI = new TonConnectUI({ //connect application
manifestUrl: 'https://<YOUR_APP_URL>/tonconnect-manifest.json',
buttonRootId: '<YOUR_CONNECT_BUTTON_ANCHOR_ID>'
});
const transaction = {
validUntil: Math.floor(Date.now() / 1000) + 60, // 60 sec
messages: [
{
address: "EQABa48hjKzg09hN_HjxOic7r8T1PleIy1dRd8NvZ3922MP0", // destination address
amount: "20000000" //Toncoin in nanotons
}
]
}
const result = await tonConnectUI.sendTransaction(transaction)
Get more examples on the Sending messages page.
Understanding transaction status by hash
Learn the principle explained in payment processing using the tonweb library.
Signing and verification
Understand how to sign and verify messages using TON Connect:
This feature is particularly useful for verifying ownership of off-chain assets such as Telegram usernames or virtual phone numbers on platforms like Fragment.
Wallet disconnection
Call to disconnect from the wallet:
await tonConnectUI.disconnect();
See also
- UI customization
- [YouTube] TON Connect UI React [RU]
- [YouTube] Connect TON Connect UI to a site [RU]