@tonconnect/ui reference

@tonconnect/ui is the framework-agnostic UI kit on top of @tonconnect/sdk. It ships a styled connect button, a wallets modal, and notification flows that match the TON Connect protocol so dApps without a framework can integrate without designing their own modals.

If you use React, see @tonconnect/ui-react. For protocol semantics, see the TON Connect spec.

Installation

Install from npm:

npm i @tonconnect/ui

Or include the bundle via CDN. The package is exposed on window.TON_CONNECT_UI:

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

For a pinned version, replace @latest with the desired version.

Generated from @tonconnect/ui v3.0.0-beta.2.

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.

Constructor

new TonConnectUI(options?: TonConnectUiCreateOptions)

Instance properties

setConnectRequestParameters()

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', a loader appears 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.

setConnectRequestParameters(
    connectRequestParameters: Loadable<ConnectAdditionalRequest> | undefined | null
): void;

setConnectionNetwork()

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.

setConnectionNetwork(network?: ChainId): void;

getWallets()

Returns available wallets list.

getWallets(): Promise<WalletInfo[]>;

Returns Promise<WalletInfo[]>. Array of WalletInfo, merged from the registry and any injected wallets.

onStatusChange()

Subscribe to connection status change.

onStatusChange(
    callback: (wallet: ConnectedWallet | null) => void,
    errorsHandler?: (err: TonConnectError) => void
): () => void;

Returns () => void. Function which has to be called to unsubscribe.

openModal()

Opens the modal window, returns a promise that resolves after the modal window is opened.

openModal(options?: { traceId?: string }): Promise<void>;

Returns Promise<void>.

closeModal()

Closes the modal window.

closeModal(reason?: WalletsModalCloseReason): void;

onModalStateChange()

Subscribe to the modal window state changes.

onModalStateChange(onChange: (state: WalletsModalState) => void): () => void;

Returns () => void. Function which has to be called to unsubscribe.

openSingleWalletModal()

Experimental — this API may change or be removed in a future release.

Opens the single wallet modal window, returns a promise that resolves after the modal window is opened.

openSingleWalletModal(wallet: string): Promise<void>;

Returns Promise<void>.

closeSingleWalletModal()

Experimental — this API may change or be removed in a future release.

Close the single wallet modal window.

closeSingleWalletModal(closeReason?: WalletsModalCloseReason): void;

onSingleWalletModalStateChange()

Experimental — this API may change or be removed in a future release.

Subscribe to the single wallet modal window state changes, returns a function which has to be called to unsubscribe.

onSingleWalletModalStateChange(onChange: (state: SingleWalletModalState) => void): () => void;

Returns () => void.

connectWallet()

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

connectWallet(options?: { traceId?: string }): Promise<ConnectedWallet>;

Returns Promise<ConnectedWallet>. Connected wallet.

Throws: TonConnectUIError — if connection was aborted.

disconnect()

Disconnect the wallet and clear localStorage.

disconnect(options?: { traceId?: string }): Promise<void>;

Returns Promise<void>.

sendTransaction()

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.

sendTransaction(
    tx: SendTransactionRequest,
    options?: ActionOptions
): Promise<OptionalTraceable<SendTransactionResponse>>;

Returns Promise<OptionalTraceable<SendTransactionResponse>>.

signData()

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.

signData(
    data: SignDataPayload,
    options?: ActionOptions
): Promise<OptionalTraceable<SignDataResponse>>;

Returns Promise<OptionalTraceable<SignDataResponse>>.

signMessage()

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.

signMessage(
    message: SignMessageRequest,
    options?: ActionOptions
): Promise<OptionalTraceable<SignMessageResponse>>;

Returns Promise<OptionalTraceable<SignMessageResponse>>.

Static methods

Types

ActionConfiguration

Modal / notification behavior for action calls (sendTransaction, signData, signMessage) and the return strategy applied to outgoing deep links.

Pass on TonConnectUiOptions.actionsConfiguration (applies to every action) or on the per-call options of a single action.

interface ActionConfiguration {
    modals?: 'all' | ('before' | 'success' | 'error')[];
    notifications?: 'all' | ('before' | 'success' | 'error')[];
    returnStrategy?: ReturnStrategy;
    twaReturnUrl?: `${string}://${string}`;
    skipRedirectToWallet?: 'ios' | 'always' | 'never';
}

TonConnectUiOptionsWithManifest

Construct a fresh TonConnect connector internally from manifestUrl. The most common form for browser dApps.

