MnemonicDisplay

A versatile component for handling mnemonic seed phrases with three modes: viewing, verifying, and importing. It provides a secure interface for displaying recovery phrases with optional verification and import capabilities.

Mnemonic DisplayDisplay, verify, and import mnemonic phrases with secure handling and validation.

Recovery Phrase

1abandon

2abandon

3abandon

4abandon

5abandon

6abandon

7abandon

8abandon

9abandon

10abandon

11abandon

12about

Write down these words in order. This is the ONLY way to recover your Bitcoin identity if you lose your password.

I have written down my recovery phrase and stored it in a safe place

Available Modes

View ModeVerify ModeImport Mode

Features

Word NumberingCopy ProtectionShuffle VerificationInput ValidationMultiple Modes

Security Note: Mnemonic phrases should be handled with extreme care. Never share or store them in plain text.

Installation

npx bigblocks add mnemonic-display

Import

import { MnemonicDisplay, MnemonicMode } from 'bigblocks';

Props

Prop	Type	Required	Default	Description
mnemonic	`string`	No	-	Mnemonic phrase to display (for view/verify modes)
mode	`MnemonicMode`	No	`'view'`	Display mode: 'view', 'verify', or 'import'
onResult	`(result: MnemonicResult) => void`	No	-	Callback with operation result
onContinue	`() => void`	No	-	Handler for continue action
onBack	`() => void`	No	-	Handler for back action
showCopyButton	`boolean`	No	`true`	Show copy to clipboard button
requireVerification	`boolean`	No	`false`	Require verification in view mode
wordCount	`12 \| 24`	No	`12`	Expected word count for import
autoCompleteLastWord	`boolean`	No	`false`	Auto-complete the last word
className	`string`	No	-	Additional CSS classes

Modes

View Mode

Display a mnemonic phrase securely with optional copy functionality:

import { MnemonicDisplay, MnemonicMode } from 'bigblocks';

export default function ViewMnemonic() {
  const mnemonic = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about";

  return (
    <MnemonicDisplay
      mode={MnemonicMode.View}
      mnemonic={mnemonic}
      onContinue={() => {
        console.log('User acknowledged');
      }}
      showCopyButton={true}
    />
  );
}

Verify Mode

Test user's backup by requiring them to confirm specific words:

import { MnemonicDisplay, MnemonicMode } from 'bigblocks';

export default function VerifyMnemonic() {
  const mnemonic = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about";

  return (
    <MnemonicDisplay
      mode={MnemonicMode.Verify}
      mnemonic={mnemonic}
      onResult={(result) => {
        if (result.verified) {
          console.log('Verification successful');
        } else {
          console.log('Verification failed');
        }
      }}
    />
  );
}

Import Mode

Allow users to enter their own mnemonic phrase:

import { MnemonicDisplay, MnemonicMode } from 'bigblocks';

export default function ImportMnemonic() {
  return (
    <MnemonicDisplay
      mode={MnemonicMode.Import}
      wordCount={12}
      autoCompleteLastWord={true}
      onResult={(result) => {
        if (result.importedMnemonic) {
          console.log('Imported:', result.importedMnemonic);
        }
      }}
    />
  );
}

Result Types

type MnemonicResult = {
  verified?: boolean;        // For verify mode
  importedMnemonic?: string; // For import mode
  words?: string[];          // Word array for processing
};

Advanced Usage

Complete Backup Flow

import { MnemonicDisplay, MnemonicMode } from 'bigblocks';
import { useState } from 'react';

export function BackupFlow() {
  const [step, setStep] = useState<'view' | 'verify' | 'complete'>('view');
  const mnemonic = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about";

  return (
    <div className="max-w-2xl mx-auto p-6">
      {step === 'view' && (
        <div>
          <h2 className="text-2xl font-bold mb-4">Your Recovery Phrase</h2>
          <MnemonicDisplay
            mode={MnemonicMode.View}
            mnemonic={mnemonic}
            requireVerification={true}
            onContinue={() => setStep('verify')}
            showCopyButton={true}
          />
        </div>
      )}

      {step === 'verify' && (
        <div>
          <h2 className="text-2xl font-bold mb-4">Verify Your Backup</h2>
          <MnemonicDisplay
            mode={MnemonicMode.Verify}
            mnemonic={mnemonic}
            onResult={(result) => {
              if (result.verified) {
                setStep('complete');
              } else {
                alert('Please try again');
              }
            }}
            onBack={() => setStep('view')}
          />
        </div>
      )}

      {step === 'complete' && (
        <div className="text-center">
          <h2 className="text-2xl font-bold mb-4">Backup Complete!</h2>
          <p>Your recovery phrase has been verified.</p>
        </div>
      )}
    </div>
  );
}

Import with Validation

import { MnemonicDisplay, MnemonicMode } from 'bigblocks';
import { validateMnemonic } from '@bsv/sdk';

export function ImportWithValidation() {
  const handleImport = async (result: MnemonicResult) => {
    if (!result.importedMnemonic) return;

    try {
      // Validate mnemonic
      const isValid = validateMnemonic(result.importedMnemonic);
      
      if (!isValid) {
        throw new Error('Invalid mnemonic phrase');
      }

      // Process valid mnemonic
      await processImport(result.importedMnemonic);
      
    } catch (error) {
      console.error('Import failed:', error);
    }
  };

  return (
    <MnemonicDisplay
      mode={MnemonicMode.Import}
      wordCount={24}
      autoCompleteLastWord={true}
      onResult={handleImport}
      onBack={() => window.history.back()}
    />
  );
}

