@tonconnect/ui - TON Docs

@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 v2.5.0-alpha.0.

`TonConnectUI`

Constructor

Creates a new TonConnectUI instance and mounts the widget into the DOM.

new TonConnectUI(options?: TonConnectUiCreateOptions)

Parameter	Type	Description
`options`	`TonConnectUiCreateOptions`	Optional. Creation options. Either `manifestUrl` or `connector` must be provided.

Throws:

TonConnectUIError — when neither manifestUrl nor connector is specified in options.
TonConnectUIError — when options.buttonRootId is set but the element does not exist in the document (the constructor applies the initial UI options).

Instance properties

Property	Type	Description
`walletsRequiredFeatures`	`RequiredFeatures \| undefined`	Required features that wallets must support to appear in the wallets list. Wallets not supporting these features are excluded from the UI.
`walletsPreferredFeatures`	`RequiredFeatures \| undefined`	Preferred features used to sort and rank wallets in the wallets list. Wallets supporting these features appear first in the UI.
`connector`	`ITonConnect`	TonConnect instance.
`modal`	`WalletsModal`	Manages the modal window state.
`connectionRestored`	`Promise<boolean>`	Promise that resolves after end of the connection restoring process (promise fires 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.
`connected`	`boolean`	Current connection status.
`account`	`Account \| null`	Current connected account or null.
`wallet`	`Wallet \| unknown \| null`	Current connected wallet app and its info or null.
`uiOptions`	`TonConnectUiOptions`	Sets and applies new UI options. Pass a partial options object; it is merged with the current options. (write-only)
`modalState`	`WalletsModalState`	Returns current modal window state.
`singleWalletModalState`	`SingleWalletModalState`	Returns current single wallet modal window state.

`setConnectRequestParameters()`

Use it to customize ConnectRequest and add tonProof payload. You can call it multiple times to set updated tonProof payload if 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 its value has been changed, the QR is re-rendered.

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

Parameter	Type	Description
`connectRequestParameters`	`Loadable<ConnectAdditionalRequest> \| undefined \| null`	—

`setConnectionNetwork()`

Set desired network for the connection. Can only be set before connecting. If wallet connects with a different chain, the SDK throws an error and aborts connection.

setConnectionNetwork(network?: ChainId): void;

Parameter	Type	Description
`network`	`ChainId`	Optional. Desired network id (e.g., ‘-239’, ‘-3’, or custom). Pass undefined to allow any network.

`getWallets()`

Returns available wallets list.

getWallets(): Promise<WalletInfo[]>;

Returns Promise<WalletInfo[]>.

`onStatusChange()`

Subscribes to connection status changes.

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

Parameter	Type	Description
`callback`	`(wallet: ConnectedWallet \| null) => void`	Called with the connected wallet on connect, or `null` on disconnect.
`errorsHandler`	`(err: TonConnectError) => void`	Optional. Optional handler called when a `TonConnectError` occurs.

Returns () => void. Unsubscribe function — call it to stop receiving status updates.

`openModal()`

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

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

Parameter	Type	Description
`options`	`{ traceId?: string }`	Optional.

Returns Promise<void>.

`closeModal()`

Closes the modal window.

closeModal(reason?: WalletsModalCloseReason): void;

Parameter	Type	Description
`reason`	`WalletsModalCloseReason`	Optional.

`onModalStateChange()`

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

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

Parameter	Type	Description
`onChange`	`(state: WalletsModalState) => void`	—

Returns () => void.

`openSingleWalletModal()`

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

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

Parameter	Type	Description
`wallet`	`string`	—

Returns Promise<void>.

`closeSingleWalletModal()`

Close the single wallet modal window.

closeSingleWalletModal(closeReason?: WalletsModalCloseReason): void;

Parameter	Type	Description
`closeReason`	`WalletsModalCloseReason`	Optional.

`onSingleWalletModalStateChange()`

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;

Parameter	Type	Description
`onChange`	`(state: SingleWalletModalState) => 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>;

Parameter	Type	Description
`options`	`{ traceId?: string }`	Optional. Optional tracing options.

Returns Promise<ConnectedWallet>. Promise that resolves to the connected wallet. Throws: TonConnectUIError — when the connection is aborted or the user cancels.

`disconnect()`

Disconnects the wallet and clears stored session data.

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

Parameter	Type	Description
`options`	`{ traceId?: string }`	Optional. Optional tracing options.

Returns Promise<void>. Promise that resolves when the disconnect is complete.

`sendTransaction()`

Opens the modal window and handles the transaction sending.

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

Parameter	Type	Description
`tx`	`SendTransactionRequest`	Transaction to send.
`options`	`ActionOptions<SendTransactionResponse>`	Optional. Modal and notifications behaviour settings. Default shows only the ‘before’ modal and all notifications.

Returns Promise<OptionalTraceable<SendTransactionResponse>>. Promise that resolves to the transaction response. Throws:

TonConnectUIError — when no wallet is connected and options.onConnected is not provided.
TonConnectUIError — when the user cancels the transaction in the modal.
TonConnectError — subclasses raised by the underlying SDK call (e.g. WalletWrongNetworkError, WalletNotSupportFeatureError, UserRejectsError, BadRequestError, UnknownAppError) are propagated unchanged.

`signData()`

Signs the data and returns the signature.

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

Parameter	Type	Description
`data`	`SignDataPayload`	Data payload to sign.
`options`	`ActionOptions<SignDataResponse>`	Optional. Modal and notifications behaviour settings.

Returns Promise<SignDataResponse>. Promise that resolves to the sign-data response including the signature. Throws:

TonConnectUIError — when no wallet is connected and options.onConnected is not provided.
TonConnectUIError — when the user cancels the signing in the modal.
TonConnectError — subclasses raised by the underlying SDK call (e.g. WalletNotSupportFeatureError, UserRejectsError, BadRequestError) are propagated unchanged.

`signMessage()`

Signs a message built from a transaction request and returns the signed internal message BoC.

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

Parameter	Type	Description
`message`	`SignMessageRequest`	Transaction-like request describing the internal message to sign.
`options`	`ActionOptions<SignMessageResponse>`	Optional. Modal and notifications behaviour settings.

Returns Promise<OptionalTraceable<SignMessageResponse>>. Promise that resolves to the sign-message response including the signed BoC. Throws:

TonConnectUIError — when no wallet is connected and options.onConnected is not provided.
TonConnectUIError — when the user cancels the signing in the modal.
TonConnectError — subclasses raised by the underlying SDK call are propagated unchanged.

Static methods

Method	Description
`TonConnectUI.getWallets()`	Returns the list of available wallets.

Types

`ActionConfiguration`

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

Field	Type	Description
`modals`	`'all' \| ('before' \| 'success' \| 'error')[]`	Optional. Configure action modals behavior.
`notifications`	`'all' \| ('before' \| 'success' \| 'error')[]`	Optional. Configure action notifications behavior.
`returnStrategy`	`ReturnStrategy`	Optional. Specifies return strategy for the deeplink when user signs/declines the request.
`twaReturnUrl`	`${string}://${string}`	Optional. Specifies return url for TWA-TWA connections. This is applied as a return strategy if dApp is opened as a TWA and user selects TWA wallet (overrides `returnStrategy` if set).
`skipRedirectToWallet`	`'ios' \| 'always' \| 'never'`	Optional.

`TonConnectUiOptionsWithManifest`

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;
}