interface TonConnectUiOptionsWithManifest {
    manifestUrl?: string;
    restoreConnection?: boolean;
    widgetRootId?: string;
    eventDispatcher?: EventDispatcher<RequestVersionEvent | ResponseVersionEvent | ConnectionStartedEvent | ConnectionCompletedEvent | ConnectionErrorEvent | ConnectionRestoringStartedEvent | ConnectionRestoringCompletedEvent | ConnectionRestoringErrorEvent | DisconnectionEvent | TransactionSentForSignatureEvent | TransactionSignedEvent | TransactionSigningFailedEvent | DataSentForSignatureEvent | DataSignedEvent | DataSigningFailedEvent | WalletModalOpenedEvent | SelectedWalletEvent>;
    uiPreferences?: UIPreferences;
    buttonRootId?: string | null;
    language?: Locales;
    walletsListConfiguration?: WalletsListConfiguration;
    walletsRequiredFeatures?: RequiredFeatures;
    walletsPreferredFeatures?: RequiredFeatures;
    actionsConfiguration?: ActionConfiguration;
    enableAndroidBackHandler?: boolean;
    analytics?: AnalyticsSettings;
}

TonConnectUiOptionsWithConnector

Reuse an externally-built ITonConnect. Useful when the dApp drives @tonconnect/sdk directly and only wants the UI layer on top, or when server-side rendering supplies the connector through a custom factory.

interface TonConnectUiOptionsWithConnector {
    connector?: ITonConnect;
    restoreConnection?: boolean;
    widgetRootId?: string;
    eventDispatcher?: EventDispatcher<RequestVersionEvent | ResponseVersionEvent | ConnectionStartedEvent | ConnectionCompletedEvent | ConnectionErrorEvent | ConnectionRestoringStartedEvent | ConnectionRestoringCompletedEvent | ConnectionRestoringErrorEvent | DisconnectionEvent | TransactionSentForSignatureEvent | TransactionSignedEvent | TransactionSigningFailedEvent | DataSentForSignatureEvent | DataSignedEvent | DataSigningFailedEvent | WalletModalOpenedEvent | SelectedWalletEvent>;
    uiPreferences?: UIPreferences;
    buttonRootId?: string | null;
    language?: Locales;
    walletsListConfiguration?: WalletsListConfiguration;
    walletsRequiredFeatures?: RequiredFeatures;
    walletsPreferredFeatures?: RequiredFeatures;
    actionsConfiguration?: ActionConfiguration;
    enableAndroidBackHandler?: boolean;
    analytics?: AnalyticsSettings;
}

TonConnectUiCreateOptionsBase

Common UI-only fields applied on top of either constructor shape.

interface TonConnectUiCreateOptionsBase {
    restoreConnection?: boolean;
    widgetRootId?: string;
    eventDispatcher?: EventDispatcher<RequestVersionEvent | ResponseVersionEvent | ConnectionStartedEvent | ConnectionCompletedEvent | ConnectionErrorEvent | ConnectionRestoringStartedEvent | ConnectionRestoringCompletedEvent | ConnectionRestoringErrorEvent | DisconnectionEvent | TransactionSentForSignatureEvent | TransactionSignedEvent | TransactionSigningFailedEvent | DataSentForSignatureEvent | DataSignedEvent | DataSigningFailedEvent | WalletModalOpenedEvent | SelectedWalletEvent>;
    uiPreferences?: UIPreferences;
    buttonRootId?: string | null;
    language?: Locales;
    walletsListConfiguration?: WalletsListConfiguration;
    walletsRequiredFeatures?: RequiredFeatures;
    walletsPreferredFeatures?: RequiredFeatures;
    actionsConfiguration?: ActionConfiguration;
    enableAndroidBackHandler?: boolean;
    analytics?: AnalyticsSettings;
}

TonConnectUiOptions

Runtime-tunable UI options. Pass on the constructor, or assign through tonConnectUI.uiOptions = { ... } to update them later — the setter merges the patch with the previous value and re-renders.

interface TonConnectUiOptions {
    uiPreferences?: UIPreferences;
    buttonRootId?: string | null;
    language?: Locales;
    walletsListConfiguration?: WalletsListConfiguration;
    walletsRequiredFeatures?: RequiredFeatures;
    walletsPreferredFeatures?: RequiredFeatures;
    actionsConfiguration?: ActionConfiguration;
    enableAndroidBackHandler?: boolean;
    analytics?: AnalyticsSettings;
}

UIPreferences

Visual configuration for SDK-rendered components — theme, border radius, custom palette per theme. Pass on TonConnectUiOptions.uiPreferences (constructor or uiOptions setter).

interface UIPreferences {
    theme?: Theme;
    borderRadius?: BorderRadius;
    colorsSet?: Partial<Record<THEME, PartialColorsSet>>;
}

WalletsModal

Imperative handle on the connect-wallet modal. Available as tonConnectUI.modal. Prefer the convenience methods on TonConnectUI (openModal(), closeModal(), onModalStateChange()) — this interface is exposed for advanced cases that need direct access to the modal state.

