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.