TON Connect for Vue

Recommended SDK for Vue Apps is a UI Vue SDK. It is a Vue 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 @townsquarelabs/ui-vue package. You can use npm or yarn for this purpose:

npm
Yarn
pnpm

npm i @townsquarelabs/ui-vue

yarn add @townsquarelabs/ui-vue

pnpm add @townsquarelabs/ui-vue

TON Connect Initiation

Add TonConnectUIProvider to the root of the app. You can specify UI options using props.

All TonConnect UI hooks calls and <TonConnectButton /> component must be placed inside <TonConnectUIProvider>.

<template>
  <TonConnectUIProvider :options="options">
    <!-- Your app -->
  </TonConnectUIProvider>
</template>

<script>
import { TonConnectUIProvider } from '@townsquarelabs/ui-vue';

export default {
  components: {
    TonConnectUIProvider
  },
  setup(){
    const options = {
      manifestUrl:"https://<YOUR_APP_URL>/tonconnect-manifest.json",
    };
    return {
      options
    }
  }
}
</script>

Connect to the Wallet

TonConnect Button is universal UI component for initializing connection. After wallet is connected it transforms to a wallet menu. It is recommended to place it in the top right corner of your app.

<template>
  <header>
    <span>My App with Vue UI</span>
    <TonConnectButton/>
  </header>
</template>

<script>
import { TonConnectButton } from '@townsquarelabs/ui-vue';

export default {
  components: {
    TonConnectButton
  }
}
</script>

You can add class and :style props to the button as well. Note that you cannot pass child to the TonConnectButton. <TonConnectButton class="my-button-class" :style="{ float: 'right' }"/>

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:

<template>
  <TonConnectUIProvider :options="options">
    <!-- Your app -->
  </TonConnectUIProvider>
</template>

<script>
import { TonConnectUIProvider } from '@townsquarelabs/ui-vue';

export default {
  components: {
    TonConnectUIProvider,
  },
  setup() {
    const options = {
      actionsConfiguration: { twaReturnUrl: 'https://t.me/<YOUR_APP_NAME>' },
    };
    return {
      options,
    };
  },
};
</script>

UI customization

To customize UI of the modal you can use useTonConnectUI hook and setOptions function. See more about useTonConnectUI hook in Hooks section.

Hooks

useTonAddress

Use it to get user's current ton wallet address. Pass boolean parameter isUserFriendly to choose format of the address. If wallet is not connected hook will return empty string.

<template>
  <div v-if="address">
    <span>User-friendly address: {{ userFriendlyAddress }}</span>
    <span>Raw address: {{ rawAddress }}</span>
  </div>
</template>

<script>
import { useTonAddress } from '@townsquarelabs/ui-vue';

export default {
  setup() {
    const userFriendlyAddress = useTonAddress();
    const rawAddress = useTonAddress(false);

    return {
      userFriendlyAddress,
      rawAddress
    }
  }
}
</script>

useTonWallet

Use it to get user's current ton wallet. If wallet is not connected hook will return null.

See all wallet's properties // todo

<template>
  <div v-if="wallet">
    <span>Connected wallet: {{ wallet.name }}</span>
    <span>Device: {{ wallet.device.appName }}</span>
  </div>
</template>

<script>
import { useTonWallet } from '@townsquarelabs/ui-vue';

export default {
  setup() {
    const wallet = useTonWallet();

    return {
      wallet
    }
  }

}
</script>

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.

<template>
  <div>
    <div>Modal state: {{ state?.status }}</div>
    <button @click="open">Open modal</button>
    <button @click="close">Close modal</button>
  </div>
</template>

<script>
import { useTonConnectModal } from '@townsquarelabs/ui-vue';

export default {
  setup() {
    const { state, open, close } = useTonConnectModal();
    return { state, open, close };
  }
};
</script>

useTonConnectUI

Use it to get access to the TonConnectUI instance and UI options updating function.

See more about TonConnectUI instance methods

See more about setOptions function

<template>
  <div>
    <button @click="sendTransaction">Send transaction</button>
    <div>
      <label>language</label>
      <select @change="onLanguageChange($event.target.value)">
        <option value="en">en</option>
        <option value="ru">ru</option>
        <option value="zh">zh</option>
      </select>
    </div>
  </div>
</template>

<script>
import { Locales, useTonConnectUI } from '@townsquarelabs/ui-vue';

