Mesh LogoMesh
React Components

Getting Started with React

Install Mesh React, configure the provider, and connect your first Cardano wallet in minutes.

Overview

This guide walks you through setting up Mesh React in your application. By the end, you will have a working wallet connection button that lets users connect their Cardano wallets.

You will learn how to:

  • Install the @meshsdk/react package
  • Configure the MeshProvider context
  • Add a wallet connection button
  • Access connected wallet data

Quick Start

Get a wallet connection working in under 2 minutes:

// pages/_app.tsx (Next.js Pages Router)
import "@meshsdk/react/styles.css";
import { MeshProvider } from "@meshsdk/react";
import type { AppProps } from "next/app";

export default function App({ Component, pageProps }: AppProps) {
  return (
    <MeshProvider>
      <Component {...pageProps} />
    </MeshProvider>
  );
}
// pages/index.tsx
import { CardanoWallet, useWallet } from "@meshsdk/react";

export default function Home() {
  const { connected, wallet } = useWallet();

  return (
    <div>
      <CardanoWallet />
      {connected && <p>Wallet connected!</p>}
    </div>
  );
}

Installation

The fastest way to start is with the Mesh CLI, which scaffolds a complete project:

npx meshjs your-app-name

Select the React template when prompted. This creates a new project with Mesh pre-configured.

Option 2: Manual Installation

Add the package to an existing project:

npm install @meshsdk/react
yarn add @meshsdk/react
pnpm add @meshsdk/react

Setup

Step 1: Add the CSS

Import the Mesh styles in your application root. This applies default styling to all Mesh components.

Next.js Pages Router (pages/_app.tsx):

import "@meshsdk/react/styles.css";

Next.js App Router (app/layout.tsx):

import "@meshsdk/react/styles.css";

Step 2: Add the MeshProvider

Wrap your application with MeshProvider to enable wallet context throughout your app.

Next.js Pages Router:

// pages/_app.tsx
import "@meshsdk/react/styles.css";
import { MeshProvider } from "@meshsdk/react";
import type { AppProps } from "next/app";

export default function App({ Component, pageProps }: AppProps) {
  return (
    <MeshProvider>
      <Component {...pageProps} />
    </MeshProvider>
  );
}

Next.js App Router:

// app/layout.tsx
import "@meshsdk/react/styles.css";
import { MeshProvider } from "@meshsdk/react";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <MeshProvider>{children}</MeshProvider>
      </body>
    </html>
  );
}

Step 3: Add the Wallet Button

Add CardanoWallet anywhere in your app to show a wallet connection button:

import { CardanoWallet } from "@meshsdk/react";

export default function Header() {
  return (
    <nav>
      <CardanoWallet />
    </nav>
  );
}

API Reference

MeshProvider

The context provider that enables wallet functionality throughout your application.

Props

PropTypeDefaultDescription
childrenReactNodeRequiredYour application components

Usage

import { MeshProvider } from "@meshsdk/react";

function App({ children }) {
  return <MeshProvider>{children}</MeshProvider>;
}

CardanoWallet

A pre-built button component that handles wallet selection and connection.

Props

PropTypeDefaultDescription
labelstring"Connect Wallet"Button text before connection
isDarkbooleanfalseEnable dark mode styling
persistbooleanfalseRemember wallet choice across sessions
onConnected() => voidundefinedCallback fired after successful connection
web3ServicesobjectundefinedMesh Web3 Services configuration
cardanoPeerConnectobjectundefinedCIP-45 WebRTC configuration
burnerWalletobjectundefinedEnable burner wallet for testing
injectFn() => Promise<void>undefinedCustom wallet injection (MetaMask Snaps)

Usage Examples

Basic usage:

import { CardanoWallet } from "@meshsdk/react";

export default function Page() {
  return <CardanoWallet />;
}

With dark mode:

import { CardanoWallet } from "@meshsdk/react";

export default function Page() {
  return <CardanoWallet isDark={true} />;
}

With custom label:

import { CardanoWallet } from "@meshsdk/react";

export default function Page() {
  return <CardanoWallet label="Sign In with Wallet" />;
}

With session persistence:

import { CardanoWallet } from "@meshsdk/react";

export default function Page() {
  return <CardanoWallet persist={true} />;
}

With connection callback:

import { CardanoWallet } from "@meshsdk/react";

export default function Page() {
  const handleConnected = () => {
    console.log("Wallet connected successfully");
    // Redirect, fetch data, etc.
  };

  return <CardanoWallet onConnected={handleConnected} />;
}

useWallet Hook

Access wallet state and connection functions from any component.

Return Values

PropertyTypeDescription
walletMeshCardanoBrowserWalletWallet instance with CIP-30 methods
connectedbooleanWhether a wallet is connected
connectingbooleanWhether connection is in progress
namestringName of the connected wallet
state"NOT_CONNECTED" | "CONNECTING" | "CONNECTED"Current connection state
connect(walletName: string) => voidConnect to a specific wallet
disconnect() => voidDisconnect the current wallet
errorError | nullConnection error if any

Usage

import { useWallet } from "@meshsdk/react";

export default function WalletInfo() {
  const { connected, name, wallet, disconnect } = useWallet();

  if (!connected) {
    return <p>No wallet connected</p>;
  }

  return (
    <div>
      <p>Connected to: {name}</p>
      <button onClick={disconnect}>Disconnect</button>
    </div>
  );
}

Customization

Dark Mode

