MetaMask Unlock Modal

A reusable React component that replicates MetaMask's unlock modal experience. Perfect for dApps that need a MetaMask-style wallet unlock interface.

Features

• ✅ Authentic MetaMask UI - Pixel-perfect replication of MetaMask's unlock modal
• ✅ One-line usage - Easy integration with React Context API
• ✅ Auto MetaMask detection - Automatically checks if MetaMask is installed
• ✅ Smart notifications - Shows Gmail-style notification if MetaMask missing
• ✅ Dark mode support - Automatic dark mode detection
• ✅ Accessible - Keyboard navigation and ARIA labels
• ✅ TypeScript friendly - Works with TypeScript projects

Installation

npm install connect-metamask

Quick Start

Step 1: Wrap your app with ModalProvider

import { ModalProvider } from 'connect-metamask';
import 'connect-metamask/styles/modal';
import 'connect-metamask/styles/index';

function App() {
  return (
    <ModalProvider>
      <YourApp />
    </ModalProvider>
  );
}

Step 2: Use the hook (one line!)

import { useUnlockModal } from 'connect-metamask';

function ConnectButton() {
  const { openModal } = useUnlockModal();
  
  return (
    <button onClick={() => openModal(() => {
      console.log('Wallet unlocked!');
    })}>
      Connect Wallet
    </button>
  );
}

That's it! 🎉

Usage

Basic Example

import React from 'react';
import { ModalProvider, useUnlockModal } from 'connect-metamask';
import 'connect-metamask/styles/modal';
import 'connect-metamask/styles/index';

function ConnectButton() {
  const { openModal } = useUnlockModal();

  const handleConnect = () => {
    openModal(() => {
      // Callback when wallet is successfully unlocked
      alert('Wallet connected!');
      // Add your wallet connection logic here
    });
  };

  return <button onClick={handleConnect}>Connect Wallet</button>;
}

function App() {
  return (
    <ModalProvider>
      <ConnectButton />
    </ModalProvider>
  );
}

With Custom Styling

The modal automatically adapts to your app's theme via CSS variables. You can customize colors by overriding CSS variables in your app:

:root {
  --color-background-default: #ffffff;
  --color-text-default: #24292e;
  /* ... other variables */
}

API Reference

ModalProvider

Context provider that manages modal state globally.

Props:

• children (ReactNode): Your app components

useUnlockModal()

Hook to control the modal from any component.

Returns:

• openModal(onSuccess?) - Opens the modal
  • onSuccess (optional function): Callback executed when wallet is unlocked
  • Returns true if modal opened, false if MetaMask not installed
• closeModal() - Manually closes the modal

useUnlockModalStandalone()

Alternative hook that returns the modal component for manual rendering.

Returns:

• openModal(onSuccess?) - Opens the modal
• closeModal() - Closes the modal
• isOpen (boolean) - Modal open state
• Modal (ReactNode) - Modal component to render

Styling

Import the required CSS files:

// Method 1: Using package exports
import 'connect-metamask/styles/modal';
import 'connect-metamask/styles/index';

// Method 2: Direct path (if using source files)
import 'connect-metamask/src/styles/modal.css';
import 'connect-metamask/src/styles/index.css';

Requirements

• React 16.8+ or 17.x or 18.x
• React DOM 16.8+ or 17.x or 18.x

Browser Support

• Chrome/Edge (latest)
• Firefox (latest)
• Safari (latest)

Requires MetaMask browser extension for full functionality.

Development

# Install dependencies
npm install

# Run development server
npm start

# Build library
npm run build:lib

License

MIT

Contributing

Contributions welcome! Please open an issue or submit a pull request.