Wallet flows

Wallet Connection

The wallet layer covers both the first-touch connection flow and the post-connection surfaces you need after auth: connected wallet state, network switching, and gated product areas.

Provider stack requiredConnection + gatingMulti-wallet support

Supported wallets

Core, MetaMask, Coinbase, WalletConnect, Ledger

Use a single connection model while keeping wallet-specific behavior behind the scenes.

Best for

Onboarding and gated product flows

Connect, inspect wallet state, switch chains, and conditionally reveal protected UI.

Required providers

AvaCloudKitProvider + wallet providers

Wallet-specific state layers sit inside AvaCloudKitProvider.

Connection controls

Use ConnectWalletButton and ConnectedWallet for the primary entry and post-connect state.

Network-sensitive UX

Pair ChainSelect with addChainToWallet and ConnectedNetworkGate when specific chains matter.

Guarded experiences

ConnectedWalletGate and ConnectedNetworkGate help you explain why a surface is unavailable.

Prerequisites

Wallet components require the AvaCloudKitProvider context (which includes WagmiProvider) plus the wallet-specific providers.

Quick Start

Wrap your app with the wallet providers inside AvaCloudKitProvider:

import {
  AvaCloudKitProvider,
  SelectedWalletProvider,
  ConnectWalletProvider,
} from '@avalabs/avacloud-kit-ui-preview';

function App() {
  return (
    <AvaCloudKitProvider value={{ appName: 'MyApp' }}>
      <SelectedWalletProvider>
        <ConnectWalletProvider>
          <YourApp />
        </ConnectWalletProvider>
      </SelectedWalletProvider>
    </AvaCloudKitProvider>
  );
}

Connect Wallet Button

Opens a dialog for wallet selection:

Connected: Loading...

Detecting wallets...

import { ConnectWalletButton } from '@avalabs/avacloud-kit-ui-preview';

function Example() {
  return <ConnectWalletButton />;
}

Connected Wallet Display

Shows the connected wallet with a dropdown for account details and disconnect:

Connected: Loading...

Detecting wallets...

import { ConnectedWallet } from '@avalabs/avacloud-kit-ui-preview';

function Example() {
  return <ConnectedWallet />;
}

Full Example

Conditionally render connect button or connected wallet based on connection state:

Connected: Loading...

Detecting wallets...

import {
  ConnectWalletButton,
  ConnectedWallet,
  dappService,
} from '@avalabs/avacloud-kit-ui-preview';

function WalletSection() {
  const { isConnected } = dappService.useAccount();

  return isConnected ? <ConnectedWallet /> : <ConnectWalletButton />;
}

Chain Switcher Demo

Use ChainSelect to choose a target chain and switch your connected wallet network. The current connected network is shown live.

Current network: Not connected

import {
  Button,
  ChainSelect,
  addChainToWallet,
  chainsService,
  dappService,
  useAppChainsContext,
} from '@avalabs/avacloud-kit-ui-preview';

function NetworkSwitcher() {
  const { chain, isConnected, provider } = dappService.useAccount();
  const { findChainByEvmChainId } = useAppChainsContext();
  const [selectedChainId, setSelectedChainId] = useState('43114');
  const isProviderReady = Boolean(provider?.request);

  const handleSwitch = async () => {
    const selectedChain = findChainByEvmChainId(selectedChainId as any);
    if (!selectedChain || !chainsService.isEvm(selectedChain)) return;
    await addChainToWallet({
      chain: selectedChain,
      provider,
    });
  };

  return (
    <>
      <div>Current network: {chain ? `${chain.name} (${chain.id})` : 'Not connected'}</div>
      <ChainSelect selectedChainId={selectedChainId} onSelect={setSelectedChainId} disabled={!isConnected || !isProviderReady} />
      <Button onClick={handleSwitch} disabled={!isConnected || !isProviderReady}>
        {isProviderReady ? 'Switch Selected Network' : 'Preparing wallet...'}
      </Button>
    </>
  );
}

Connected Wallet Gate

A wrapper component that shows its children only when a wallet is connected. When disconnected, it displays a prompt with a connect button.

