Class TonConnectUI

UI-aware TON Connect connector. Wraps a TonConnect instance from @tonconnect/sdk and adds the wallet-selection modal, the "connect-wallet" button, notification toasts, and a uiOptions setter for runtime theming.

In a React app prefer <TonConnectUIProvider> from @tonconnect/ui-react, which manages a singleton TonConnectUI for you.

Example

import { TonConnectUI, THEME } from '@tonconnect/ui';

const tonConnectUI = new TonConnectUI({
    manifestUrl: 'https://example.com/tonconnect-manifest.json',
    buttonRootId: 'ton-connect-button',
    uiPreferences: { theme: THEME.DARK },
});

if (tonConnectUI.connected) {
    await tonConnectUI.sendTransaction(tx);
} else {
    await tonConnectUI.openModal();
}

See

Connect a wallet (docs)

Constructors

constructor

new TonConnectUI(options?: TonConnectUiCreateOptions): TonConnectUI
Parameters
- Optionaloptions: TonConnectUiCreateOptions
Returns TonConnectUI
- Defined in packages/ui/src/ton-connect-ui.ts:298

Properties

`Readonly`connectionRestored

connectionRestored: Promise<boolean> = ...

Promise that resolves after the connection restoring process ends (it fires after onStatusChange, so you can read actual wallet and session information once it resolves). The resolved value true/false indicates whether the session was restored successfully.

`Readonly`connector

connector: ITonConnect

TonConnect instance.

`Readonly`modal

modal: WalletsModal

Manages the modal window state.

Accessors

account

get account(): null | Account
Current connected account or null.

Returns null | Account
- Defined in packages/ui/src/ton-connect-ui.ts:212

connected

get connected(): boolean
Current connection status.

Returns boolean
- Defined in packages/ui/src/ton-connect-ui.ts:205

modalState

get modalState(): WalletsModalState
Returns current modal window state.

Returns WalletsModalState
- Defined in packages/ui/src/ton-connect-ui.ts:477

singleWalletModalState

get singleWalletModalState(): SingleWalletModalState
Experimental
Returns current single wallet modal window state.

Returns SingleWalletModalState
- Defined in packages/ui/src/ton-connect-ui.ts:511

uiOptions

set uiOptions(options: TonConnectUiOptions): void
Set and apply new UI options. Object with partial options should be passed. Passed options will be merged with current options.
Parameters
- options: TonConnectUiOptions
Returns void
- Defined in packages/ui/src/ton-connect-ui.ts:234

wallet

get wallet(): null | Wallet | (Wallet & WalletInfoWithOpenMethod)
Current connected wallet app and its info, or null when not connected.

Returns null | Wallet | (Wallet & WalletInfoWithOpenMethod)
- Defined in packages/ui/src/ton-connect-ui.ts:219

walletsPreferredFeatures

get walletsPreferredFeatures(): undefined | RequiredFeatures
Wallet features the dApp prefers. Non-matching wallets stay selectable but are sorted to the bottom of the picker; unlike TonConnectUI.walletsRequiredFeatures, the match is not enforced at connect time. See RequiredFeatures.

Returns undefined | RequiredFeatures
- Defined in packages/ui/src/ton-connect-ui.ts:163

walletsRequiredFeatures

get walletsRequiredFeatures(): undefined | RequiredFeatures
Wallet features the dApp requires. Wallets that do not advertise them are hidden from the picker and rejected at connect time. Set via the constructor or the uiOptions setter. See RequiredFeatures.

Returns undefined | RequiredFeatures
- Defined in packages/ui/src/ton-connect-ui.ts:151

Methods

closeModal

closeModal(reason?: WalletsModalCloseReason): void
Closes the modal window.
Parameters
- Optionalreason: WalletsModalCloseReason
  optional WalletsModalCloseReason forwarded to state subscribers.
Returns void
- Defined in packages/ui/src/ton-connect-ui.ts:461

closeSingleWalletModal

closeSingleWalletModal(closeReason?: WalletsModalCloseReason): void
Experimental
Close the single wallet modal window.
Parameters
- OptionalcloseReason: WalletsModalCloseReason
Returns void
- Defined in packages/ui/src/ton-connect-ui.ts:493

connectWallet

connectWallet(options?: { traceId?: string }): Promise<ConnectedWallet>
Parameters
- Optionaloptions: { traceId?: string }
Returns Promise<ConnectedWallet>
Connected wallet.

Deprecated
Use tonConnectUI.openModal() instead. Will be removed in the next major version. Opens the modal window and handles a wallet connection.

Throws
TonConnectUIError if connection was aborted.
- Defined in packages/ui/src/ton-connect-ui.ts:521

disconnect