Field	Type	Description
`manifestUrl`	`string`	Optional. URL to the manifest with the dApp metadata that is displayed in the user’s wallet. If not passed, the manifest from `${window.location.origin}/tonconnect-manifest.json` is used.
`restoreConnection`	`boolean`	Optional. Try to restore existing session and reconnect to the corresponding wallet.
`widgetRootId`	`string`	Optional. HTML element id to attach the modal window element. If not passed, `div#tc-widget-root` is appended to the end of `<body>` and used. Defaults to `'tc-widget-root'`.
`eventDispatcher`	`EventDispatcher<RequestVersionEvent \| ResponseVersionEvent \| ConnectionStartedEvent \| ConnectionCompletedEvent \| ConnectionErrorEvent \| ConnectionRestoringStartedEvent \| ConnectionRestoringCompletedEvent \| ConnectionRestoringErrorEvent \| DisconnectionEvent \| TransactionSentForSignatureEvent \| TransactionSignedEvent \| TransactionSigningFailedEvent \| DataSentForSignatureEvent \| DataSignedEvent \| DataSigningFailedEvent \| WalletModalOpenedEvent \| SelectedWalletEvent>`	Optional. Event dispatcher to track user actions. By default, it uses `window.dispatchEvent` for browser environment. Defaults to `new BrowserEventDispatcher()`.
`uiPreferences`	`UIPreferences`	Optional. UI elements configuration.
`buttonRootId`	`string \| null`	Optional. HTML element id to attach the wallet connect button. If not passed the button does not appear.
`language`	`Locales`	Optional. Language for the phrases in the UI elements.
`walletsListConfiguration`	`WalletsListConfiguration`	Optional. Configuration for the wallets list in the connect wallet modal.
`walletsRequiredFeatures`	`RequiredFeatures`	Optional. Required features for wallets. If a wallet doesn’t support the required features, it is disabled.
`walletsPreferredFeatures`	`RequiredFeatures`	Optional. Preferred features for wallets. If a wallet doesn’t support the preferred features, it is moved to the end of the list.
`actionsConfiguration`	`ActionConfiguration`	Optional. Configuration for action-period (e.g. sendTransaction) UI elements: modals and notifications and wallet behaviour (return strategy).
`enableAndroidBackHandler`	`boolean`	Optional. Specifies whether the Android back button should be used to close modals and notifications on Android devices.
`analytics`	`AnalyticsSettings`	Optional. Analytics configuration forwarded to the underlying TonConnect SDK instance.

