# `@tonconnect/ui-react` reference (https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/ton-connect/api-reference/ui-react/content.md)



`@tonconnect/ui-react` is the React binding for [`@tonconnect/ui`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/ton-connect/api-reference/ui/content.md). 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`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/ton-connect/api-reference/ui/content.md) directly. For server-side use, see [`@tonconnect/sdk`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/ton-connect/api-reference/sdk/content.md).

## Installation [#installation]

Install from npm:

```bash
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 [#types]

### `TonConnectButtonProps` [#tonconnectbuttonprops]

Props for [`TonConnectButton`](#tonconnectbutton).

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

| Field       | Type            | Description                                                                                |
| ----------- | --------------- | ------------------------------------------------------------------------------------------ |
| `className` | `string`        | *Optional*. Extra class name applied to the button container.                              |
| `style`     | `CSSProperties` | *Optional*. Inline styles merged with the button container's `width: fit-content` default. |

### `TonConnectUIProviderPropsWithManifest` [#tonconnectuiproviderpropswithmanifest]

Pass a `manifestUrl` and let the provider build a [`TonConnectUI`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/ton-connect/api-reference/ui/content.md) from
the merged UI options.

```ts
interface TonConnectUIProviderPropsWithManifest {
    manifestUrl: string;
}
```

| Field         | Type     | Description                                                                                                                                                                                                                                          |
| ------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `manifestUrl` | `string` | HTTPS URL of the dApp's [`tonconnect-manifest.json`](https://github.com/ton-blockchain/ton-connect/blob/main/spec/manifest.md). The provider builds the [`TonConnectUI`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/ton-connect/api-reference/ui/content.md) connector from it. |

### `TonConnectUIProviderPropsWithConnector` [#tonconnectuiproviderpropswithconnector]

Pass a pre-built [`ITonConnect`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/ton-connect/api-reference/sdk/content.md) (typically from `@tonconnect/sdk`) — the
provider wraps it in a [`TonConnectUI`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/ton-connect/api-reference/ui/content.md). Useful when the dApp drives the
underlying SDK directly and only wants the React UI on top.

```ts
interface TonConnectUIProviderPropsWithConnector {
    connector: ITonConnect;
}
```

| Field       | Type                                                                     | Description                                                                                                                       |
| ----------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| `connector` | [`ITonConnect`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/ton-connect/api-reference/sdk/content.md) | Existing [`ITonConnect`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/ton-connect/api-reference/sdk/content.md) instance. The provider will not create its own. |

### `TonConnectUIProviderPropsBase` [#tonconnectuiproviderpropsbase]

Common UI options accepted in addition to the constructor selector
(`manifestUrl` / `connector`). All optional; mirror the fields on
[`TonConnectUiOptions`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/ton-connect/api-reference/ui/content.md) from `@tonconnect/ui`.

```ts
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`                                                                                         | Attempt to restore the previous session from storage on mount. Set to `false` for flows that prefer an explicit connect step. Defaults to `true`.                                                                                                                 |
| `language`                 | [`Locales`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/ton-connect/api-reference/ui/content.md)                                   | Language for SDK-rendered strings. Defaults to `'en'`.                                                                                                                                                                                                            |
| `widgetRootId`             | `string`                                                                                          | HTML element ID under which the modal root is attached. Defaults to `tc-widget-root` (created at the end of `<body>`).                                                                                                                                            |
| `uiPreferences`            | [`UIPreferences`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/ton-connect/api-reference/ui/content.md)                       | *Optional*. Visual configuration — theme, border radius, color overrides.                                                                                                                                                                                         |
| `walletsListConfiguration` | [`WalletsListConfiguration`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/ton-connect/api-reference/ui/content.md) | *Optional*. Wallets-list overrides — include extra wallets, reorder existing ones.                                                                                                                                                                                |
| `walletsRequiredFeatures`  | [`RequiredFeatures`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/ton-connect/api-reference/sdk/content.md)                | *Optional*. Hide wallets from the picker that don't advertise the listed features. Non-matching entries are greyed out below the separator and rejected at connect time with `WalletMissingRequiredFeaturesError`.                                                |
| `walletsPreferredFeatures` | [`RequiredFeatures`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/ton-connect/api-reference/sdk/content.md)                | *Optional*. Soft preference filter — non-matching wallets remain clickable but sorted below the separator. The SDK does NOT enforce the match at connect time.                                                                                                    |
| `actionsConfiguration`     | [`ActionConfiguration`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/ton-connect/api-reference/ui/content.md)           | *Optional*. Modal / notification behavior and the return strategy for action deep links. See [`ActionConfiguration`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/ton-connect/api-reference/ui/content.md).                                                                             |
| `enableAndroidBackHandler` | `boolean`                                                                                         | *Optional*. Close modals and notifications when the Android back button is pressed. Disable when the dApp manages browser history manually. Defaults to `true`.                                                                                                   |
| `analytics`                | [`AnalyticsSettings`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/ton-connect/api-reference/sdk/content.md)              | *Optional*. Analytics configuration forwarded to the underlying [`TonConnect`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/ton-connect/api-reference/sdk/content.md) instance. See [`AnalyticsSettings`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/ton-connect/api-reference/sdk/content.md) from `@tonconnect/sdk`. |

### `TonConnectUIProviderProps` [#tonconnectuiproviderprops]

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

* [`TonConnectUIProviderPropsWithManifest`](#tonconnectuiproviderpropswithmanifest) — most common: pass a
  `manifestUrl`, the provider builds a [`TonConnectUI`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/ton-connect/api-reference/ui/content.md) for you.
* [`TonConnectUIProviderPropsWithConnector`](#tonconnectuiproviderpropswithconnector) — pass a pre-built
  [`ITonConnect`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/ton-connect/api-reference/sdk/content.md) (from `@tonconnect/sdk`); the provider wraps it in UI.
* `TonConnectUIProviderPropsWithInstance` — pass an externally
  constructed [`TonConnectUI`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/ton-connect/api-reference/ui/content.md).

The manifest / connector variants accept the same UI-level options as the
vanilla [`TonConnectUiOptions`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/ton-connect/api-reference/ui/content.md) (theme, language, wallet filters,
analytics).

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

## Components [#components]

### `TonConnectButton()` [#tonconnectbutton]

```ts
function TonConnectButton(props: TonConnectButtonProps): ReactNode;
```

| Parameter | Type                    | Description |
| --------- | ----------------------- | ----------- |
| `props`   | `TonConnectButtonProps` | —           |

Returns `ReactNode`.

### `TonConnectUIProvider()` [#tonconnectuiprovider]

```ts
function TonConnectUIProvider(props: TonConnectUIProviderProps): ReactNode;
```

| Parameter | Type                        | Description |
| --------- | --------------------------- | ----------- |
| `props`   | `TonConnectUIProviderProps` | —           |

Returns `ReactNode`.

## Hooks [#hooks]

### `useIsConnectionRestored()` [#useisconnectionrestored]

Indicates current status of the connection restoring process.

```ts
function useIsConnectionRestored(): boolean;
```

Returns `boolean`.

### `useTonAddress()` [#usetonaddress]

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

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

| Parameter      | Type      | Description                                                                                                                                                                                            |
| -------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `userFriendly` | `boolean` | *Optional*. — `true` (default) returns the non-bounceable base64url user-friendly form (`UQ…` on mainnet, `0Q…` on testnet). Pass `false` to get the raw `<workchain>:<hex>` form. Defaults to `true`. |

Returns `string`.

**Example:**

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

### `useTonConnectModal()` [#usetonconnectmodal]

Reactive wrapper around `tonConnectUI.modal`. Returns `{ state, open,
close }` — `state` mirrors [`WalletsModalState`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/ton-connect/api-reference/ui/content.md) 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 />`.

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

Returns `Omit<WalletsModal, 'onStateChange'>`.

**Example:**

```tsx
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()` [#usetonconnectui]

Returns a tuple of:

* the singleton [`TonConnectUI`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/ton-connect/api-reference/ui/content.md) instance — call every method (`connectWallet`,
  `sendTransaction`, `signData`, `signMessage`, modal helpers) on it;
* a `setOptions(options)` callback that merges the partial
  [`TonConnectUiOptions`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/ton-connect/api-reference/ui/content.md) 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.

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

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

**Example:**

```tsx
const [tonConnectUI, setOptions] = useTonConnectUI();

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

### `useTonWallet()` [#usetonwallet]

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

The shape mirrors `tonConnectUI.wallet` — [`Wallet`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/ton-connect/api-reference/sdk/content.md) (from `@tonconnect/sdk`)
merged with the picker entry for the wallet (icon, name, open method).

Must be called inside a `<TonConnectUIProvider>`.

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

Returns `Wallet | Wallet & WalletInfoWithOpenMethod | null`.

**Example:**

```tsx
const wallet = useTonWallet();

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

## Errors [#errors]

Every error from this package extends [`TonConnectUIReactError`](#tonconnectuireacterror), which itself extends [`TonConnectUIError`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/ton-connect/api-reference/ui/content.md). Use `err instanceof TonConnectUIReactError` to catch errors from this package; use `err instanceof TonConnectUIError` to catch anything raised by the TonConnect stack.

### `TonConnectUIReactError` [#tonconnectuireacterror]

Base class for every error thrown by `@tonconnect/ui-react`. Extends
[`TonConnectUIError`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/ton-connect/api-reference/ui/content.md) from `@tonconnect/ui`, which itself extends
[`TonConnectError`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/ton-connect/api-reference/sdk/content.md) from `@tonconnect/sdk` — a single
`catch (e instanceof TonConnectError)` branch covers them all.

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

### Error catalogue [#error-catalogue]

| Class                           | Thrown when                                                                                                                                                                                    |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TonConnectProviderNotSetError` | Thrown when a hook from `@tonconnect/ui-react` (or `<TonConnectButton />`) is used outside the subtree rendered by `<TonConnectUIProvider>`. Add the provider near the top of your React tree. |

## Related pages [#related-pages]

* [`@tonconnect/ui`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/ton-connect/api-reference/ui/content.md) — framework-agnostic UI wrapped by these bindings.
* [`@tonconnect/sdk`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/ton-connect/api-reference/sdk/content.md) — connector core under the UI.
* [`@tonconnect/protocol`](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/ton-connect/api-reference/protocol/content.md) — wire-format types.
* [TON Connect spec](https://github.com/ton-blockchain/ton-connect) — normative protocol material.