disconnect(options?: { traceId?: string }): Promise<void>
Disconnect wallet and clean localstorage.
Parameters
- Optionaloptions: { traceId?: string }
Returns Promise<void>
- Defined in packages/ui/src/ton-connect-ui.ts:537

getWallets

getWallets(): Promise<WalletInfo[]>
Returns available wallets list.

Returns Promise<WalletInfo[]>
array of WalletInfo, merged from the registry and any injected wallets.
- Defined in packages/ui/src/ton-connect-ui.ts:414

onModalStateChange

onModalStateChange(onChange: (state: WalletsModalState) => void): () => void
Subscribe to the modal window state changes.
Parameters
- onChange: (state: WalletsModalState) => void
  callback invoked with the new WalletsModalState on every change.
Returns () => void
function which has to be called to unsubscribe.
- Defined in packages/ui/src/ton-connect-ui.ts:470

onSingleWalletModalStateChange

onSingleWalletModalStateChange(
onChange: (state: SingleWalletModalState) => void,
): () => void
Experimental
Subscribe to the single wallet modal window state changes, returns a function which has to be called to unsubscribe.
Parameters
- onChange: (state: SingleWalletModalState) => void
Returns () => void
- Defined in packages/ui/src/ton-connect-ui.ts:501

onStatusChange

onStatusChange(
callback: (wallet: null | ConnectedWallet) => void,
errorsHandler?: (err: TonConnectError) => void,
): () => void
Subscribe to connection status change.
Parameters
- callback: (wallet: null | ConnectedWallet) => void
- OptionalerrorsHandler: (err: TonConnectError) => void
Returns () => void
function which has to be called to unsubscribe.
- Defined in packages/ui/src/ton-connect-ui.ts:422

openModal

openModal(options?: { traceId?: string }): Promise<void>
Opens the modal window, returns a promise that resolves after the modal window is opened.
Parameters
- Optionaloptions: { traceId?: string }
Returns Promise<void>
- Defined in packages/ui/src/ton-connect-ui.ts:443

openSingleWalletModal

openSingleWalletModal(wallet: string): Promise<void>
Experimental
Opens the single wallet modal window, returns a promise that resolves after the modal window is opened.
Parameters
- wallet: string
Returns Promise<void>
- Defined in packages/ui/src/ton-connect-ui.ts:485

sendTransaction

sendTransaction(
tx: SendTransactionRequest,
options?: ActionOptions,
): Promise<OptionalTraceable<SendTransactionResponse>>
Opens the modal window and handles the transaction sending.

Pass options.enableEmbeddedRequest: true to allow the request to ride along with the connect URL on mobile, eliminating a round-trip. With that flag, the result is always the embedded shape:
- { hasResponse: true, response } — the transaction was signed, either folded into connect by an embedded-request-capable wallet, or via the normal bridge flow.
- { hasResponse: false, connectResult: { dispatched } } — the wallet connected but did not return a signed transaction. The dApp must decide how to recover:
  - dispatched: false — the request never reached the wallet.
  - dispatched: true — the request was delivered to the wallet inside the connect URL. The wallet may have already signed and submitted it; you just didn't get the response. Do not retry silently. Surface an explicit retry button to the user, and ideally check on-chain state (e.g. the user's transaction history for the destination, queryId and amount) before re-submitting to avoid a duplicate transaction.
Without the flag the method throws if the wallet is not connected and returns the plain SendTransactionResponse otherwise.
Parameters
- tx: SendTransactionRequest
  transaction to send.
- Optionaloptions: ActionOptions
  modal and notifications behavior settings; set enableEmbeddedRequest: true to opt into the connect-and-send flow described above.
Returns Promise<OptionalTraceable<SendTransactionResponse>>
- Defined in packages/ui/src/ton-connect-ui.ts:573
sendTransaction(
tx: SendTransactionRequest,
options?: EmbeddedActionOptions,
): Promise<OptionalTraceable<EmbeddedSendTransactionResponse>>
Opens the modal window and handles the transaction sending.

Pass options.enableEmbeddedRequest: true to allow the request to ride along with the connect URL on mobile, eliminating a round-trip. With that flag, the result is always the embedded shape:
- { hasResponse: true, response } — the transaction was signed, either folded into connect by an embedded-request-capable wallet, or via the normal bridge flow.
- { hasResponse: false, connectResult: { dispatched } } — the wallet connected but did not return a signed transaction. The dApp must decide how to recover:
  - dispatched: false — the request never reached the wallet.
  - dispatched: true — the request was delivered to the wallet inside the connect URL. The wallet may have already signed and submitted it; you just didn't get the response. Do not retry silently. Surface an explicit retry button to the user, and ideally check on-chain state (e.g. the user's transaction history for the destination, queryId and amount) before re-submitting to avoid a duplicate transaction.
