Use the Wallet API in a React app

This guide shows how to integrate the Ledger Wallet API in a React app: install the packages, configure the transport, wrap your app, and optionally test with the simulator.

Prerequisites

• A React app (client-side)
• Node.js and a package manager (npm, yarn or pnpm)

Install packages

Install the base client:

npm install @ledgerhq/wallet-api-client

pnpm add @ledgerhq/wallet-api-client

yarn add @ledgerhq/wallet-api-client

bun add @ledgerhq/wallet-api-client

Install the React helper package with hooks:

npm install @ledgerhq/wallet-api-client-react

pnpm add @ledgerhq/wallet-api-client-react

yarn add @ledgerhq/wallet-api-client-react

bun add @ledgerhq/wallet-api-client-react

Optional: install the simulator for server-side testing:

npm install @ledgerhq/wallet-api-simulator

pnpm add @ledgerhq/wallet-api-simulator

yarn add @ledgerhq/wallet-api-simulator

bun add @ledgerhq/wallet-api-simulator

Note: the simulator currently works only in server-side environments because it depends on process.

Configure the transport

Create a transport provider to enable communication with the Ledger Wallet API. Add a TransportProvider.tsx component that uses the Wallet API client to establish a window message transport (SSR-safe).

import { WalletAPIProvider } from "@ledgerhq/wallet-api-client-react";
import { Transport, WindowMessageTransport } from "@ledgerhq/wallet-api-client";
 
function TransportProvider({ children }) {
  function getWalletAPITransport(): Transport {
    if (typeof window === "undefined") {
      return {
        onMessage: undefined,
        send: () => {},
      };
    }
 
    const transport = new WindowMessageTransport();
    transport.connect();
    return transport;
  }
 
  const transport = getWalletAPITransport();
 
  return (
    <WalletAPIProvider transport={transport}>{children}</WalletAPIProvider>
  );
}
 
export default TransportProvider;

How it works

• Import the client React provider and transport types from the Ledger Wallet API packages.
• Create TransportProvider to render its children inside WalletAPIProvider.
• Use getWalletAPITransport to supply a transport: during SSR, return a no-op transport; in the browser, use WindowMessageTransport and call connect().
• WindowMessageTransport communicates with the Ledger Wallet API via window messages.
• WalletAPIProvider receives the transport so the rest of the app (its {children}) can access the API.

Wrap your app

Wrap your root <App /> component with the TransportProvider:

import React from 'react';
import ReactDOM from 'react-dom';
import App from './App';
import TransportProvider from './TransportProvider';
 
ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
  <React.StrictMode>
    <TransportProvider>
      <App />
    </TransportProvider>
  </React.StrictMode>
);

With this setup, your app can access the Ledger Wallet API via the WalletAPIProvider context.

Test with the simulator (optional)

To test without connecting to the Ledger Wallet App directly, use @ledgerhq/wallet-api-simulator in a server-side environment.

npm install @ledgerhq/wallet-api-simulator

pnpm add @ledgerhq/wallet-api-simulator

yarn add @ledgerhq/wallet-api-simulator

bun add @ledgerhq/wallet-api-simulator

Remember: it currently only functions server-side due to a dependency on process.

Next steps

• Make your Live App ready to be registered by creating your manifest.
• Learn how to create your manifest: how to create your manifest