npm package: @okxconnect/tonui-react
Description: ## Installation via npm
Author: OKX Wallet
Latest version: 1.9.1

## React UI components

## Installation via npm

`npm install @okxconnect/tonui-react`

## Add OKXTonConnectUIProvider
Add OKXTonConnectUIProvider to the root directory of your application. You can specify UI options using props.
All OKXConnectUI hooks calls and `<OKXTonConnectButton />` components should be placed inside `<OKXTonConnectUIProvider>`.

```tsx
import { OKXTonConnectUIProvider } from '@okxconnect/tonui-react';

export function App() {
    return (
        <OKXTonConnectUIProvider
            uiPreferences = {{theme: THEME.DARK}}
            dappMetaData = {{
                name: "application name",
                icon: "application url"
            }}
            restoreConnection = {true}
            language = {'zh_CN'}
            actionsConfiguration = {{returnStrategy:"tg://resolve",tmaReturnUrl:'back'}}
        >
            { /* Your app */}
        </OKXTonConnectUIProvider>
    );
}

```

## Add OKXTonConnectButton
The TonConnect button is a generic UI component used to initialise the connection. After the wallet is connected, it converts to the wallet menu. It is recommended to place it in the top right corner of the application.

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

## Connecting to a wallet
Connecting to a wallet goes to get the wallet address, which serves as the identifier and the necessary parameters used to sign the transaction.
The ‘Connect Button’ (added to buttonRootId) automatically handles the click and invokes the connection.
If no buttonRootId is added, this method needs to be called.

`await okxTonConnectUI.openModal();`

**Example**

```typescript
const [okxTonConnectUI, setOptions] = useOKXTonConnectUI();
await okxTonConnectUI.openModal();
```

## Monitoring wallet status changes

Wallet statuses are: successful connection, successful restoration of connection, disconnection, etc. You can use this method to get the status.
[Method details same as OKXTonConnect.onStatusChange](https://www.okx.com/web3/build/docs/sdks/app-connect-ton#%E7%9B%91%E5%90%AC%E9%92%B1%E5%8C%85% e7%8a%b6%e6%80%81%e5%8f%98%e5%8c%96)

**Example**

```typescript
const [okxTonConnectUI, setOptions] = useOKXTonConnectUI();
okxTonConnectUI.onStatusChange((value: ConnectedWallet | null) => {
    //
});
```

## Get the currently connected wallet address
Use this to get the user's current ton wallet address. Pass the boolean parameter isUserFriendly to select the format of the address. If the wallet is not connected, an empty string will be returned.
```tsx
import { useTonAddress } from '@okxconnect/tonui-react';

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

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

### Get currently connected wallet
Use this to get the user's current ton wallet. If the wallet is not connected, null is returned.

```tsx
import { useOKXTonWallet } from '@okxconnect/tonui-react';

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

    return (
        wallet && (
            <div>
                <span>Connected wallet: {wallet.name}</span>
                <span>Device: {wallet.device.appName}</span>
            </div>
        )
    );
};
```

### useTonConnectUI
Use it to access OKXTonConnectUI instances and UI option update features

```tsx
import { Locales, useOKXTonConnectUI } from '@okxconnect/tonui-react';

export const Settings = () => {
    const [okxTonConnectUI, setOptions] = useOKXTonConnectUI();

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

    const myTransaction = {
        validUntil: Math.floor(Date.now() / 1000) + 60, // 60 sec
        messages: [
            {
                address: "EQBBJBB3HagsujBqVfqeDUPJ0kXjgTPLWPFFffuNXNiJL0aA",
                amount: "10000000",
                // stateInit: "base64bocblahblahblah==" // just for instance. Replace with your transaction initState or remove
            },
            {
                address: "EQDmnxDMhId6v1Ofg_h5KR5coWlFG6e86Ro3pc7Tq4CA0-Jn",
                amount: "60000000",
                // payload: "base64bocblahblahblah==" // just for instance. Replace with your transaction payload or remove
            }
        ]
    }

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

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

### Whether the connection has been restored
Displays the status of the connection recovery process.

```tsx
import { useIsConnectionRestored } from '@okxconnect/tonui-react';

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

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

    return <MainPage />;
};
```

## Add connection request parameters (ton_proof)
Use the OKXTonConnectUI.setConnectRequestParameters function to pass the connection request parameters (ton_proof).
If you need to set tonProof, set state:‘loading’, before preparing the tonProof parameter.
When ready, set state to ‘ready’ and add value;.
The loading state can also be removed by setting setConnectRequestParameters(null);


```ts
const [okxtonConnectUI] = useOKXTonConnectUI();

okxtonConnectUI.setConnectRequestParameters({ state: 'loading' });

const tonProofPayload: string | null = await fetchTonProofPayloadFromBackend();

if (!tonProofPayload) {
    okxtonConnectUI.setConnectRequestParameters(null);
} else {
    okxtonConnectUI.setConnectRequestParameters({
        state: "ready",
        value: { tonProof: tonProof }
    });
}

```