Cardano Connect with Wallet - React

React hooks and components for connecting Cardano wallets to dApps. Supports desktop browser extensions and mobile native wallets with built-in CIP-8, CIP-30, CIP-45, and CIP-158 support.

🚀 Getting Started

npm i @cardano-foundation/cardano-connect-with-wallet

For live examples see the storybook playground.

🎨 Components

ConnectWalletButton

A single button that opens a dropdown listing available wallets. On mobile it handles deep links and app store redirects automatically.

import { ConnectWalletButton } from '@cardano-foundation/cardano-connect-with-wallet';

<ConnectWalletButton
  supportedWallets={['Eternl', 'Nami', 'Yoroi', 'Vespr', 'Begin']}
  onConnect={(walletName) => console.log('connected:', walletName)}
  onDisconnect={() => console.log('disconnected')}
/>

Props

| Prop | Type | Default | Description | |---|---|---|---| | label | string \| ReactNode | 'Connect Wallet' | Button label when no wallet is connected | | supportedWallets | string[] | Eternl, Nami, Yoroi... | Wallets shown in the dropdown | | showUnavailableWallets | UnavailableWalletVisibility | SHOW_UNAVAILABLE_ON_MOBILE | Controls which wallets are listed | | alwaysVisibleWallets | string[] | [] | Wallets always shown regardless of install state | | primaryColor | string | '#0538AF' | Accent color for the button and menu | | borderRadius | number | 15 | Border radius in pixels | | showAccountBalance | boolean | false | Show ADA balance instead of stake address | | limitNetwork | NetworkType | — | Restrict to MAINNET or TESTNET | | peerConnectEnabled | boolean | true | Show the CIP-45 P2P QR option | | cip158Enabled | boolean | true | Use CIP-158 deep links for supported mobile wallets | | dAppName | string | 'Awesome DApp' | dApp name shown in the CIP-45 QR dialog | | dAppUrl | string | — | dApp URL used for CIP-45 peer identity | | extensions | number[] | — | CIP extension numbers to request on connect (e.g. [95]) | | message | string | — | If set, adds a "Sign message" action when connected | | customActions | Action[] | [] | Extra menu items shown when connected | | hideActionMenu | boolean | false | Hide the action dropdown when connected | | customCSS | string | — | Extra CSS applied to the outer wrapper | | onConnect | (walletName: string) => void | — | Called after a successful connection | | onDisconnect | () => void | — | Called after disconnect | | onSignMessage | (signature, key) => void | — | Called after a successful message signature | | onConnectError | (walletName, error, level) => void | alert | Called when connection fails |

ConnectWalletList

A flat list of wallet buttons, useful when you want to embed the wallet picker inline rather than inside a dropdown.

import { ConnectWalletList } from '@cardano-foundation/cardano-connect-with-wallet';

<ConnectWalletList
  borderRadius={15}
  gap={12}
  primaryColor="#0538AF"
  onConnect={onConnectWallet}
  customCSS={`
    font-family: Helvetica Light, sans-serif;
    font-size: 0.875rem;
    font-weight: 700;
    width: 164px;
    & > span { padding: 5px 16px; }
  `}
/>

Accepts the same props as ConnectWalletButton minus label, showAccountBalance, hideActionMenu, message, customActions, beforeComponent, and afterComponent.

🪝 useCardano Hook

useCardano is the low-level hook used by both components. Use it when you need direct access to wallet state or want to build a fully custom UI.

import { useCardano } from '@cardano-foundation/cardano-connect-with-wallet';

const { 
  isEnabled,
  isConnected,
  isConnecting,
  enabledWallet,
  stakeAddress,
  usedAddresses,
  unusedAddresses,
  accountBalance,
  installedExtensions,
  connect,
  disconnect,
  signMessage,
} = useCardano({ limitNetwork: NetworkType.MAINNET });

// Connect by wallet name
await connect('eternl', onSuccess, onError, [{ cip: 95 }]);

// Disconnect
disconnect();

// Sign a message (CIP-8)
signMessage('Hello Cardano', (signature, key) => console.log(signature));

📱 Mobile Wallets

On mobile devices the library automatically adapts its behavior:

Wallets with CIP-158 support (Eternl, Vespr): tapping the wallet fires a web+cardano://browse/v1?uri=<encoded_url> deep link. If the wallet app is installed it opens its in-app browser with the CIP-30 API already injected. If the app is not installed the user is redirected to the App Store or Play Store after a 2.5 s timeout.

Other mobile wallets (Begin, Yoroi, Flint): tapping redirects directly to the appropriate app store if the wallet is not already injected.

To opt out of CIP-158 deep links set cip158Enabled={false} on either component.

🔗 CIP-45: P2P Wallet Connection

CIP-45 lets a mobile wallet connect to a desktop dApp by scanning a QR code. Both components show a "P2P Wallet" entry in the wallet list when peerConnectEnabled is true (the default). Clicking it opens a modal with a QR code the user scans with their mobile wallet.

<ConnectWalletButton
  peerConnectEnabled={true}
  dAppName="My dApp"
  dAppUrl="https://my-dapp.io"
  peerConnectSubtitle="Scan with a CIP-45 compatible wallet such as Eternl"
/>

ℹ️ SSR with Next.js

This library accesses window and localStorage which are not available during server-side rendering. Use dynamic imports with ssr: false for both components and the hook.

const ConnectWalletButton = dynamic(
  () =>
    import('@cardano-foundation/cardano-connect-with-wallet').then(
      (mod) => mod.ConnectWalletButton
    ),
  { ssr: false }
);

💪 Contributing

Please have a look at our contributing infos to become familiar with our guidelines. There is also a short description for our development setup as we use Storybook for testing, playing around and for supporting the development process.