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

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.