Skip to content

React docs improved #661

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 2 commits into from
Closed

React docs improved #661

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5033be1
improve react doc
mlikhtar Jul 11, 2024
a836a47
add more info tonconnect/react doc
mlikhtar Aug 21, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
300 changes: 166 additions & 134 deletions docs/develop/dapps/ton-connect/react.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,12 +39,12 @@ Add the `TonConnectButton`. The TonConnect Button is a universal UI component fo

```tsx
export const Header = () => {
return (
<header>
<span>My App with React UI</span>
<TonConnectButton />
</header>
);
return (
<header>
<span>My App with React UI</span>
<TonConnectButton />
</header>
);
};
```

Expand All @@ -53,7 +53,30 @@ You can add className and style props to the button as well. Note that you canno
<TonConnectButton className="my-button-class" style={{ float: "right" }}/>
```

Moreover, you always can initiate the connection manually, using `useTonConnectUI` hook and [connectWallet](https://github.com/ton-connect/sdk/tree/main/packages/ui#call-connect) method.
Moreover, you always can initiate the connection manually, using `useTonConnectUI` hook and `openModal` method (❗ Note that `connectWallet` method is deprecated ❗).

```tsx
export const Header = () => {
const [tonConnectUI, setOptions] = useTonConnectUI();
return (
<header>
<span>My App with React UI</span>
<button onClick={() => tonConnectUI.openModal()}>
Connect Wallet
</button>
</header>
);
};
```

#### Connect with a specific wallet
To open a modal window for a specific wallet, use the `openSingleWalletModal()` method. This method takes the wallet's `app_name` as a parameter (refer to the [wallets-list.json]('https://github.com/ton-blockchain/wallets-list/blob/main/wallets-v2.json') file) and opens the corresponding wallet modal. It returns a promise that resolves once the modal window has successfully opened.

```tsx
<button onClick={() => tonConnectUI.openSingleWalletModal('tonwallet')}>
Connect Wallet
</button>
```

### 4) Redirects

Expand Down Expand Up @@ -85,50 +108,76 @@ If you want to use some low-level TON Connect UI SDK features in your React app,

### useTonAddress

Use it to get user's current ton wallet address. Pass boolean parameter isUserFriendly to choose format of the address. If wallet is not connected hook will return empty string.
Use it to get user's current ton wallet address. Pass the boolean parameter `isUserFriendly` (default is `true`) to choose the format of the address. If the wallet is not connected, the hook will return an empty string.

```tsx
import { useTonAddress } from '@tonconnect/ui-react';

export const Address = () => {
const userFriendlyAddress = useTonAddress();
const rawAddress = useTonAddress(false);
const userFriendlyAddress = useTonAddress();
const rawAddress = useTonAddress(false);

return (
userFriendlyAddress && (
<div>
<span>User-friendly address: {userFriendlyAddress}</span>
<span>Raw address: {rawAddress}</span>
</div>
)
);
};
```

### useTonConnectModal
Use this hook to access the functions for opening and closing the modal window. The hook returns an object with the current modal state and methods to open and close the modal.

```tsx
import { useTonConnectModal } from '@tonconnect/ui-react';

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

return (
userFriendlyAddress && (
<div>
<span>User-friendly address: {userFriendlyAddress}</span>
<span>Raw address: {rawAddress}</span>
</div>
)
<div>
<div>Modal state: {state?.status}</div>
<button onClick={open}>Open modal</button>
<button onClick={close}>Close modal</button>
</div>
);
};
```

### useTonWallet

Use it to get user's current ton wallet. If wallet is not connected hook will return null.
Use this hook to retrieve the user's current TON wallet.
If the wallet is not connected, the hook will return `null`. The `wallet` object provides common data such as the user's address, provider, [TON proof](/develop/dapps/ton-connect/sign), and other attributes (see the [Wallet interface](https://ton-connect.github.io/sdk/interfaces/_tonconnect_sdk.Wallet.html)).

See all wallet's properties
Additionally, you can access more specific details about the connected wallet, such as its name, image, and other attributes (refer to the [WalletInfo interface](https://ton-connect.github.io/sdk/types/_tonconnect_sdk.WalletInfo.html)).

[Wallet interface](https://ton-connect.github.io/sdk/interfaces/_tonconnect_sdk.Wallet.html)
[WalletInfo interface](https://ton-connect.github.io/sdk/types/_tonconnect_sdk.WalletInfo.html)

```tsx
import { useTonWallet } from '@tonconnect/ui-react';