Please connect your wallet to use Staking

import { ConnectedWalletGate } from '@avalabs/avacloud-kit-ui-preview';

function ProtectedFeature() {
  return (
    <ConnectedWalletGate featureName="Staking">
      <StakingContent />
    </ConnectedWalletGate>
  );
}

With Card Wrapper

By default, the gate wraps disconnected content in a Card. Set withCard={false} to disable:

Please connect your wallet to use Dashboard

// With card (default)
<ConnectedWalletGate featureName="Dashboard">
  <DashboardContent />
</ConnectedWalletGate>

// Without card
<ConnectedWalletGate featureName="Dashboard" withCard={false}>
  <DashboardContent />
</ConnectedWalletGate>

import { ConnectedNetworkGate } from '@avalabs/avacloud-kit-ui-preview';

function StakingFeature() {
  return (
    <ConnectedNetworkGate
      chainId={43114}
      chainName="Avalanche C-Chain (Mainnet)"
      featureName="Staking"
    >
      <StakingContent />
    </ConnectedNetworkGate>
  );
}

Testnet Example

Please connect your wallet to use Testing

import { ConnectedNetworkGate } from '@avalabs/avacloud-kit-ui-preview';

function TestingFeature() {
  return (
    <ConnectedNetworkGate
      chainId={43113}
      chainName="Avalanche Fuji (Testnet)"
      featureName="Testing"
    >
      <TestContent />
    </ConnectedNetworkGate>
  );
}

Without Card Wrapper

Please connect your wallet to use DeFi

<ConnectedNetworkGate
  chainId={43114}
  chainName="Avalanche"
  featureName="DeFi"
  withCard={false}
>
  <DeFiContent />
</ConnectedNetworkGate>

Props

Prop

Type

Behavior

Wallet not connected: Shows ConnectedWalletGate prompt to connect wallet
Wrong network: Shows prompt with "Switch to [chainName]" button
Correct network: Renders children

The "Switch" button first tries wallet_switchEthereumChain, and falls back to wallet_addEthereumChain when the chain is missing.

Supported Wallets

Wallet	Type	Notes
Core	Extension/Mobile	Full support including multi-account
MetaMask	Extension	EVM chains
Coinbase Wallet	Extension	EVM chains
WalletConnect	Mobile QR	EVM chains
Ledger	Hardware	Via Core extension

Hooks

useConnectWalletContext

Access connection dialog state:

import { useConnectWalletContext } from '@avalabs/avacloud-kit-ui-preview';

function Example() {
  const {
    setConnectWalletDialogOpen,
    isConnectingToWallet
  } = useConnectWalletContext();

  return (
    <button onClick={() => setConnectWalletDialogOpen(true)}>
      Custom Connect Button
    </button>
  );
}

useSelectedWalletContext

Access wallet detection state:

import { useSelectedWalletContext } from '@avalabs/avacloud-kit-ui-preview';

function Example() {
  const {
    connectedWallet,
    isCoreInstalled,
    isMetaMaskInstalled
  } = useSelectedWalletContext();

  // ...
}

dappService.useAccount

Access current account:

import { dappService } from '@avalabs/avacloud-kit-ui-preview';

function Example() {
  const { account, isConnected, connector } = dappService.useAccount();

  if (!isConnected) return <span>Not connected</span>;
  return <span>Connected: {account}</span>;
}

Provider Hierarchy

The correct provider order is:

AvaCloudKitProvider (includes WagmiProvider)
  - SelectedWalletProvider (wallet detection)
    - ConnectWalletProvider (dialog state)
      - Your App

Wallet Connection

Connection controls

Network-sensitive UX

Guarded experiences

Prerequisites

Quick Start

Connect Wallet Button

Connected Wallet Display

Full Example

Chain Switcher Demo

Connected Wallet Gate

With Card Wrapper

Props

Connected Network Gate

Mainnet Example

Testnet Example

Without Card Wrapper

Props

Behavior

Supported Wallets

Hooks

useConnectWalletContext

useSelectedWalletContext

dappService.useAccount

Provider Hierarchy

On this page