Without the flag the method throws if the wallet is not connected and returns the plain SendTransactionResponse otherwise.
Parameters
- tx: SendTransactionRequest
  transaction to send.
- Optionaloptions: EmbeddedActionOptions
  modal and notifications behavior settings; set enableEmbeddedRequest: true to opt into the connect-and-send flow described above.
Returns Promise<OptionalTraceable<EmbeddedSendTransactionResponse>>
- Defined in packages/ui/src/ton-connect-ui.ts:577

setConnectionNetwork

setConnectionNetwork(network?: string): void
Set desired network for the connection. Can only be set before connecting. If wallet connects with a different chain, the SDK will throw an error and abort connection.
Parameters
- Optionalnetwork: string
  desired network id (e.g., '-239', '-3', or custom). Pass undefined to allow any network. See ChainId.
Returns void
- Defined in packages/ui/src/ton-connect-ui.ts:406

setConnectRequestParameters

setConnectRequestParameters(
    connectRequestParameters:
        | undefined
        | null
        | Loadable<ConnectAdditionalRequest>,
): void
Use it to customize ConnectRequest and add tonProof payload. You can call it multiple times to set an updated tonProof payload if the previous one is outdated. If connectRequestParameters.state === 'loading' loader will appear instead of the qr code in the wallets modal. If connectRequestParameters.state was changed to 'ready' or it's value has been changed, QR will be re-rendered.
Parameters
- connectRequestParameters: undefined | null | Loadable<ConnectAdditionalRequest>
Returns void
- Defined in packages/ui/src/ton-connect-ui.ts:392

signData

signData(
data: SignDataPayload,
options?: ActionOptions,
): Promise<OptionalTraceable<SignDataResponse>>
Signs the data and returns the signature.

Pass options.enableEmbeddedRequest: true to allow the request to ride along with the connect URL on mobile, eliminating a round-trip. With that flag, the result is always the embedded shape:
- { hasResponse: true, response } — the data was signed, either folded into connect by an embedded-request-capable wallet, or via the normal bridge flow.
- { hasResponse: false, connectResult: { dispatched } } — the wallet connected but did not return a signature. Recovery is the dApp's responsibility:
  - dispatched: false — the request never reached the wallet.
  - dispatched: true — the request was delivered to the wallet inside the connect URL. The wallet may have already signed it; you just didn't get the response back. Do not retry silently. Surface an explicit retry button to the user, and, where it makes sense, verify that you don't already have the signature you need before re-submitting.
Without the flag the method throws if the wallet is not connected and returns the plain SignDataResponse otherwise.
Parameters
- data: SignDataPayload
  data to sign.
- Optionaloptions: ActionOptions
  modal and notifications behavior settings; set enableEmbeddedRequest: true to opt into the connect-and-sign flow described above.
Returns Promise<OptionalTraceable<SignDataResponse>>
- Defined in packages/ui/src/ton-connect-ui.ts:656
signData(
data: SignDataPayload,
options?: EmbeddedActionOptions,
): Promise<OptionalTraceable<EmbeddedSignDataResponse>>
Signs the data and returns the signature.

Pass options.enableEmbeddedRequest: true to allow the request to ride along with the connect URL on mobile, eliminating a round-trip. With that flag, the result is always the embedded shape:
- { hasResponse: true, response } — the data was signed, either folded into connect by an embedded-request-capable wallet, or via the normal bridge flow.
- { hasResponse: false, connectResult: { dispatched } } — the wallet connected but did not return a signature. Recovery is the dApp's responsibility:
  - dispatched: false — the request never reached the wallet.
  - dispatched: true — the request was delivered to the wallet inside the connect URL. The wallet may have already signed it; you just didn't get the response back. Do not retry silently. Surface an explicit retry button to the user, and, where it makes sense, verify that you don't already have the signature you need before re-submitting.
Without the flag the method throws if the wallet is not connected and returns the plain SignDataResponse otherwise.
Parameters
- data: SignDataPayload
  data to sign.
- Optionaloptions: EmbeddedActionOptions
  modal and notifications behavior settings; set enableEmbeddedRequest: true to opt into the connect-and-sign flow described above.
Returns Promise<OptionalTraceable<EmbeddedSignDataResponse>>
- Defined in packages/ui/src/ton-connect-ui.ts:660

signMessage

signMessage(
message: SendTransactionRequest,
options?: ActionOptions,
): Promise<OptionalTraceable<SignMessageResponse>>
Signs a message built from a transaction request and returns the signed internal message BoC.

