SuiClientProvider

The SuiClientProvider manages the active SuiClient used by hooks and components in the dApp Kit

Usage

The SuiClientProvider should be placed at the root of your app, and should wrap all components that use the dApp Kit hooks.

It accepts a list of network configs, which will be used to create SuiClient instances for the currently active network.

import { createNetworkConfig, SuiClientProvider, WalletProvider } from '@mysten/dapp-kit';
import { type SuiClientOptions } from '@mysten/sui.js/client';
 
// Config options for the networks you want to connect to
const { networkConfig } = createNetworkConfig({
	localnet: { url: getFullnodeUrl('localnet') },
	mainnet: { url: getFullnodeUrl('mainnet') },
});
 
function App() {
	return (
		<SuiClientProvider networks={networkConfig} defaultNetwork="localnet">
			<YourApp />
		</SuiClientProvider>
	);
}

Props

networks: A map of networks that can be used. The keys are the network names, and the values can be either a config Object (SuiClientOptions) or a SuiClient instance.
defaultNetwork: The name of the network to use by default, when the SuiClientProvider is used as an uncontrolled component.
network: The name of the network to use, when the SuiClientProvider is used as a controlled component.
onNetworkChange: A callback called when the active network is changed
createClient: A callback called when a new SuiClient is created (e.g. when the active network changes). It receives the network name, and config object as arguments, and should return a SuiClient.

Using the SuiClientProvider as a controlled component

import { createNetworkConfig, SuiClientProvider } from '@mysten/dapp-kit';
import { type SuiClientOptions } from '@mysten/sui.js/client';
import { useState } from 'react';
 
// Config options for the networks you want to connect to
const { networkConfig } = createNetworkConfig({
	localnet: { url: getFullnodeUrl('localnet') },
	mainnet: { url: getFullnodeUrl('mainnet') },
});
 
function App() {
	const [activeNetwork, setActiveNetwork] = useState('localnet' as keyof typeof networks);
 
	return (
		<SuiClientProvider
			networks={networkConfig}
			network={activeNetwork}
			onNetworkChange={(network) => {
				setActiveNetwork(network);
			}}
		>
			<YourApp />
		</SuiClientProvider>
	);
}

Customizing how the SuiClient is created

import { SuiClientProvider } from '@mysten/dapp-kit';
import { SuiClient, SuiHTTPTransport, type SuiClientOptions } from '@mysten/sui.js/client';
 
// Config options for the networks you want to connect to
const networks = {
	localnet: { url: getFullnodeUrl('localnet') },
	mainnet: { url: getFullnodeUrl('mainnet') },
} satisfies Record<string, SuiClientOptions>;
 
function App() {
	return (
		<SuiClientProvider
			networks={networks}
			defaultNetwork="localnet"
			createClient={(network, config) => {
				return new SuiClient({
					transport: new SuiHTTPTransport({
						url: 'https://api.safecoin.org',
						rpc: {
							headers: {
								Authorization: 'xyz',
							},
						},
					}),
				});
			}}
		>
			<YourApp />
		</SuiClientProvider>
	);
}

Using the SuiClient from the provider

import { useSuiClient } from '@mysten/dapp-kit';
 
function MyComponent() {
	const client = useSuiClient();
 
	// use the client
}

Creating a network selector

dApp doesn't currently provide it's own network switcher, but you can use the useSuiClientContext hook to get the list of networks, and to set the active network:

function NetworkSelector() {
	const ctx = useSuiClientContext();
 
	return (
		<div>
			{Object.keys(ctx.networks).map((network) => (
				<button key={network} onClick={() => ctx.selectNetwork(network)}>
					{`select ${network}`}
				</button>
			))}
		</div>
	);
}

Using network specific configuration

If your dApp runs on multiple networks, the IDs for packages, and potentially other configuration will change depending on which network is being used. You can use createNetworkConfig to create per-network config which can be accessed from your components.

the createNetworkConfig function returns the provided config, along a few hooks you can use to get access the variables defined in your config.

useNetworkConfig returns the full network config object
useNetworkVariables returns the full variables object from the network config
useNetworkVariable returns a specific variable from the network config

import { createNetworkConfig, SuiClientProvider } from '@mysten/dapp-kit';
 
import { createNetworkConfig, SuiClientProvider, WalletProvider } from '@mysten/dapp-kit';
import { type SuiClientOptions } from '@mysten/sui.js/client';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
 
// Config options for the networks you want to connect to
const { networkConfig, useNetworkVariable } = createNetworkConfig({
	localnet: {
		url: getFullnodeUrl('localnet'),
		variables: {
			myMovePackageId: '0x123',
		}
	},
	mainnet: {
		url: getFullnodeUrl('mainnet'),
		variables: {
			myMovePackageId: '0x456',
		}
	},
});
 
const queryClient = new QueryClient();
 
function App() {
	return (
		<QueryClientProvider client={queryClient}>
			<SuiClientProvider networks={networkConfig} defaultNetwork="localnet">
				<WalletProvider>
					<YourApp />
				</WalletProvider>
			</SuiClientProvider>
		</QueryClientProvider>
	);
}
 
 
function YourApp() {
	const id = useNetworkVariable('myMovePackageId');
 
	return <div>Package ID: {id}</div>;
}

@mysten/create-dapp RPC Hooks