> For the complete documentation index, see [llms.txt](https://docs.megaeth.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.megaeth.com/moss-docs/react-sdk/ux-guidance.md).
# UX Guidance
React-specific patterns for wallet UX. For general wallet UX rules (cancellation handling, error states, copy conventions), see [Best Practices](/moss-docs/wallet/best-practices.md).
## Separate Boot from Connection
Use `useStatus().initialised` to distinguish "the wallet SDK is still initialising" from "the wallet is initialised but no user is connected." A `Connect` button rendered before the provider has initialised can feel broken — the click does nothing useful.
```tsx
const { initialised, status } = useStatus();
if (!initialised) return ;
if (status === 'disconnected') return ;
return ;
```
## Drive Mutations from Explicit User Action
Mutation hooks (`useConnect`, `useTransfer`, `useSignMessage`, etc.) should fire from button clicks or other intentional user actions — never on mount or in render. Use `isPending` for the in-flight state and `onSuccess` / `onError` callbacks for the outcome. Keep app context intact on cancellation so the user can retry without losing state.
## Gate Queries on Connected State
`useBalances` and `usePermissions` already check connection status internally and skip the fetch when disconnected. Apply the same gating logic to your own data — don't render balance or permission panels in a layout that implies data should exist before the user has connected.
## Mount the Provider Once, at a Stable Boundary
Mount `MegaProvider` at the durable shell of your app (root layout, top-level provider tree). Recreating it on route transitions causes the iframe to remount, the Penpal bridge to re-handshake, and React Query state to reset — all avoidable churn.
```tsx
// app/layout.tsx
import { MegaProvider } from '@megaeth-labs/wallet-sdk-react';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
);
}
```
If you need different configs on different routes, prefer config that changes via React state inside one provider over remounting the provider with a different config.
## Copy Conventions
For account onboarding, prefer "Creating your account" and "Restoring account" — see [Best Practices > Account recovery wording](/moss-docs/core-sdk/error-handling.md#account-recovery-wording) for the full guidance.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.megaeth.com/moss-docs/react-sdk/ux-guidance.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.