export const Wallet = () => {
const wallet = useTonWallet();
const wallet = useTonWallet();

return (
wallet && (
<div>
<span>Connected wallet: {wallet.name}</span>
<span>Device: {wallet.device.appName}</span>
</div>
)
);
return (
wallet && (
<div>
<span>Connected wallet address: {wallet.account.address}</span>
<span>Device: {wallet.device.appName}</span>
<span>Connected via: {wallet.provider}</span>
{wallet.connectItems?.tonProof?.proof && <span>Ton proof: {wallet.connectItems.tonProof.proof}</span>}

<div>Connected wallet info:</div>
<div>
{wallet.name} <img src={wallet.imageUrl} />
</div>
</div>
)
);
};

```

### useTonConnectUI
Expand All @@ -144,27 +193,21 @@ Use it to get access to the `TonConnectUI` instance and UI options updating func
import { Locales, useTonConnectUI } from '@tonconnect/ui-react';

export const Settings = () => {
const [tonConnectUI, setOptions] = useTonConnectUI();

const onLanguageChange = (lang: string) => {
setOptions({ language: lang as Locales });
};

return (
<div>
<button onClick={() => tonConnectUI.sendTransaction(myTransaction)}>
Send transaction
</button>

<div>
<label>language</label>
<select onChange={e => onLanguageChange(e.target.value)}>
<option value="en">en</option>
<option value="ru">ru</option>
</select>
</div>
</div>
);
const [tonConnectUI, setOptions] = useTonConnectUI();

const onLanguageChange = (language: Locales) => {
setOptions({ language });
};

return (
<div>
<label>language</label>
<select onChange={(e) => onLanguageChange(e.target.value as Locales)}>
<option value="en">en</option>
<option value="ru">ru</option>
</select>
</div>
);
};
```

Expand All @@ -176,13 +219,13 @@ You can use it to detect when connection restoring process if finished.
import { useIsConnectionRestored } from '@tonconnect/ui-react';

export const EntrypointPage = () => {
const connectionRestored = useIsConnectionRestored();
const connectionRestored = useIsConnectionRestored();

if (!connectionRestored) {
return <Loader>Please wait...</Loader>;
}
if (!connectionRestored) {
return <Loader>Please wait...</Loader>;
}

return <MainPage />;
return <MainPage />;
};
```

Expand All @@ -197,27 +240,29 @@ Send TON coins (in nanotons) to a specific address:
```js
import { useTonConnectUI } from '@tonconnect/ui-react';

const transaction = {
messages: [
{
address: "0:412410771DA82CBA306A55FA9E0D43C9D245E38133CB58F1457DFB8D5CD8892F", // destination address
amount: "20000000" //Toncoin in nanotons
}
]

}
const transaction: SendTransactionRequest = {
validUntil: Date.now() + 5 * 60 * 1000, // 5 minutes
messages: [
{
address:
"0:412410771DA82CBA306A55FA9E0D43C9D245E38133CB58F1457DFB8D5CD8892F", // destination address
amount: "20000000", // Toncoin in nanotons
},
],
};

export const Settings = () => {
const [tonConnectUI, setOptions] = useTonConnectUI();

return (
<div>
<button onClick={() => tonConnectUI.sendTransaction(transaction)}>
Send transaction
</button>
</div>
);
const [tonConnectUI, setOptions] = useTonConnectUI();

return (
<div>
<button onClick={() => tonConnectUI.sendTransaction(transaction)}>
Send transaction
</button>
</div>
);
};

