Skip to main content

React Hooks Overview

Cardano DevKit provides React hooks for seamless integration with React applications.

Installation​

npm install cardano-devkit react

Available Hooks​

HookPurpose
useCardanoDevKitMain hook for DevKit instance management
useWalletWallet connection and management

useCardanoDevKit​

The primary hook for managing your Cardano connection.

import { useCardanoDevKit } from 'cardano-devkit/react';

function App() {
  const {
    lucid,
    network,
    isInitialized,
    isLoading,
    error,
    switchNetwork,
    getEnvironment
  } = useCardanoDevKit({
    network: 'LocalDevnet',
    debug: true
  });

  if (isLoading) return <div>Connecting to Cardano...</div>;
  if (error) return <div>Error: {error.message}</div>;
  if (!isInitialized) return <div>Not connected</div>;

  return (
    <div>
      <h1>Connected to {network}</h1>
      <p>Environment: {getEnvironment()}</p>
    </div>
  );
}

Options​

interface UseCardanoDevKitOptions {
  network?: NetworkType;       // Default: 'Preprod'
  provider?: ProviderConfig;   // Custom provider
  debug?: boolean;             // Enable logging
  autoConnect?: boolean;       // Auto-connect on mount (default: true)
}

Return Value​

interface UseCardanoDevKitReturn {
  // State
  lucid: Lucid | null;
  network: NetworkType;
  isInitialized: boolean;
  isLoading: boolean;
  error: Error | null;

  // Actions
  init: () => Promise<void>;
  switchNetwork: (network: NetworkType) => Promise<void>;

  // Utilities
  getEnvironment: () => 'development' | 'testnet' | 'production';
  isLocalDevnet: () => boolean;
  isTestnet: () => boolean;
  isSafeForTesting: () => boolean;
}

useWallet​

Hook for wallet operations.

import { useCardanoDevKit, useWallet } from 'cardano-devkit/react';

function WalletComponent() {
  const { lucid } = useCardanoDevKit({ network: 'LocalDevnet' });
  const {
    address,
    balance,
    isConnected,
    connect,
    disconnect,
    signMessage,
    sendAda
  } = useWallet(lucid);

  if (!isConnected) {
    return (
      <button onClick={() => connect('seed', mySeed)}>
        Connect Wallet
      </button>
    );
  }

  return (
    <div>
      <p>Address: {address}</p>
      <p>Balance: {formatAda(balance)} ADA</p>
      <button onClick={disconnect}>Disconnect</button>
    </div>
  );
}

Connection Methods​

// From seed phrase
await connect('seed', 'word1 word2 ... word24');

// From private key
await connect('privateKey', 'ed25519_sk...');

// From browser wallet (Nami, Eternl, etc.)
await connect('browser', 'nami');

Return Value​

interface UseWalletReturn {
  // State
  address: string | null;
  balance: bigint;
  utxos: UTxO[];
  isConnected: boolean;
  isLoading: boolean;
  error: Error | null;

  // Actions
  connect: (method: string, credential: string) => Promise<void>;
  disconnect: () => void;
  refreshBalance: () => Promise<void>;
  signMessage: (message: string) => Promise<string>;
  signTx: (tx: Transaction) => Promise<SignedTx>;

  // Transaction helpers
  sendAda: (to: string, amount: bigint) => Promise<string>;
  sendToken: (to: string, policyId: string, name: string, amount: bigint) => Promise<string>;
}

Complete Example​

import React, { useState } from 'react';
import { useCardanoDevKit, useWallet, WalletHelper } from 'cardano-devkit/react';

function CardanoApp() {
  const [recipient, setRecipient] = useState('');
  const [amount, setAmount] = useState('');

  const {
    lucid,
    network,
    isInitialized,
    switchNetwork
  } = useCardanoDevKit({
    network: 'LocalDevnet'
  });

  const {
    address,
    balance,
    isConnected,
    connect,
    sendAda,
    isLoading
  } = useWallet(lucid);

  const handleConnect = async () => {
    const seed = WalletHelper.generateSeed();
    await connect('seed', seed);
  };

  const handleSend = async (e: React.FormEvent) => {
    e.preventDefault();
    const lovelace = BigInt(parseFloat(amount) * 1_000_000);
    const txHash = await sendAda(recipient, lovelace);
    alert(`Transaction submitted: ${txHash}`);
  };

  if (!isInitialized) {
    return <div>Initializing...</div>;
  }

  return (
    <div className="cardano-app">
      <header>
        <h1>Cardano App</h1>
        <select
          value={network}
          onChange={(e) => switchNetwork(e.target.value)}
        >
          <option value="LocalDevnet">Local Devnet</option>
          <option value="Preview">Preview</option>
          <option value="Preprod">Preprod</option>
        </select>
      </header>

      {!isConnected ? (
        <button onClick={handleConnect} disabled={isLoading}>
          {isLoading ? 'Connecting...' : 'Create Wallet'}
        </button>
      ) : (
        <div className="wallet-panel">
          <div className="wallet-info">
            <p>Address: {address?.slice(0, 20)}...</p>
            <p>Balance: {Number(balance) / 1_000_000} ADA</p>
          </div>

          <form onSubmit={handleSend}>
            <input
              placeholder="Recipient address"
              value={recipient}
              onChange={(e) => setRecipient(e.target.value)}
            />
            <input
              type="number"
              placeholder="Amount (ADA)"
              value={amount}
              onChange={(e) => setAmount(e.target.value)}
            />
            <button type="submit" disabled={isLoading}>
              Send ADA
            </button>
          </form>
        </div>
      )}
    </div>
  );
}

export default CardanoApp;

Provider Setup​

Wrap your app with the DevKit provider for shared state:

import { CardanoProvider } from 'cardano-devkit/react';

function App() {
  return (
    <CardanoProvider
      config={{
        network: 'LocalDevnet',
        debug: true
      }}
    >
      <YourApp />
    </CardanoProvider>
  );
}

Then use hooks anywhere:

function DeepComponent() {
  // Access shared DevKit instance
  const { lucid, network } = useCardanoDevKit();
  // ...
}

Error Boundaries​

import { CardanoErrorBoundary } from 'cardano-devkit/react';

function App() {
  return (
    <CardanoErrorBoundary
      fallback={({ error, reset }) => (
        <div>
          <h2>Cardano Error</h2>
          <p>{error.message}</p>
          <button onClick={reset}>Retry</button>
        </div>
      )}
    >
      <CardanoApp />
    </CardanoErrorBoundary>
  );
}

TypeScript Support​

All hooks are fully typed:

import type { NetworkType, UTxO } from 'cardano-devkit';

// Types are inferred
const { lucid } = useCardanoDevKit();
//     ^? Lucid | null

const { balance } = useWallet(lucid);
//     ^? bigint

Next Steps​