@tonconnect/ui-react

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

Types

`TonConnectButtonProps`

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

Field	Type	Description
`className`	`string`	Optional. CSS class to add to the button container.
`style`	`CSSProperties`	Optional. Inline style to add to the button container.

`TonConnectUIProviderPropsWithManifest`

interface TonConnectUIProviderPropsWithManifest {
    manifestUrl: string;
}

Field	Type	Description
`manifestUrl`	`string`	URL to the manifest with the dApp metadata that is displayed in the user’s wallet. If not passed, the manifest is loaded from `${window.location.origin}/tonconnect-manifest.json`.

`TonConnectUIProviderPropsWithConnector`

interface TonConnectUIProviderPropsWithConnector {
    connector: ITonConnect;
}

Field	Type	Description
`connector`	`ITonConnect`	TonConnect instance. Can be helpful if you use custom ITonConnect implementation, or use both of @tonconnect/sdk and @tonconnect/ui in your app.

`TonConnectUIProviderPropsBase`

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

Field	Type	Description
`restoreConnection`	`boolean`	Try to restore existing session and reconnect to the corresponding wallet.
`language`	`Locales`	Language for the phrases it the UI elements.
`widgetRootId`	`string`	HTML element id to attach the modal window element. If not passed, the library appends `div#tc-widget-root` to the end of `<body>` and uses it. Defaults to `div#tc-widget-root`.
`uiPreferences`	`UIPreferences`	Optional. UI elements configuration.
`walletsListConfiguration`	`WalletsListConfiguration`	Optional. Configuration for the wallets list in the connect wallet modal.
`walletsRequiredFeatures`	`RequiredFeatures`	Optional. Required features for wallets to be displayed in the connect wallet modal.
`walletsPreferredFeatures`	`RequiredFeatures`	Optional. Preferred features for wallets to be displayed in the connect wallet modal.
`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.

`TonConnectUIProviderProps`

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

Components

`TonConnectButton()`

TonConnect Button is a universal UI component for initializing connection. After a wallet connects, it transforms into a wallet menu. Place it in the top right corner of your app. Props on TonConnectButtonProps.

function TonConnectButton(props: TonConnectButtonProps): ReactNode;

Parameter	Type	Description
`props`	`TonConnectButtonProps`	—

Returns ReactNode.

`TonConnectUIProvider()`

Add TonConnectUIProvider at the root of your app. Specify UI options through its props. Every TonConnect UI hook call and <TonConnectButton /> must live somewhere inside this provider. Props on TonConnectUIProviderProps.

function TonConnectUIProvider(props: TonConnectUIProviderProps): ReactNode;

Parameter	Type	Description
`props`	`TonConnectUIProviderProps`	—

Returns ReactNode.

Hooks

`useIsConnectionRestored()`

Indicates current status of the connection restoring process. Returns false on first render and flips to true once tonConnectUI.connectionRestored resolves. Use it to gate UI that depends on knowing the final connection state — e.g. avoid rendering a “Connect wallet” CTA before a session restore has had a chance to complete.

function useIsConnectionRestored(): boolean;

Returns boolean. Throws: TonConnectProviderNotSetError — when called on the client side without a <TonConnectUIProvider> ancestor. Example:

function App() {
    const restored = useIsConnectionRestored();
    const wallet = useTonWallet();

    if (!restored) {
        return <p>Restoring session...</p>;
    }

    return wallet ? <Dashboard /> : <ConnectScreen />;
}

`useTonAddress()`

Use it to get the user’s current TON wallet address. Returns an empty string when no wallet is connected. When userFriendly is true (the default), the address is converted to the non-bounceable user-friendly form, with the test-only flag set when the wallet reports the testnet chain. Pass false to receive the raw 0:<hex> form straight from wallet.account.address.

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

Parameter	Type	Description
`userFriendly`	`boolean`	Optional. Allows to choose format of the address. Defaults to `true`.

Returns string. Throws: TonConnectProviderNotSetError — when called on the client side without a <TonConnectUIProvider> ancestor. Example:

function AddressLabel() {
    const userFriendly = useTonAddress();
    const raw = useTonAddress(false);

    if (!userFriendly) {
        return null;
    }

    return (
        <p>
            Address: {userFriendly} (raw: {raw})
        </p>
    );
}

`useTonConnectModal()`

Use it to get access to the open/close modal functions. Subscribes to tonConnectUI.onModalStateChange internally, so the component re-renders whenever the modal opens, closes, or moves between states. The returned state matches the latest reported value, or null until the underlying instance is ready.

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

Returns Omit<WalletsModal, 'onStateChange'>. Throws: TonConnectProviderNotSetError — when called on the client side without a <TonConnectUIProvider> ancestor. Example:

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

    return (
        <button onClick={state?.status === 'opened' ? close : open}>
            {state?.status === 'opened' ? 'Close' : 'Connect wallet'}
        </button>
    );
}

`useTonConnectUI()`

Use it to get access to the TonConnectUI instance and UI options updating function. The returned tuple is stable across renders. setOptions merges into tonConnectUI.uiOptions; call it to switch language, theme, return strategy, or other UI preferences at runtime.

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

Returns [TonConnectUI, (options: TonConnectUiOptions) => void]. Throws: TonConnectProviderNotSetError — when called on the client side without a <TonConnectUIProvider> ancestor. On the server side the hook returns a no-op tuple instead. Example:

function ConnectButton() {
    const [tonConnectUI, setOptions] = useTonConnectUI();

    return (
        <>
            <button onClick={() => tonConnectUI.openModal()}>Connect</button>
            <button onClick={() => setOptions({ language: 'ru' })}>Switch to RU</button>
        </>
    );
}

`useTonWallet()`

Use it to get the user’s current TON wallet. Returns null when no wallet is connected. Subscribes to tonConnectUI.onStatusChange internally, so the component re-renders whenever the user connects, disconnects, or switches accounts.

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

Returns Wallet | unknown | null. Throws: TonConnectProviderNotSetError — when called on the client side without a <TonConnectUIProvider> ancestor. Example:

function WalletStatus() {
    const wallet = useTonWallet();

    if (!wallet) {
        return <p>No wallet connected</p>;
    }

    return <p>Connected: {wallet.account.address}</p>;
}

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.