export default {
  name: 'Settings',
  setup() {
    const [tonConnectUI, setOptions] = useTonConnectUI();

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

    const myTransaction = {
      validUntil: Math.floor(Date.now() / 1000) + 60, // 60 sec
      messages: [
        {
          address: "EQBBJBB3HagsujBqVfqeDUPJ0kXjgTPLWPFFffuNXNiJL0aA",
          amount: "20000000",
          // 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
        }
      ]
    }

    const sendTransaction = () => {
      tonConnectUI.sendTransaction(myTransaction);
    };

    return { onLanguageChange, sendTransaction };
  }
};
</script>

useIsConnectionRestored

Indicates current status of the connection restoring process. You can use it to detect when connection restoring process if finished.

<template>
  <div>
    <div v-if="!connectionRestored">Please wait...</div>
    <MainPage v-else />
  </div>
</template>

<script>
import { useIsConnectionRestored } from '@townsquarelabs/ui-vue';

export default {
  name: 'EntrypointPage',
  setup() {
    const connectionRestored = useIsConnectionRestored();
    return { connectionRestored };
  }
};
</script>

Usage

Let's take a look at how to use the Vue UI SDK on practice.

Sending transactions

Send TON coins (in nanotons) to a specific address:

<template>
  <div>
    <button @click="sendTransaction">Send transaction</button>
  </div>
</template>

<script>
import { useTonConnectUI } from '@townsquarelabs/ui-vue';

export default {
  name: 'Settings',
  setup() {
    const [tonConnectUI, setOptions] = useTonConnectUI();


    const myTransaction = {
      validUntil: Math.floor(Date.now() / 1000) + 60, // 60 sec
      messages: [
        {
          address: "EQBBJBB3HagsujBqVfqeDUPJ0kXjgTPLWPFFffuNXNiJL0aA",
          amount: "20000000",
          // 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
        }
      ]
    }

    const sendTransaction = () => {
      tonConnectUI.sendTransaction(myTransaction);
    };

    return { sendTransaction };
  }
};
</script>

Understanding Transaction Status by Hash

The principle located in Payment Processing (using tonweb). See more

Add connect request parameters (ton_proof)

tip

Understand how to sign and verify messages: Signing and Verification

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.

import { ref } from 'vue';
import { useTonConnectUI } from '@townsquarelabs/ui-vue';

const tonConnectUI = useTonConnectUI();

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

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

import { ref } from 'vue';
import { useTonConnectUI } from '@townsquarelabs/ui-vue';

const tonConnectUI = useTonConnectUI();

tonConnectUI.setConnectRequestParameters({
    state: 'ready',
    value: {
        tonProof: '<your-proof-payload>'
    }
});

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.

import { ref } from 'vue';
import { useTonConnectUI } from '@townsquarelabs/ui-vue';

const tonConnectUI = useTonConnectUI();

tonConnectUI.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).

import { ref } from 'vue';
import { useTonConnectUI } from '@townsquarelabs/ui-vue';

const tonConnectUI = useTonConnectUI();

// enable ui loader
tonConnectUI.setConnectRequestParameters({ state: 'loading' });

// fetch you tonProofPayload from the backend
const tonProofPayload: string | null = await fetchTonProofPayloadFromBackend();

if (!tonProofPayload) {
    // remove loader, connect request will be without any additional parameters
    tonConnectUI.setConnectRequestParameters(null);
} else {
    // add tonProof to the connect request
    tonConnectUI.setConnectRequestParameters({
        state: "ready",
        value: { tonProof: tonProofPayload }
    });
}

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

import { ref, onMounted } from 'vue';
import { useTonConnectUI } from '@townsquarelabs/ui-vue';

const tonConnectUI = useTonConnectUI();

onMounted(() =>
    tonConnectUI.onStatusChange(wallet => {
        if (wallet.connectItems?.tonProof && 'proof' in wallet.connectItems.tonProof) {
            checkProofInYourBackend(wallet.connectItems.tonProof.proof, wallet.account);
        }
}));

Wallet Disconnection

Call to disconnect the wallet:

import { useTonConnectUI } from '@townsquarelabs/ui-vue';

const [tonConnectUI] = useTonConnectUI();

await tonConnectUI.disconnect();

Troubleshooting

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:

npm install web-animations-js

Then, import the polyfill in your project:

import 'web-animations-js';

Using CDN

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

<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.

Examples

Demo dApp - Example of a DApp with @townsquarelabs/ui-vue.

Implementation​

Installation​

TON Connect Initiation​

Connect to the Wallet​

Redirects​

Telegram Mini Apps​

UI customization​

Hooks​

useTonAddress​

useTonWallet​

useTonConnectModal​

useTonConnectUI​

useIsConnectionRestored​

Usage​

Sending transactions​

Understanding Transaction Status by Hash​

Add connect request parameters (ton_proof)​

Wallet Disconnection​

Troubleshooting​

Animations not working​

Using npm​

Using CDN​

Examples​