interface WalletsModal {
    open: (options?: { traceId?: string }) => void;
    close: (reason?: WalletsModalCloseReason) => void;
    onStateChange: (callback: (state: WalletsModalState) => void) => () => void;
    state: WalletsModalState;
}

Theme

Theme identifier accepted by UIPreferences.theme. Either one of the built-in THEME values, or 'SYSTEM' to follow the user's OS preference via prefers-color-scheme (default).

type Theme = THEME | 'SYSTEM';

BorderRadius

Border-radius preset applied to SDK UI elements.

• 'm' — medium rounding (default).
• 's' — small rounding.
• 'none' — square corners.

type BorderRadius = 'm' | 's' | 'none';

ColorsSet

Full palette for one theme — every named slot. Pass as a per-theme entry in UIPreferences.colorsSet. The PartialColorsSet variant is the deep-partial form; missing values fall back to the built-in palette.

Color values are any CSS color expression (#29CC6A, rgb(...), ...).

type ColorsSet = {
    constant: { black: Color; white: Color };
    connectButton: { background: Color; foreground: Color };
    accent: Color;
    telegramButton: Color;
    icon: { primary: Color; secondary: Color; tertiary: Color; success: Color; error: Color };
    background: { primary: Color; secondary: Color; segment: Color; tint: Color; qr: Color };
    text: { primary: Color; secondary: Color };
};

PartialColorsSet

Deep-partial of ColorsSet — every slot is optional.

type PartialColorsSet = {
    constant?: { black?: Color; white?: Color };
    connectButton?: { background?: Color; foreground?: Color };
    accent?: Color;
    telegramButton?: Color;
    icon?: { primary?: Color; secondary?: Color; tertiary?: Color; success?: Color; error?: Color };
    background?: { primary?: Color; secondary?: Color; segment?: Color; tint?: Color; qr?: Color };
    text?: { primary?: Color; secondary?: Color };
};

WalletOpenMethod

How the dApp ended up connecting to the wallet. Set on WalletInfoRemoteWithOpenMethod.openMethod for remote wallets.

• 'qrcode' — user scanned the connect QR code.
• 'universal-link' — user tapped a universal link (mobile flow).
• 'custom-deeplink' — user tapped a wallet-specific deep link.

type WalletOpenMethod = 'qrcode' | 'universal-link' | 'custom-deeplink';

WalletInfoWithOpenMethod

Wallets-list info for the connected wallet — the registry (or custom) entry plus, for remote wallets, the WalletOpenMethod the user picked. It is merged with the runtime Wallet from @tonconnect/sdk to form ConnectedWallet, the shape tonConnectUI.wallet resolves to.

Used by UI components that want to render wallet branding next to the connected account.

type WalletInfoWithOpenMethod =
    | WalletInfoInjectable
    | WalletInfoRemoteWithOpenMethod
    | WalletInfoWalletConnect
    | (WalletInfoInjectable & WalletInfoRemoteWithOpenMethod);

WalletInfoRemoteWithOpenMethod

Remote wallet info enriched with the WalletOpenMethod the user took.

type WalletInfoRemoteWithOpenMethod = WalletInfoRemote & { openMethod?: WalletOpenMethod };

WalletInfoWalletConnect

Pseudo-wallet entry used to surface the WalletConnect bridge inside the picker. WalletConnect itself is a multi-wallet transport — the visible "wallet" is a placeholder with a fixed appName.

type WalletInfoWalletConnect = WalletInfoBase & { type: 'wallet-connect' };

ConnectedWallet

Wallet merged with the wallets-list entry. The shape tonConnectUI.wallet resolves to once a wallet is connected; null while disconnected.

type ConnectedWallet = Wallet & WalletInfoWithOpenMethod;

EmbeddedTResponse

Discriminated envelope returned by TonConnectUI.sendTransaction / signData / signMessage when enableEmbeddedRequest: true is set on the call. Without the flag the methods return the raw method response.

Branch on hasResponse:

• hasResponse: true — the wallet signed the request. response carries the regular method-specific result.
• hasResponse: false — the wallet completed the connect step but did not return a signed result.

dispatched semantics

• dispatched: false — the SDK did not put the request into the connect URL. The wallet never saw it.
• dispatched: true — the SDK did fold the request into the connect URL, but no signed result came back. The wallet may have already prompted the user (and potentially submitted the transaction). Do not retry silently. Surface a retry button and, where possible, verify on-chain or in your backend that the action hasn't already landed before re-prompting.

type EmbeddedTResponse<TResponse> =
    | { response: TResponse; hasResponse: true }
    | { connectResult: { dispatched: boolean }; hasResponse: false };

EmbeddedSendTransactionResponse

type EmbeddedSendTransactionResponse = EmbeddedTResponse<SendTransactionResponse>;

EmbeddedSignDataResponse

type EmbeddedSignDataResponse = EmbeddedTResponse<SignDataResponse>;

EmbeddedSignMessageResponse

type EmbeddedSignMessageResponse = EmbeddedTResponse<SignMessageResponse>;

Color

type Color = Property.Color;

Loadable

type Loadable<T> = LoadableLoading | LoadableReady<T>;

LoadableLoading

type LoadableLoading = { state: 'loading' };

LoadableReady

type LoadableReady<T> = { state: 'ready'; value: T };

Locales

Locales supported by SDK-rendered strings. Pass on TonConnectUiOptions.language to override the system default.

Currently 'en' (English) and 'ru' (Russian).

type Locales = 'en' | 'ru';

ReturnStrategy

Where the wallet sends the user after they approve or decline a deep-link request. Carried as the ret query parameter on the wallet's universal / deep link.

• 'back' (default) — return to the originating app (browser, native host, etc.).
• 'none' — wallet does not redirect; the user stays in the wallet.
• `${string}://${string}` — open the given URL. dApps should not pass their own webpage URL when running as a webpage; use this form for native-app callbacks or TMA t.me/... links.

type ReturnStrategy = 'back' | 'none' | `${string}://${string}`;

TonConnectUiCreateOptions

Constructor options for new TonConnectUI(...). Either pass a manifestUrl and let TonConnectUI create the underlying connector for you, or hand in an existing ITonConnect instance via connector.

Both shapes extend TonConnectUiCreateOptionsBase (and therefore TonConnectUiOptions), so the UI-level options — theme, language, wallet filters, analytics — are the same regardless of which form you pick.

type TonConnectUiCreateOptions = TonConnectUiOptionsWithConnector | TonConnectUiOptionsWithManifest;

UIWallet

Shape accepted by WalletsListConfiguration.includeWallets to add custom wallets to the picker.

Build a UIWallet when the wallet your dApp targets is not yet listed in the canonical wallets registry.

type UIWallet = Omit<WalletInfoInjectable, 'injected' | 'embedded'> | WalletInfoRemote;

WalletsListConfiguration

Overrides for the wallets list shown inside the connect modal — add custom wallets, alter ordering, etc.

type WalletsListConfiguration = { includeWallets?: UIWallet[] };

WalletModalOpened

Modal is open. When the modal was opened via the embedded-request flow, embeddedRequest carries the queued sendTransaction / signData / signMessage the SDK will fold into the connect URL.

type WalletModalOpened = { status: 'opened'; closeReason: null; embeddedRequest?: Consumable<EmbeddedRequest> | null };

WalletModalClosed

Modal is closed. closeReason is populated when the close was driven by the user.

type WalletModalClosed = { status: 'closed'; closeReason: WalletsModalCloseReason | null };

WalletsModalState

Discriminated union of all modal states, wrapped in OptionalTraceable so consumers can correlate state events with the analytics trace ID.

type WalletsModalState = OptionalTraceable<WalletModalOpened | WalletModalClosed | ChooseSupportedFeatureWalletsModal>;

WalletsModalCloseReason

Why the modal closed.

• 'action-cancelled' — user dismissed without picking a wallet (default for programmatic close()).
• 'wallet-selected' — user picked a wallet and connect flow took over.

type WalletsModalCloseReason = 'action-cancelled' | 'wallet-selected';

UserActionEvent

User action events.

type UserActionEvent =
    | VersionEvent
    | ConnectionEvent
    | ConnectionRestoringEvent
    | DisconnectionEvent
    | TransactionSigningEvent
    | DataSigningEvent
    | WalletModalOpenedEvent
    | SelectedWalletEvent;

THEME

Two built-in palettes for SDK-rendered UI.

enum THEME {
    DARK = 'DARK',
    LIGHT = 'LIGHT',
}

Errors

Every error from this package extends TonConnectUIError, which itself extends TonConnectError. Use err instanceof TonConnectUIError to catch errors from this package; use err instanceof TonConnectError to catch anything raised by the TonConnect stack.

TonConnectUIError

UI-layer precondition failure thrown by TonConnectUI — e.g. calling sendTransaction() while no wallet is connected, or when the configured buttonRootId element is not present in the document.

Extends TonConnectError so a single catch (e instanceof TonConnectError) branch covers both SDK-level and UI-level failures:

try {
    await tonConnectUI.signMessage(req);
} catch (e) {
    if (e instanceof TonConnectUIError) {
        // UI precondition (no wallet connected, etc.)
    }
}

class TonConnectUIError extends TonConnectError {
    constructor(message?: string, options?: ErrorOptions);
}

Related pages

• @tonconnect/sdk — connector core that this UI wraps.
• @tonconnect/ui-react — React bindings.
• @tonconnect/protocol — wire-format types.
• TON Connect spec — normative protocol material.