Enable dark mode styling with the isDark prop:

<CardanoWallet isDark={true} />

Custom Button Label

Change the button text:

<CardanoWallet label="Sign In" />

Session Persistence

Save the user's wallet choice and auto-connect on return visits:

<CardanoWallet persist={true} />

Mesh Web3 Services

Integrate Mesh Web3 Services for enhanced features:

import { CardanoWallet } from "@meshsdk/react";
import { BlockfrostProvider } from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_BLOCKFROST_API_KEY>");

export default function Page() {
  return (
    <CardanoWallet
      web3Services={{
        networkId: 0, // 0 = testnet, 1 = mainnet
        fetcher: provider,
        submitter: provider,
      }}
    />
  );
}

CIP-45 WebRTC Connection

Enable decentralized wallet communication via WebRTC:

import { CardanoWallet } from "@meshsdk/react";

export default function Page() {
  return (
    <CardanoWallet
      cardanoPeerConnect={{
        dAppInfo: {
          name: "My dApp",
          url: "https://mydapp.com",
        },
        announce: [
          "wss://dev.btt.cf-identity-wallet.metadata.dev.cf-deployments.org",
        ],
      }}
    />
  );
}

Burner Wallet (Testing)

Enable temporary wallets for development and testing:

import { CardanoWallet } from "@meshsdk/react";
import { BlockfrostProvider } from "@meshsdk/core";

const provider = new BlockfrostProvider("<YOUR_BLOCKFROST_API_KEY>");

export default function Page() {
  return (
    <CardanoWallet
      burnerWallet={{
        networkId: 0,
        provider: provider,
      }}
    />
  );
}

MetaMask Snaps Integration

Add custom wallet injection for MetaMask Snaps:

import { CardanoWallet } from "@meshsdk/react";
import { checkIfMetamaskInstalled } from "./metamask-utils";

export default function Page() {
  return (
    <CardanoWallet
      injectFn={async () => await checkIfMetamaskInstalled("preprod")}
    />
  );
}

Complete Example

A full example combining multiple features:

// pages/_app.tsx
import "@meshsdk/react/styles.css";
import { MeshProvider } from "@meshsdk/react";
import type { AppProps } from "next/app";

export default function App({ Component, pageProps }: AppProps) {
  return (
    <MeshProvider>
      <Component {...pageProps} />
    </MeshProvider>
  );
}
// pages/index.tsx
import { CardanoWallet, useWallet, useLovelace } from "@meshsdk/react";

export default function Home() {
  const { connected, name, disconnect } = useWallet();
  const lovelace = useLovelace();

  const handleConnected = () => {
    console.log("Wallet connected!");
  };

  return (
    <main>
      <h1>My Cardano dApp</h1>

      {!connected ? (
        <CardanoWallet
          label="Connect Your Wallet"
          isDark={true}
          persist={true}
          onConnected={handleConnected}
        />
      ) : (
        <div>
          <p>Connected to: {name}</p>
          <p>Balance: {lovelace ? parseInt(lovelace) / 1_000_000 : 0} ADA</p>
          <button onClick={disconnect}>Disconnect</button>
        </div>
      )}
    </main>
  );
}

Troubleshooting

"No wallets found"

Problem: The wallet list is empty even with wallets installed.

Solutions:

  1. Ensure the wallet browser extension is installed and enabled
  2. Refresh the page after installing a new wallet
  3. Check that you're on a supported browser (Chrome, Brave, Firefox)

"MeshProvider not found"

Problem: Hooks throw an error about missing provider.

Solution: Wrap your app with MeshProvider at the root level:

// pages/_app.tsx
import { MeshProvider } from "@meshsdk/react";

export default function App({ Component, pageProps }) {
  return (
    <MeshProvider>
      <Component {...pageProps} />
    </MeshProvider>
  );
}

Styles not loading

Problem: Components appear unstyled.

Solution: Import the CSS file in your app root:

import "@meshsdk/react/styles.css";

Wallet connection fails silently

Problem: Clicking connect does nothing.

Solutions:

  1. Check browser console for errors
  2. Ensure the wallet extension is unlocked
  3. Verify the user has an account set up in their wallet
  4. Check the error property from useWallet() for details

TypeScript errors with wallet methods

Problem: TypeScript doesn't recognize wallet methods.

Solution: The wallet object from useWallet() is a MeshCardanoBrowserWallet instance. Import types from @meshsdk/wallet:

import type { MeshCardanoBrowserWallet } from "@meshsdk/wallet";

React Components

Build Cardano dApps with pre-built React components and hooks for wallet connections, transactions, and blockchain interactions.

UI Components

Pre-built React components for wallet connections, badges, and common Cardano dApp UI patterns.

On this page

OverviewQuick StartInstallationOption 1: Mesh CLI (Recommended)Option 2: Manual InstallationSetupStep 1: Add the CSSStep 2: Add the MeshProviderStep 3: Add the Wallet ButtonAPI ReferenceMeshProviderPropsUsageCardanoWalletPropsUsage ExamplesuseWallet HookReturn ValuesUsageCustomizationDark ModeCustom Button LabelSession PersistenceMesh Web3 ServicesCIP-45 WebRTC ConnectionBurner Wallet (Testing)MetaMask Snaps IntegrationComplete ExampleTroubleshooting"No wallets found""MeshProvider not found"Styles not loadingWallet connection fails silentlyTypeScript errors with wallet methodsRelated Links