View with Custom Styling

import { MnemonicDisplay, MnemonicMode } from 'bigblocks';

export function StyledMnemonicView() {
  return (
    <div className="bg-orange-50 p-8 rounded-xl">
      <h2 className="text-xl font-semibold mb-4">Recovery Phrase</h2>
      
      <MnemonicDisplay
        mode={MnemonicMode.View}
        mnemonic={userMnemonic}
        className="bg-white shadow-sm"
        showCopyButton={false}
        onContinue={() => {
          console.log('Proceeding to next step');
        }}
      />
      
      <div className="mt-4 text-sm text-orange-700">
        ⚠️ Never share these words with anyone
      </div>
    </div>
  );
}

Conditional Copy Button

import { MnemonicDisplay, MnemonicMode } from 'bigblocks';
import { useState } from 'react';

export function ConditionalCopy() {
  const [allowCopy, setAllowCopy] = useState(false);

  return (
    <div>
      <label className="flex items-center mb-4">
        <input
          type="checkbox"
          checked={allowCopy}
          onChange={(e) => setAllowCopy(e.target.checked)}
          className="mr-2"
        />
        I understand the security risks of copying
      </label>

      <MnemonicDisplay
        mode={MnemonicMode.View}
        mnemonic={mnemonic}
        showCopyButton={allowCopy}
        onContinue={() => console.log('Continue')}
      />
    </div>
  );
}

Common Patterns

In SignupFlow

import { MnemonicDisplay, MnemonicMode } from 'bigblocks';

export function SignupMnemonicStep({ mnemonic, onComplete }) {
  const [verified, setVerified] = useState(false);

  return (
    <div>
      {!verified ? (
        <MnemonicDisplay
          mode={MnemonicMode.View}
          mnemonic={mnemonic}
          requireVerification={true}
          onContinue={() => setVerified(true)}
        />
      ) : (
        <MnemonicDisplay
          mode={MnemonicMode.Verify}
          mnemonic={mnemonic}
          onResult={(result) => {
            if (result.verified) {
              onComplete();
            }
          }}
        />
      )}
    </div>
  );
}

Recovery Flow

import { MnemonicDisplay, MnemonicMode } from 'bigblocks';

export function RecoveryFlow() {
  const [mnemonic, setMnemonic] = useState<string | null>(null);

  return (
    <div>
      <h2>Recover Your Wallet</h2>
      
      <MnemonicDisplay
        mode={MnemonicMode.Import}
        wordCount={12}
        onResult={(result) => {
          if (result.importedMnemonic) {
            setMnemonic(result.importedMnemonic);
            // Proceed with recovery
            recoverWallet(result.importedMnemonic);
          }
        }}
      />
    </div>
  );
}

Features by Mode

View Mode Features

Grid display of numbered words
Optional copy to clipboard
Security warnings
Verification requirement option
Continue button

Verify Mode Features

Random word verification
Input validation
Error feedback
Back navigation
Success/failure callbacks

Import Mode Features

Word count selection (12 or 24)
Auto-completion for last word
BIP39 word list validation
Paste support
Progress tracking

Styling

The component uses Radix Themes and supports custom styling:

/* Word grid styling */
.mnemonic-grid {
  display: grid;
  grid-template-columns: repeat(3, 1fr);
  gap: 0.5rem;
}

/* Word item styling */
.mnemonic-word {
  padding: 0.5rem;
  background: var(--gray-2);
  border-radius: var(--radius-2);
  font-family: monospace;
}

Best Practices

Security First: Always show security warnings in view mode
Verification: Require verification for new wallet creation
Copy Protection: Consider disabling copy for sensitive contexts
Clear Instructions: Provide mode-specific guidance
Error Handling: Validate mnemonics before processing

Accessibility

Keyboard navigation for all interactive elements
Screen reader announcements for verification
Clear focus indicators
Semantic HTML structure

Troubleshooting

Verification Failing

Ensure correct mnemonic is passed
Check for extra spaces or formatting
Verify word indices are correct

Import Not Working

Validate BIP39 word list compatibility
Check word count matches expected
Ensure proper whitespace handling

Copy Not Working

Check browser clipboard permissions
Verify showCopyButton prop
Test in different browsers

IdentityGeneration - Generate new identities
BackupDownload - Download encrypted backups
SignupFlow - Complete signup with mnemonic
BackupImport - Import from various formats

API Reference

This component provides secure mnemonic phrase handling with three distinct modes for viewing, verifying, and importing seed phrases.

MnemonicMode Enum

enum MnemonicMode {
  View = "view",
  Verify = "verify",
  Import = "import"
}

MnemonicResult Type

type MnemonicResult = {
  verified?: boolean;        // Verification success (verify mode)
  importedMnemonic?: string; // Imported phrase (import mode)
  words?: string[];          // Word array for processing
};

Notes for Improvement

Mode-Based Implementation: The actual component is more sophisticated than the prompt suggested, with three distinct modes:

View mode for displaying phrases
Verify mode for testing user knowledge
Import mode for entering phrases

The prompt described mainly view mode features, while the actual implementation provides a complete mnemonic handling solution with verification and import capabilities.

MnemonicDisplay

On this page