@tonconnect/ui-react reference

@tonconnect/ui-react is the React binding for @tonconnect/ui. It exposes a <TonConnectUIProvider> for app-wide setup, a <TonConnectButton> component, and hooks (useTonConnectUI, useTonAddress, useTonWallet) so React dApps can integrate TON Connect without touching the imperative UI API.

If your app does not use React, use @tonconnect/ui directly. For server-side use, see @tonconnect/sdk.

Installation

Install from npm:

npm i @tonconnect/ui-react

@tonconnect/ui-react is a client-only package — under Next.js, mark the wrapping component with "use client" or import the provider with dynamic(..., { ssr: false }).

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

Types

TonConnectButtonProps

Props for TonConnectButton.

interface TonConnectButtonProps {
    className?: string;
    style?: CSSProperties;
}

TonConnectUIProviderPropsWithManifest

Pass a manifestUrl and let the provider build a TonConnectUI from the merged UI options.

interface TonConnectUIProviderPropsWithManifest {
    manifestUrl: string;
}

TonConnectUIProviderPropsWithConnector

Pass a pre-built ITonConnect (typically from @tonconnect/sdk) — the provider wraps it in a TonConnectUI. Useful when the dApp drives the underlying SDK directly and only wants the React UI on top.

interface TonConnectUIProviderPropsWithConnector {
    connector: ITonConnect;
}

TonConnectUIProviderPropsBase

Common UI options accepted in addition to the constructor selector (manifestUrl / connector). All optional; mirror the fields on TonConnectUiOptions from @tonconnect/ui.

interface TonConnectUIProviderPropsBase {
    restoreConnection: boolean;
    language: Locales;
    widgetRootId: string;
    uiPreferences?: UIPreferences;
    walletsListConfiguration?: WalletsListConfiguration;
    walletsRequiredFeatures?: RequiredFeatures;
    walletsPreferredFeatures?: RequiredFeatures;
    actionsConfiguration?: ActionConfiguration;
    enableAndroidBackHandler?: boolean;
    analytics?: AnalyticsSettings;
}

TonConnectUIProviderProps

Props for <TonConnectUIProvider>. Pick one of three shapes:

• TonConnectUIProviderPropsWithManifest — most common: pass a manifestUrl, the provider builds a TonConnectUI for you.
• TonConnectUIProviderPropsWithConnector — pass a pre-built ITonConnect (from @tonconnect/sdk); the provider wraps it in UI.
• TonConnectUIProviderPropsWithInstance — pass an externally constructed TonConnectUI.

The manifest / connector variants accept the same UI-level options as the vanilla TonConnectUiOptions (theme, language, wallet filters, analytics).

type TonConnectUIProviderProps =
    & { children: ReactNode }
    & (Partial<TonConnectUIProviderPropsBase & (TonConnectUIProviderPropsWithManifest | TonConnectUIProviderPropsWithConnector)> | TonConnectUIProviderPropsWithInstance);

Components

TonConnectButton()

function TonConnectButton(props: TonConnectButtonProps): ReactNode;

Returns ReactNode.

TonConnectUIProvider()

function TonConnectUIProvider(props: TonConnectUIProviderProps): ReactNode;

Returns ReactNode.

Hooks

useIsConnectionRestored()

Indicates current status of the connection restoring process.

function useIsConnectionRestored(): boolean;

Returns boolean.

useTonAddress()

Reactive accessor for the connected account's TON address. Returns an empty string while disconnected.

function useTonAddress(userFriendly: boolean = true): string;

Returns string.

Example:

const address = useTonAddress();      // user-friendly
const rawAddress = useTonAddress(false);

useTonConnectModal()

Reactive wrapper around tonConnectUI.modal. Returns { state, open, close } — state mirrors WalletsModalState and re-renders on every modal lifecycle event; open / close are convenience bindings.

Must be called inside a <TonConnectUIProvider>. Use this hook when the dApp wants its own "Connect" UI separate from <TonConnectButton />.

function useTonConnectModal(): Omit<WalletsModal, 'onStateChange'>;

Returns Omit<WalletsModal, 'onStateChange'>.

Example:

const { state, open, close } = useTonConnectModal();

return (
    <>
        <div>Modal status: {state?.status}</div>
        <button onClick={open}>Open modal</button>
        <button onClick={close}>Close modal</button>
    </>
);

useTonConnectUI()

Returns a tuple of:

• the singleton TonConnectUI instance — call every method (connectWallet, sendTransaction, signData, signMessage, modal helpers) on it;
• a setOptions(options) callback that merges the partial TonConnectUiOptions into the live instance via its uiOptions setter, triggering an immediate re-render.

Must be called inside a <TonConnectUIProvider>. On the server side, the hook returns a no-op pair — call sites can render shells without crashing, but the real wiring only kicks in once the component hydrates in the browser.

function useTonConnectUI(): [TonConnectUI, (options: TonConnectUiOptions) => void];

Returns [TonConnectUI, (options: TonConnectUiOptions) => void].

Example:

const [tonConnectUI, setOptions] = useTonConnectUI();

await tonConnectUI.sendTransaction(tx, { traceId });
setOptions({ language: 'ru' });

useTonWallet()

Reactive accessor for the currently connected wallet. Returns null while disconnected and refreshes on every onStatusChange event.

The shape mirrors tonConnectUI.wallet — Wallet (from @tonconnect/sdk) merged with the picker entry for the wallet (icon, name, open method).

Must be called inside a <TonConnectUIProvider>.

function useTonWallet(): Wallet | Wallet & WalletInfoWithOpenMethod | null;

Returns Wallet | Wallet & WalletInfoWithOpenMethod | null.

Example:

const wallet = useTonWallet();

if (!wallet) return <ConnectButton />;
return <span>{wallet.device.appName} · {wallet.account.address}</span>;

Errors

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

TonConnectUIReactError

Base class for every error thrown by @tonconnect/ui-react. Extends TonConnectUIError from @tonconnect/ui, which itself extends TonConnectError from @tonconnect/sdk — a single catch (e instanceof TonConnectError) branch covers them all.

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

Error catalogue

Related pages

• @tonconnect/ui — framework-agnostic UI wrapped by these bindings.
• @tonconnect/sdk — connector core under the UI.
• @tonconnect/protocol — wire-format types.
• TON Connect spec — normative protocol material.