`TonConnectUiOptionsWithConnector`

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;
}

Field	Type	Description
`connector`	`ITonConnect`	Optional. TonConnect instance. Can be helpful if you use custom ITonConnect implementation, or use both of @tonconnect/sdk and @tonconnect/ui in your app.
`restoreConnection`	`boolean`	Optional. Try to restore existing session and reconnect to the corresponding wallet.
`widgetRootId`	`string`	Optional. HTML element id to attach the modal window element. If not passed, `div#tc-widget-root` is appended to the end of `<body>` and used. Defaults to `'tc-widget-root'`.
`eventDispatcher`	`EventDispatcher<RequestVersionEvent \| ResponseVersionEvent \| ConnectionStartedEvent \| ConnectionCompletedEvent \| ConnectionErrorEvent \| ConnectionRestoringStartedEvent \| ConnectionRestoringCompletedEvent \| ConnectionRestoringErrorEvent \| DisconnectionEvent \| TransactionSentForSignatureEvent \| TransactionSignedEvent \| TransactionSigningFailedEvent \| DataSentForSignatureEvent \| DataSignedEvent \| DataSigningFailedEvent \| WalletModalOpenedEvent \| SelectedWalletEvent>`	Optional. Event dispatcher to track user actions. By default, it uses `window.dispatchEvent` for browser environment. Defaults to `new BrowserEventDispatcher()`.
`uiPreferences`	`UIPreferences`	Optional. UI elements configuration.
`buttonRootId`	`string \| null`	Optional. HTML element id to attach the wallet connect button. If not passed the button does not appear.
`language`	`Locales`	Optional. Language for the phrases in the UI elements.
`walletsListConfiguration`	`WalletsListConfiguration`	Optional. Configuration for the wallets list in the connect wallet modal.
`walletsRequiredFeatures`	`RequiredFeatures`	Optional. Required features for wallets. If a wallet doesn’t support the required features, it is disabled.
`walletsPreferredFeatures`	`RequiredFeatures`	Optional. Preferred features for wallets. If a wallet doesn’t support the preferred features, it is moved to the end of the list.
`actionsConfiguration`	`ActionConfiguration`	Optional. Configuration for action-period (e.g. sendTransaction) UI elements: modals and notifications and wallet behaviour (return strategy).
`enableAndroidBackHandler`	`boolean`	Optional. Specifies whether the Android back button should be used to close modals and notifications on Android devices.
`analytics`	`AnalyticsSettings`	Optional. Analytics configuration forwarded to the underlying TonConnect SDK instance.

`TonConnectUiCreateOptionsBase`

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;
}

