@mysten/dapp-kit-react 2.0.2 → 2.1.0

package/docs/index.md

@@ -0,0 +1,70 @@
+# Sui dApp Kit
+
+> Build Sui apps with framework-agnostic core and React bindings.
+
+> **Note:** **Migrating from @mysten/dapp-kit?** If you're currently using the legacy `@mysten/dapp-kit`
+> package, check out our [Migration Guide](/sui/migrations/sui-2.0/dapp-kit) to upgrade to the new
+> packages with gRPC and GraphQL support.
+
+The Sui dApp Kit provides tools and components for building decentralized applications on the Sui
+network. The SDK consists of two packages that work together:
+
+## Packages
+
+### @mysten/dapp-kit-core
+
+Framework-agnostic core that works with vanilla JS, React, Vue, or any framework:
+
+- Action-based API for direct wallet operations
+- Web Components for universal UI elements
+- Automatic state management with nanostores
+- Smaller bundle size and improved performance
+
+### @mysten/dapp-kit-react
+
+React bindings for the core package:
+
+- React hooks for state and actions
+- React component wrappers for Web Components
+- Seamless integration with React applications
+
+## Install
+
+Choose the installation method based on your framework:
+
+### For React applications
+
+```npm
+npm i @mysten/dapp-kit-react @mysten/sui
+```
+
+### Vanilla JavaScript and other frameworks
+
+```npm
+npm i @mysten/dapp-kit-core @mysten/sui
+```
+
+## Getting started
+
+Check the framework-specific guides:
+
+- [React](/dapp-kit/getting-started/react)
+- [Next.js](/dapp-kit/getting-started/next-js)
+- [Vue](/dapp-kit/getting-started/vue)
+
+## Legacy package
+
+### @mysten/dapp-kit (Legacy)
+
+See the [Legacy dApp Kit documentation](/dapp-kit/legacy).
+
+The original React-focused version of the dApp Kit. This package provides:
+
+- React hooks for wallet connection and blockchain queries
+- Pre-built UI components with Radix UI
+- Integration with TanStack React Query
+- Comprehensive wallet state management
+
+> **Warning:** **Deprecated JSON RPC Only**: This legacy package only works with the deprecated JSON RPC API and
+> will not be updated to support gRPC or GraphQL. All new projects should use
+> `@mysten/dapp-kit-core` and `@mysten/dapp-kit-react`.

package/docs/llms-index.md

@@ -0,0 +1,33 @@
+# dApp Kit
+> Build Sui dApps with @mysten/dapp-kit-core and @mysten/dapp-kit-react
+
+- [Sui dApp Kit](..md): Build Sui apps with framework-agnostic core and React bindings.
+- [@mysten/create-dapp](./getting-started/create-dapp.md): Create a Sui app with one command using the create-dapp CLI scaffolding tool.
+- [React](./getting-started/react.md): Set up dApp Kit in a React application.
+- [Next.js](./getting-started/next-js.md): Set up dApp Kit in a Next.js application.
+- [Vue](./getting-started/vue.md): Set up dApp Kit in a Vue application.
+- [DApp Kit Instance](./dapp-kit-instance.md): Create and configure a DAppKit instance for wallet and client management
+- [State](./state.md): Access and subscribe to wallet connection state in dApp Kit.
+- [Connect Wallet](./actions/connect-wallet.md): Programmatically connect to a Sui wallet using the dApp Kit connectWallet action.
+- [Disconnect Wallet](./actions/disconnect-wallet.md): Programmatically disconnect from a Sui wallet using the dApp Kit disconnectWallet action.
+- [Sign and Execute Transaction](./actions/sign-and-execute-transaction.md): Sign and execute a transaction on the Sui network using the connected wallet.
+- [Sign Personal Message](./actions/sign-personal-message.md): Sign an arbitrary message with the connected wallet for authentication or proof of ownership.
+- [Sign Transaction](./actions/sign-transaction.md): Sign a Sui transaction without executing it for deferred or multi-signature scenarios.
+- [Switch Account](./actions/switch-account.md): Switch the active account in the connected wallet using the dApp Kit switchAccount action.
+- [Switch Network](./actions/switch-network.md): Switch the active network for the dApp Kit instance between mainnet, testnet, and other networks.
+- [DAppKitProvider](./react/dapp-kit-provider.md): React context provider that makes dApp Kit available throughout your application.
+- [React Hooks](./react/hooks.md): React hooks for accessing dApp Kit state and actions in Sui applications.
+- [useDAppKit](./react/hooks/use-dapp-kit.md): React hook to access the full dApp Kit instance for calling actions directly.
+- [useCurrentAccount](./react/hooks/use-current-account.md): React hook to get the currently selected wallet account in a Sui dApp.
+- [useCurrentClient](./react/hooks/use-current-client.md): React hook to get the current Sui client instance for the active network.
+- [useCurrentNetwork](./react/hooks/use-current-network.md): React hook to get the currently selected Sui network in dApp Kit.
+- [useCurrentWallet](./react/hooks/use-current-wallet.md): React hook to get the currently connected wallet in a Sui dApp.
+- [useWalletConnection](./react/hooks/use-wallet-connection.md): React hook to manage wallet connection status and information in a Sui dApp.
+- [useWallets](./react/hooks/use-wallets.md): React hook to list all available Sui wallets detected by dApp Kit.
+- [React Components](./react/components.md): Pre-built React UI components for wallet interaction in Sui dApps.
+- [Connect Button](./react/components/connect-button.md): React button component for connecting and disconnecting Sui wallets.
+- [Connect Modal](./react/components/connect-modal.md): React modal component for selecting and connecting to a Sui wallet.
+- [Connect Button](./web-components/connect-button.md): Framework-agnostic web component providing a complete wallet connection UI for Sui dApps.
+- [Connect Modal](./web-components/connect-modal.md): Framework-agnostic web component for wallet selection and connection in Sui dApps.
+- [Theming](./theming.md): Customize the appearance of dApp Kit UI components.
+- [Sui dApp Kit (Legacy)](./legacy.md): Legacy dApp Kit API reference for the deprecated @mysten/dapp-kit package using JSON RPC.