```

- Get more examples here: [Preparing Messages](/develop/dapps/ton-connect/message-builders)
Expand All @@ -232,91 +277,78 @@ The principle located in Payment Processing (using tonweb). [See more](/develop/
Understand how to sign and verify messages: [Signing and Verification](/develop/dapps/ton-connect/sign)
:::

Use `tonConnectUI.setConnectRequestParameters` function to pass your connect request parameters.
To ensure that the user truly owns the declared address, you can use `ton_proof`.

This function takes one parameter:
Use the `tonConnectUI.setConnectRequestParameters` function to set up your connection request parameters. You can use it for:
- Loading State: Show a loading state while waiting for a response from your backend.
- Ready State with tonProof: Set the state to 'ready' and include the tonProof value.
- If an error occurs, remove the loader and create the connect request without additional parameters.

Set state to 'loading' while you are waiting for the response from your backend. If user opens connect wallet modal at this moment, he will see a loader.
```ts
const [tonConnectUI] = useTonConnectUI();

tonConnectUI.setConnectRequestParameters({
state: 'loading'
});
```

or
// Set loading state
tonConnectUI.setConnectRequestParameters({ state: "loading" });

Set state to 'ready' and define `tonProof` value. Passed parameter will be applied to the connect request (QR and universal link).
```ts
const [tonConnectUI] = useTonConnectUI();
// Fetch tonProofPayload from backend
const tonProofPayload: string | null =
await fetchTonProofPayloadFromBackend();

tonConnectUI.setConnectRequestParameters({
state: 'ready',
value: {
tonProof: '<your-proof-payload>'
}
});
```

or

Remove loader if it was enabled via `state: 'loading'` (e.g. you received an error instead of a response from your backend). Connect request will be created without any additional parameters.
```ts
const [tonConnectUI] = useTonConnectUI();

tonConnectUI.setConnectRequestParameters(null);
if (tonProofPayload) {
// Set ready state with tonProof
tonConnectUI.setConnectRequestParameters({
state: "ready",
value: { tonProof: tonProofPayload },
});
} else {
// Remove loader
tonConnectUI.setConnectRequestParameters(null);
}
```

#### Handling ton_proof Result

You can call `tonConnectUI.setConnectRequestParameters` multiple times if your tonProof payload has bounded lifetime (e.g. you can refresh connect request parameters every 10 minutes).

You can find `ton_proof` result in the `wallet` object when the wallet is connected:

```ts
const [tonConnectUI] = useTonConnectUI();

// enable ui loader
tonConnectUI.setConnectRequestParameters({ state: 'loading' });

// fetch you tonProofPayload from the backend
const tonProofPayload: string | null = await fetchTonProofPayloadFromBackend();

if (!tonProofPayload) {
// remove loader, connect request will be without any additional parameters
tonConnectUI.setConnectRequestParameters(null);
} else {
// add tonProof to the connect request
tonConnectUI.setConnectRequestParameters({
state: "ready",
value: { tonProof: tonProofPayload }
useEffect(() => {
tonConnectUI.onStatusChange((wallet) => {
if (
wallet.connectItems?.tonProof &&
"proof" in wallet.connectItems.tonProof
) {
checkProofInYourBackend(
wallet.connectItems.tonProof.proof,
wallet.account.address
);
}
});
}

}, [tonConnectUI]);
```


You can find `ton_proof` result in the `wallet` object when wallet will be connected:
#### Structure of ton_proof

```ts
import {useTonConnectUI} from "@tonconnect/ui-react";

const [tonConnectUI] = useTonConnectUI();

useEffect(() =>
tonConnectUI.onStatusChange(wallet => {
if (wallet.connectItems?.tonProof && 'proof' in wallet.connectItems.tonProof) {
checkProofInYourBackend(wallet.connectItems.tonProof.proof, wallet.account);
}
}), []);
type TonProofItemReplySuccess = {
name: "ton_proof";
proof: {
timestamp: string; // Unix epoch time (seconds)
domain: {
lengthBytes: number; // Domain length
value: string; // Domain name
};
signature: string; // Base64-encoded signature
payload: string; // Payload from the request
}
}
```

You can find an example of authentication on this [page](/develop/dapps/ton-connect/sign#react-example)

### Wallet Disconnection

Call to disconnect the wallet:
```js
import { useTonConnectUI } from '@tonconnect/ui-react';

const [tonConnectUI] = useTonConnectUI();

await tonConnectUI.disconnect();
Expand Down
Loading