Field	Type	Description
`restoreConnection`	`boolean`	Optional. Try to restore existing session and reconnect to the corresponding wallet.
`widgetRootId`	`string`	Optional. HTML element id to attach the modal window element. If not passed, `div#tc-widget-root` is appended to the end of `<body>` and used. Defaults to `'tc-widget-root'`.
`eventDispatcher`	`EventDispatcher<RequestVersionEvent \| ResponseVersionEvent \| ConnectionStartedEvent \| ConnectionCompletedEvent \| ConnectionErrorEvent \| ConnectionRestoringStartedEvent \| ConnectionRestoringCompletedEvent \| ConnectionRestoringErrorEvent \| DisconnectionEvent \| TransactionSentForSignatureEvent \| TransactionSignedEvent \| TransactionSigningFailedEvent \| DataSentForSignatureEvent \| DataSignedEvent \| DataSigningFailedEvent \| WalletModalOpenedEvent \| SelectedWalletEvent>`	Optional. Event dispatcher to track user actions. By default, it uses `window.dispatchEvent` for browser environment. Defaults to `new BrowserEventDispatcher()`.
`uiPreferences`	`UIPreferences`	Optional. UI elements configuration.
`buttonRootId`	`string \| null`	Optional. HTML element id to attach the wallet connect button. If not passed the button does not appear.
`language`	`Locales`	Optional. Language for the phrases in the UI elements.
`walletsListConfiguration`	`WalletsListConfiguration`	Optional. Configuration for the wallets list in the connect wallet modal.
`walletsRequiredFeatures`	`RequiredFeatures`	Optional. Required features for wallets. If a wallet doesn’t support the required features, it is disabled.
`walletsPreferredFeatures`	`RequiredFeatures`	Optional. Preferred features for wallets. If a wallet doesn’t support the preferred features, it is moved to the end of the list.
`actionsConfiguration`	`ActionConfiguration`	Optional. Configuration for action-period (e.g. sendTransaction) UI elements: modals and notifications and wallet behaviour (return strategy).
`enableAndroidBackHandler`	`boolean`	Optional. Specifies whether the Android back button should be used to close modals and notifications on Android devices.
`analytics`	`AnalyticsSettings`	Optional. Analytics configuration forwarded to the underlying TonConnect SDK instance.

`TonConnectUiOptions`

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

Field	Type	Description
`uiPreferences`	`UIPreferences`	Optional. UI elements configuration.
`buttonRootId`	`string \| null`	Optional. HTML element id to attach the wallet connect button. If not passed the button does not appear.
`language`	`Locales`	Optional. Language for the phrases in the UI elements.
`walletsListConfiguration`	`WalletsListConfiguration`	Optional. Configuration for the wallets list in the connect wallet modal.
`walletsRequiredFeatures`	`RequiredFeatures`	Optional. Required features for wallets. If a wallet doesn’t support the required features, it is disabled.
`walletsPreferredFeatures`	`RequiredFeatures`	Optional. Preferred features for wallets. If a wallet doesn’t support the preferred features, it is moved to the end of the list.
`actionsConfiguration`	`ActionConfiguration`	Optional. Configuration for action-period (e.g. sendTransaction) UI elements: modals and notifications and wallet behaviour (return strategy).
`enableAndroidBackHandler`	`boolean`	Optional. Specifies whether the Android back button should be used to close modals and notifications on Android devices.
`analytics`	`AnalyticsSettings`	Optional. Analytics configuration forwarded to the underlying TonConnect SDK instance.

`UIPreferences`

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

Field	Type	Description
`theme`	`Theme`	Optional. Color theme for the UI elements. When set to `'SYSTEM'` the theme follows the OS preference.
`borderRadius`	`BorderRadius`	Optional. Border radius for UI elements.
`colorsSet`	`Partial<Record<THEME, PartialColorsSet>>`	Optional. Configure colors scheme for different themes.

`WalletsModal`

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

Field	Type	Description
`open`	`(options?: { traceId?: string }) => void`	Open the modal.
`close`	`(reason?: WalletsModalCloseReason) => void`	Close the modal.
`onStateChange`	`(callback: (state: WalletsModalState) => void) => () => void`	Subscribe to the modal window status changes.
`state`	`WalletsModalState`	Current modal window state.

`Theme`

UI colour theme, including automatic system-preference detection.

type Theme = THEME | 'SYSTEM';

`BorderRadius`