Pass options.enableEmbeddedRequest: true to allow the request to ride along with the connect URL on mobile, eliminating a round-trip. With that flag, the result is always the embedded shape:
- { hasResponse: true, response } — the message was signed, either folded into connect by an embedded-request-capable wallet, or via the normal bridge flow.
- { hasResponse: false, connectResult: { dispatched } } — the wallet connected but did not return a signed message. Recovery is the dApp's responsibility:
  - dispatched: false — the request never reached the wallet. Calling signMessage(msg) again (over the bridge) is safe.
  - dispatched: true — the request was delivered to the wallet inside the connect URL. The wallet may have already signed (and, for gasless flows, even submitted) it; you just didn't get the BoC back. Do not retry silently. Surface an explicit retry button to the user, and for transfer-style payloads check on-chain (the destination and amount in recent transaction history) before re-submitting to avoid a double send.
Without the flag the method throws if the wallet is not connected and returns the plain SignMessageResponse otherwise.
Parameters
- message: SendTransactionRequest
  transaction-like request describing the internal message to sign.
- Optionaloptions: ActionOptions
  modal and notifications behavior settings; set enableEmbeddedRequest: true to opt into the connect-and-sign flow described above.
Returns Promise<OptionalTraceable<SignMessageResponse>>
- Defined in packages/ui/src/ton-connect-ui.ts:733
signMessage(
message: SendTransactionRequest,
options?: EmbeddedActionOptions,
): Promise<OptionalTraceable<EmbeddedSignMessageResponse>>
Signs a message built from a transaction request and returns the signed internal message BoC.

Pass options.enableEmbeddedRequest: true to allow the request to ride along with the connect URL on mobile, eliminating a round-trip. With that flag, the result is always the embedded shape:
- { hasResponse: true, response } — the message was signed, either folded into connect by an embedded-request-capable wallet, or via the normal bridge flow.
- { hasResponse: false, connectResult: { dispatched } } — the wallet connected but did not return a signed message. Recovery is the dApp's responsibility:
  - dispatched: false — the request never reached the wallet. Calling signMessage(msg) again (over the bridge) is safe.
  - dispatched: true — the request was delivered to the wallet inside the connect URL. The wallet may have already signed (and, for gasless flows, even submitted) it; you just didn't get the BoC back. Do not retry silently. Surface an explicit retry button to the user, and for transfer-style payloads check on-chain (the destination and amount in recent transaction history) before re-submitting to avoid a double send.
Without the flag the method throws if the wallet is not connected and returns the plain SignMessageResponse otherwise.
Parameters
- message: SendTransactionRequest
  transaction-like request describing the internal message to sign.
- Optionaloptions: EmbeddedActionOptions
  modal and notifications behavior settings; set enableEmbeddedRequest: true to opt into the connect-and-sign flow described above.
Returns Promise<OptionalTraceable<EmbeddedSignMessageResponse>>
- Defined in packages/ui/src/ton-connect-ui.ts:737

`Static`getWallets

getWallets(): Promise<WalletInfo[]>
Fetch the wallets-list registry without instantiating a TonConnectUI. Equivalent to the instance method but usable in code that runs before the connector exists.

Returns Promise<WalletInfo[]>
- Defined in packages/ui/src/ton-connect-ui.ts:122

Class TonConnectUI

Example

See

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

Returns TonConnectUI

Properties

ReadonlyconnectionRestored

Readonlyconnector

Readonlymodal

Accessors

account

Returns null | Account

connected

Returns boolean

modalState

Returns WalletsModalState

singleWalletModalState

Returns SingleWalletModalState

uiOptions

Parameters

Returns void

wallet

Returns null | Wallet | (Wallet & WalletInfoWithOpenMethod)

walletsPreferredFeatures

Returns undefined | RequiredFeatures

walletsRequiredFeatures

Returns undefined | RequiredFeatures

Methods

closeModal

Parameters

Returns void

closeSingleWalletModal

Parameters

Returns void

connectWallet

Parameters

Returns Promise<ConnectedWallet>

Deprecated

Throws

disconnect

Parameters

Returns Promise<void>

getWallets

Returns Promise<WalletInfo[]>

onModalStateChange

Parameters

Returns () => void

onSingleWalletModalStateChange

Parameters

Returns () => void

onStatusChange

Parameters

Returns () => void

openModal

Parameters

Returns Promise<void>

openSingleWalletModal

Parameters

Returns Promise<void>

sendTransaction

Parameters

Returns Promise<OptionalTraceable<SendTransactionResponse>>

Parameters

Returns Promise<OptionalTraceable<EmbeddedSendTransactionResponse>>

setConnectionNetwork

Parameters

Returns void

setConnectRequestParameters

Parameters

Returns void

signData

Parameters

Returns Promise<OptionalTraceable<SignDataResponse>>

`Readonly`connectionRestored

`Readonly`connector

`Readonly`modal

`Static`getWallets