package/docs/react/components/connect-button.md

@@ -0,0 +1,42 @@
+# Connect Button
+
+> React button component for connecting and disconnecting Sui wallets.
+
+## Usage
+
+```tsx
+<ConnectButton
+	modalOptions={{
+		filterFn: (wallet) => wallet.name !== 'Excluded Wallet',
+		sortFn: (a, b) => a.name.localeCompare(b.name),
+	}}
+/>
+```
+
+> Auto-connect is enabled by default and will attempt to restore the previous wallet connection on
+> page reload. This provides a seamless user experience but can be
+> [disabled](/dapp-kit/dapp-kit-instance#disabling-auto-connect) if needed.
+
+## Props
+
+- **instance** (optional) - dApp Kit instance. If not provided, uses the instance from context.
+- **modalOptions** (optional) - Configuration options for the connect modal
+  - **filterFn** (optional) - Function to filter available wallets
+    - Type: `(wallet: UiWallet, index: number, array: UiWallet[]) => boolean`
+  - **sortFn** (optional) - Function to sort available wallets
+    - Type: `(a: UiWallet, b: UiWallet) => number`
+
+## Custom button text
+
+Use the slot to customize the button content when disconnected:
+
+```tsx
+<ConnectButton>
+	<span>🔗 Link Wallet</span>
+</ConnectButton>
+```
+
+## Server-side rendering (SSR)
+
+The `<ConnectButton />` component can be only client-side rendered, as wallets are detected in the
+browser. For Next.js guide see [here](/dapp-kit/getting-started/next-js).

package/docs/react/components/connect-modal.md

@@ -0,0 +1,51 @@
+# Connect Modal
+
+> React modal component for selecting and connecting to a Sui wallet.
+
+## Usage
+
+```tsx
+
+	const [open, setOpen] = useState(false);
+	return (
+		<>
+			<button onClick={() => setOpen(true)}>Connect Wallet</button>
+			<ConnectModal open={open} />
+		</>
+	);
+}
+```
+
+## Props
+
+- **open** (optional) - Boolean to control modal visibility. If not provided, the modal can be
+  controlled by calling `show()` and `close()` methods directly on the component ref.
+- **instance** (optional) - dApp Kit instance. If not provided, uses the instance from context
+- **filterFn** (optional) - Function to filter available wallets
+  - Type: `(wallet: UiWallet, index: number, array: UiWallet[]) => boolean`
+- **sortFn** (optional) - Function to sort available wallets
+  - Type: `(a: UiWallet, b: UiWallet) => number`
+
+### Example
+
+```tsx
+<ConnectModal
+	open={open}
+	filterFn={(wallet) => wallet.name !== 'ExcludedWallet'}
+	sortFn={(a, b) => a.name.localeCompare(b.name)}
+/>
+```
+
+## Modal states
+
+The modal displays different views based on connection status:
+
+- **Wallet Selection**: Shows available wallets to choose from
+- **Connecting**: Displays loading state while connecting to selected wallet
+- **Error**: Shows error message with retry option when connection fails
+- **Request Cancelled**: Appears when user cancels the wallet connection request
+
+## Server-side rendering (SSR)
+
+The `<ConnectModal />` component can be only client-side rendered, as wallets are detected in the
+browser. For Next.js guide see [here](/dapp-kit/getting-started/next-js).

package/docs/react/components/index.md

@@ -0,0 +1,13 @@
+# React Components
+
+> Pre-built React UI components for wallet interaction in Sui dApps.
+
+The `@mysten/dapp-kit-react` package provides pre-built React components for common wallet
+interactions.
+
+## Available components
+
+- [`ConnectButton`](/dapp-kit/react/components/connect-button) - A button that opens the wallet
+  connection modal and displays account info when connected
+- [`ConnectModal`](/dapp-kit/react/components/connect-modal) - A modal dialog for selecting and
+  connecting to a wallet

package/docs/react/dapp-kit-provider.md

@@ -0,0 +1,86 @@
+# DAppKitProvider
+
+> React context provider that makes dApp Kit available throughout your application.
+
+The `DAppKitProvider` is a React context provider that makes your dApp Kit instance available
+throughout your React application. It must wrap any components that use dApp Kit hooks.
+
+## Basic usage
+
+```tsx
+
+	return (
+		<DAppKitProvider dAppKit={dAppKit}>
+			<YourApp />
+		</DAppKitProvider>
+	);
+}
+```
+
+## Props
+
+- **dAppKit**: The dApp Kit instance created with `createDAppKit`
+
+## Provider setup patterns
+
+### With custom configuration
+
+```tsx
+
+const GRPC_URLS = {
+	testnet: 'https://fullnode.testnet.sui.io:443',
+} as const;
+
+const dAppKit = createDAppKit({
+	networks: ['testnet'],
+	createClient: (network) => new SuiGrpcClient({ network, baseUrl: GRPC_URLS[network] }),
+	autoConnect: true,
+	storage: localStorage,
+	storageKey: 'myapp_dappkit',
+});
+
+// global type registration necessary for the hooks to work correctly
+declare module '@mysten/dapp-kit-react' {
+	interface Register {
+		dAppKit: typeof dAppKit;
+	}
+}
+
+	return (
+		<DAppKitProvider dAppKit={dAppKit}>
+			<YourApp />
+		</DAppKitProvider>
+	);
+}
+```
+
+## Using hooks inside the provider
+
+Once your app is wrapped with `DAppKitProvider`, you can use any dApp Kit hooks in child components:
+
+```tsx
+
+	const dAppKit = useDAppKit();
+	const account = useCurrentAccount();
+	const network = useCurrentNetwork();
+	const handleConnect = async () => {
+		await dAppKit.connectWallet({ wallet });
+	};
+	return (
+		<div>
+			<p>Network: {network}</p>
+			<p>Account: {account?.address}</p>
+			<button onClick={handleConnect}>Connect</button>
+		</div>
+	);
+}
+```
+
+> All dApp Kit hooks must be used within components that are descendants of `DAppKitProvider`. Using
+> them outside will result in an error.
+
+## Server-side rendering (SSR)
+
+While `DAppKitProvider` itself is SSR-safe, components that interact with wallets should be
+client-side rendered, as wallets are detected in the browser. For Next.js guide see
+[here](/dapp-kit/getting-started/next-js).

package/docs/react/hooks/index.md

@@ -0,0 +1,26 @@
+# React Hooks
+
+> React hooks for accessing dApp Kit state and actions in Sui applications.
+
+The `@mysten/dapp-kit-react` package provides a set of hooks for interacting with wallets and the
+Sui blockchain in React applications.
+
+> **Warning:** All dApp Kit hooks must be used within components that are descendants of
+> [`DAppKitProvider`](/dapp-kit/react/dapp-kit-provider). Using them outside will result in an
+> error.
+
+## Available hooks
+
+- [`useDAppKit`](/dapp-kit/react/hooks/use-dapp-kit) - Access the dApp Kit instance for calling
+  actions directly
+- [`useCurrentAccount`](/dapp-kit/react/hooks/use-current-account) - Get the currently selected
+  account
+- [`useCurrentClient`](/dapp-kit/react/hooks/use-current-client) - Get the blockchain client for the
+  current network
+- [`useCurrentNetwork`](/dapp-kit/react/hooks/use-current-network) - Get the currently selected
+  network
+- [`useCurrentWallet`](/dapp-kit/react/hooks/use-current-wallet) - Get the currently connected
+  wallet
+- [`useWalletConnection`](/dapp-kit/react/hooks/use-wallet-connection) - Get wallet connection
+  status and actions
+- [`useWallets`](/dapp-kit/react/hooks/use-wallets) - Get all available wallets

package/docs/react/hooks/use-current-account.md

@@ -0,0 +1,33 @@
+# useCurrentAccount
+
+> React hook to get the currently selected wallet account in a Sui dApp.
+
+The `useCurrentAccount` hook provides access to the currently selected account.
+
+> **Warning:** All dApp Kit hooks must be used within components that are descendants of
+> [`DAppKitProvider`](../dapp-kit-provider). Using them outside will result in an error.
+
+## Usage
+
+```tsx
+
+	const account = useCurrentAccount();
+
+	if (!account) {
+		return <div>No account selected</div>;
+	}
+
+	return (
+		<div>
+			<p>Address: {account.address}</p>
+			<p>Label: {account.label}</p>
+		</div>
+	);
+}
+```
+
+## Return value
+
+```tsx
+UiWalletAccount | null;
+```

package/docs/react/hooks/use-current-client.md

@@ -0,0 +1,36 @@
+# useCurrentClient
+
+> React hook to get the current Sui client instance for the active network.
+
+The `useCurrentClient` hook provides access to the blockchain client instance for the current
+network.
+
+> **Note:** By default, this returns a `SuiClient` instance when using the standard setup. However, the dApp
+> Kit supports any client that implements the Sui core API, making it flexible for different
+> blockchain implementations.
+
+> **Warning:** All dApp Kit hooks must be used within components that are descendants of
+> [`DAppKitProvider`](../dapp-kit-provider). Using them outside will result in an error.
+
+## Usage
+
+```tsx
+
+	const client = useCurrentClient();
+
+	const handleQuery = async () => {
+		const balance = await client.getBalance({
+			owner: '0x...',
+		});
+		console.log(balance);
+	};
+
+	return <button onClick={handleQuery}>Check Balance</button>;
+}
+```
+
+## Return value
+
+```tsx
+SuiClient;
+```

package/docs/react/hooks/use-current-network.md

@@ -0,0 +1,28 @@
+# useCurrentNetwork
+
+> React hook to get the currently selected Sui network in dApp Kit.
+
+The `useCurrentNetwork` hook provides access to the currently selected network.
+
+> **Warning:** All dApp Kit hooks must be used within components that are descendants of
+> [`DAppKitProvider`](../dapp-kit-provider). Using them outside will result in an error.
+
+## Usage
+
+```tsx
+
+	const network = useCurrentNetwork();
+
+	return (
+		<div>
+			<p>Current network: {network}</p>
+		</div>
+	);
+}
+```
+
+## Return value
+
+```tsx
+string;
+```

package/docs/react/hooks/use-current-wallet.md

@@ -0,0 +1,36 @@
+# useCurrentWallet
+
+> React hook to get the currently connected wallet in a Sui dApp.
+
+The `useCurrentWallet` hook provides access to the currently connected wallet.
+
+> **Warning:** All dApp Kit hooks must be used within components that are descendants of
+> [`DAppKitProvider`](../dapp-kit-provider). Using them outside will result in an error.
+
+## Usage
+
+```tsx
+
+	const wallet = useCurrentWallet();
+
+	if (!wallet) {
+		return <div>No wallet connected</div>;
+	}
+
+	return (
+		<div>
+			<p>Wallet: {wallet.name}</p>
+			<p>
+				Icon: <img src={wallet.icon} alt={wallet.name} />
+			</p>
+			<p>Accounts: {wallet.accounts.length}</p>
+		</div>
+	);
+}
+```
+
+## Return value
+
+```tsx
+UiWallet | null;
+```

package/docs/react/hooks/use-dapp-kit.md

@@ -0,0 +1,100 @@
+# useDAppKit
+
+> React hook to access the full dApp Kit instance for calling actions directly.
+
+The `useDAppKit` hook provides direct access to the dApp Kit instance within React components,
+enabling you to call actions and access the underlying functionality.
+
+> **Warning:** All dApp Kit hooks must be used within components that are descendants of
+> [`DAppKitProvider`](../dapp-kit-provider). Using them outside will result in an error.
+
+## Usage
+
+```tsx
+
+	const dAppKit = useDAppKit();
+
+	async function handleConnect() {
+		try {
+			await dAppKit.connectWallet({ wallet });
+			console.log('Connected successfully');
+		} catch (error) {
+			console.error('Connection failed:', error);
+		}
+	}
+
+	return <button onClick={handleConnect}>Connect Wallet</button>;
+}
+```
+
+## Return value
+
+```ts
+{
+    // Actions
+    connectWallet: (args: { wallet: UiWallet; account?: UiWalletAccount }) => Promise<{ accounts: UiWalletAccount[]; }>;
+    disconnectWallet: () => Promise<void>;
+    switchAccount: (args: { account: UiWalletAccount }) => Promise<void>;
+    switchNetwork: (network: string) => void;
+    signTransaction: (args: { transaction: Transaction | string; signal?: AbortSignal }) => Promise<SignedTransaction>;
+    signAndExecuteTransaction: (args: { transaction: Transaction | string; signal?: AbortSignal }) => Promise<TransactionResult>;
+    signPersonalMessage: (args: { message: Uint8Array }) => Promise<SignedPersonalMessage>;
+
+    // Properties
+    networks: string[];
+    stores:  {
+        $wallets: DAppKitStores['$compatibleWallets'];
+        $connection: DAppKitStores['$connection'];
+        $currentNetwork: ReadableAtom<TNetworks[number]>;
+        $currentClient: ReadableAtom<Client>;
+    };
+    getClient: (network?: string) => Client;
+}
+```
+
+## Examples
+
+### Transaction execution
+
+```tsx
+
+	const dAppKit = useDAppKit();
+
+	async function handleTransfer() {
+		const tx = new Transaction();
+		tx.transferObjects([tx.object('0x123...')], '0xrecipient...');
+
+		try {
+			const result = await dAppKit.signAndExecuteTransaction({
+				transaction: tx,
+			});
+
+			if (result.FailedTransaction) {
+				throw new Error(`Transaction failed: ${result.FailedTransaction.status.error?.message}`);
+			}
+
+			console.log('Transaction digest:', result.Transaction.digest);
+		} catch (error) {
+			console.error('Transaction failed:', error);
+		}
+	}
+
+	return <button onClick={handleTransfer}>Transfer</button>;
+}
+```
+
+### Subscribing to state changes
+
+```tsx
+
+	const dAppKit = useDAppKit();
+	useEffect(() => {
+		// Subscribe directly to connection store changes
+		const unsubscribe = dAppKit.stores.$connection.subscribe((connection) => {
+			console.log('Connection status:', connection.status);
+		});
+		return unsubscribe;
+	}, [dAppKit]);
+	return null;
+}
+```

package/docs/react/hooks/use-wallet-connection.md

@@ -0,0 +1,48 @@
+# useWalletConnection
+
+> React hook to manage wallet connection status and information in a Sui dApp.
+
+The `useWalletConnection` hook provides access to the current wallet connection status and
+information.
+
+> **Warning:** All dApp Kit hooks must be used within components that are descendants of
+> [`DAppKitProvider`](../dapp-kit-provider). Using them outside will result in an error.
+
+## Usage
+
+```tsx
+
+	const connection = useWalletConnection();
+
+	if (connection.status === 'disconnected') {
+		return <div>Please connect your wallet</div>;
+	}
+
+	if (connection.status === 'connecting') {
+		return <div>Connecting...</div>;
+	}
+
+	// status === 'connected'
+	return (
+		<div>
+			<p>Connected to: {connection.wallet.name}</p>
+			<p>Address: {connection.account.address}</p>
+		</div>
+	);
+}
+```
+
+## Return value
+
+```tsx
+{
+	status: 'disconnected' | 'connecting' | 'reconnecting' | 'connected';
+	wallet: UiWallet | null;
+	account: UiWalletAccount | null;
+	supportedIntents: string[];
+	isConnected: boolean;
+	isConnecting: boolean;
+	isReconnecting: boolean;
+	isDisconnected: boolean;
+}
+```

package/docs/react/hooks/use-wallets.md

@@ -0,0 +1,33 @@
+# useWallets
+
+> React hook to list all available Sui wallets detected by dApp Kit.
+
+The `useWallets` hook provides access to all available wallets.
+
+> **Warning:** All dApp Kit hooks must be used within components that are descendants of
+> [`DAppKitProvider`](../dapp-kit-provider). Using them outside will result in an error.
+
+## Usage
+
+```tsx
+
+	const wallets = useWallets();
+
+	return (
+		<div>
+			{wallets.map((wallet) => (
+				<div key={wallet.name}>
+					<img src={wallet.icon} alt={wallet.name} />
+					<span>{wallet.name}</span>
+				</div>
+			))}
+		</div>
+	);
+}
+```
+
+## Return value
+
+```tsx
+UiWallet[]
+```