Corner radius preset for the UI widget. 'm' is the default rounded style; 'none' disables rounding.

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

`ColorsSet`

Complete set of colour tokens used to theme the TonConnectUI widget.

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`

Partial colour token override — only the provided tokens are applied; the rest fall back to defaults.

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`

Method used to open the wallet app from the dApp.

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

`WalletInfoWithOpenMethod`

Wallet info enriched with the open method used to initiate the connection.

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

`WalletInfoRemoteWithOpenMethod`

Remote wallet info that also carries the WalletOpenMethod used to connect.

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

`WalletInfoWalletConnect`

Wallet info for wallets connected via the WalletConnect bridge.

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

`ConnectedWallet`

A fully connected wallet: combines session data from Wallet with its UI metadata.

type ConnectedWallet = Wallet & WalletInfoWithOpenMethod;

`Color`

type Color = Property.Color;

`Loadable`

A value that is either loading or ready. Used for async state passed into the UI (e.g. setConnectRequestParameters).

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

`LoadableLoading`

Indicates that the value is not yet available.

type LoadableLoading = { state: 'loading' };

`LoadableReady`

Indicates that the value is available.

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

`Locales`

Supported UI locale codes.

type Locales = 'en' | 'ru';

`ReturnStrategy`

Specifies return strategy for the deeplink when user signs/declines the request. See details.

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

`TonConnectUiCreateOptions`

type TonConnectUiCreateOptions = TonConnectUiOptionsWithConnector | TonConnectUiOptionsWithManifest;

`UIWallet`

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

`WalletsListConfiguration`

Add corrections to the default wallets list in the modal: add custom wallets and change wallets order.

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

`WalletModalOpened`

Opened modal window state.

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

`WalletModalClosed`

Closed modal window state.

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

`WalletsModalState`

Modal window state.

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

`WalletsModalCloseReason`

Modal window close reason.

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

`UserActionEvent`

User action events.

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

`THEME`

Built-in UI colour themes.

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`

Base error class for errors thrown by @tonconnect/ui itself (modal lifecycle, UI configuration, deeplink helpers, etc.), as opposed to protocol errors surfaced from the SDK. Use err instanceof TonConnectUIError to distinguish UI-layer failures from TonConnectError subclasses raised by @tonconnect/sdk. Extends TonConnectError.

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

Constructor: Construct a TonConnectUIError. Subclasses pass these arguments through via super(...args); consumers normally interact with instances thrown by the package rather than constructing TonConnectUIError directly.

Parameter	Type	Description
`message`	`string`	Optional. Human-readable message. The resulting `error.message` is prefixed with `[TON_CONNECT_SDK_ERROR]` and the subclass name (inherited from `TonConnectError`).
`options`	`ErrorOptions`	Optional. Standard ES `Error` options.

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

Payment processing

TON Connect

Standard contracts

Smart contract development

Tolk language

Other languages

TVM: TON Virtual Machine

Nodes

Primitives

Whitepapers

Documentation Index

​Installation

​TonConnectUI

​Constructor

​Instance properties

​setConnectRequestParameters()

​setConnectionNetwork()

​getWallets()

​onStatusChange()

​openModal()

​closeModal()

​onModalStateChange()

​openSingleWalletModal()

​closeSingleWalletModal()

​onSingleWalletModalStateChange()

​connectWallet()

​disconnect()

​sendTransaction()

​signData()

​signMessage()

​Static methods

​Types

​ActionConfiguration

​TonConnectUiOptionsWithManifest

​TonConnectUiOptionsWithConnector

​TonConnectUiCreateOptionsBase

​TonConnectUiOptions

​UIPreferences

​WalletsModal

​Theme

​BorderRadius

​ColorsSet

​PartialColorsSet

​WalletOpenMethod

​WalletInfoWithOpenMethod

​WalletInfoRemoteWithOpenMethod

​WalletInfoWalletConnect

​ConnectedWallet

​Color

​Loadable

​LoadableLoading

​LoadableReady

​Locales

​ReturnStrategy

​TonConnectUiCreateOptions

​UIWallet

​WalletsListConfiguration

​WalletModalOpened

​WalletModalClosed

​WalletsModalState

​WalletsModalCloseReason

​UserActionEvent

​THEME

​Errors

​TonConnectUIError

​Related pages