Developer Docs

Compatibility

The Wallet Kit widget requires React 18+ and is available for web applications using the JavaScript SDK.

Use Cases

Add a complete login UI to your React app without building custom components
Support multiple authentication methods (email OTP, OAuth, Farcaster, external wallets) from a single widget

Getting Started

Installation

npm install magic-sdk @magic-ext/wallet-kit

yarn add magic-sdk @magic-ext/wallet-kit

Usage

Initialize Magic with the WalletKitExtension, then render the MagicWidget component in your app.

JavaScript

import { Magic } from 'magic-sdk';
import { MagicWidget, WalletKitExtension } from '@magic-ext/wallet-kit';

const magic = new Magic('YOUR_API_KEY', {
  extensions: [new WalletKitExtension()],
});

export default function LoginPage() {
  const handleSuccess = (result) => {
    switch (result.method) {
      case 'email':
        // result.didToken for backend verification
        console.log('Email login:', result.didToken);
        break;
      case 'oauth':
        // result.magic.idToken for backend verification
        console.log('OAuth login:', result.magic.idToken);
        break;
      case 'farcaster':
        // result.didToken for backend verification
        console.log('Farcaster login:', result.didToken, result.farcaster);
        break;
      case 'wallet':
        // result.walletAddress for wallet connections
        console.log('Wallet connected:', result.walletAddress);
        break;
    }
  };

  return (
    <MagicWidget
      wallets={['metamask', 'coinbase', 'walletconnect']}
      enableFarcaster
      onSuccess={handleSuccess}
      onError={(error) => console.error(error)}
    />
  );
}

Configuration

The widget displays login options based on two sources: Dashboard-configured options — Email OTP and OAuth providers (Google, Apple, GitHub, etc.) are configured in your Magic Dashboard. Enable the authentication methods you want, and they will automatically appear in the widget. Code-configured options — External wallets and Farcaster are configured via props. Pass wallets to specify which external wallets to display, and enableFarcaster to show a Farcaster login button. For example, if you enable Email and Google OAuth in your dashboard and pass wallets={['metamask']} and enableFarcaster, the widget will show all four options: email input, Google sign-in button, Farcaster, and MetaMask.

Farcaster

To enable Farcaster login, pass the enableFarcaster prop. This adds a Farcaster button alongside your OAuth social providers. When clicked, users see a QR code they can scan with the Warpcast app on their phone. On mobile devices, the widget automatically redirects to the Farcaster app.

JavaScript

<MagicWidget
  enableFarcaster
  onSuccess={(result) => {
    if (result.method === 'farcaster') {
      console.log('DID token:', result.didToken);
      console.log('Farcaster user:', result.farcaster.username);
    }
  }}
/>

WalletConnect

If you include 'walletconnect' in the wallets prop, the widget uses Reown (formerly WalletConnect) under the hood. A default project ID is included for development, but for production apps you should provide your own to avoid rate limiting:

JavaScript

const magic = new Magic('YOUR_API_KEY', {
  extensions: [new WalletKitExtension({ projectId: 'YOUR_REOWN_PROJECT_ID' })],
});

You can get a project ID by creating a free account at dashboard.walletconnect.com.

Account Switching

When a user switches to a different account in their wallet (e.g. MetaMask), the widget automatically re-runs SIWE authentication for the new account in the background. The user will see their wallet’s native signing prompt — no widget UI changes occur. Use onAccountChanged to respond when the new session is ready:

JavaScript

<MagicWidget
  wallets={['metamask']}
  onSuccess={(result) => {
    if (result.method === 'wallet') {
      setAddress(result.walletAddress);
    }
  }}
  onAccountChanged={(result) => {
    // New SIWE session is verified — safe to update your app state
    setAddress(result.walletAddress);
  }}
  onError={(error) => {
    // Fires for both initial login failures and account switch re-auth failures
    console.error(error);
  }}
/>

API Reference

Props

Prop	Type	Default	Description
`displayMode`	`'inline' \| 'modal'`	`'inline'`	How the widget is displayed. `'inline'` renders in document flow, `'modal'` shows as an overlay.
`isOpen`	`boolean`	`true`	Whether the widget is visible.
`onClose`	`() => void`	—	Called when the user closes the widget.
`closeOnSuccess`	`boolean`	`false`	Automatically close after successful login (shows success screen for 2 seconds first).
`closeOnClickOutside`	`boolean`	`false`	Close when clicking the backdrop. Only applies in modal mode.
`wallets`	`Array`	`[]`	External wallets to display: `'metamask'`, `'coinbase'`, `'phantom'`, `'rabby'`, `'walletconnect'`.
`enableFarcaster`	`boolean`	`false`	Show a Farcaster login button alongside social providers.
`onSuccess`	`(result: LoginResult) => void`	—	Called on successful login. See Login Results for result structure.
`onAccountChanged`	`(result: WalletLoginResult) => void`	—	Called when a wallet user switches to a different account and re-authentication completes. Fires after the new SIWE session is verified, so `result.walletAddress` reflects the active account.
`onError`	`(error: Error) => void`	—	Called when login fails, or when a re-authentication triggered by an account switch fails (e.g. the user rejects the signing prompt).
`onReady`	`() => void`	—	Called when the widget has initialized and applied theme settings.

The onSuccess callback receives a result object with a method property indicating the authentication type:

// Email OTP login
{ method: 'email', didToken: string }

// OAuth login (Google, Apple, etc.)
{ method: 'oauth', oauth: { provider, scope, userHandle, userInfo }, magic: { idToken, userMetadata } }

// Farcaster login
{ method: 'farcaster', didToken: string, farcaster: { fid?, username?, displayName?, pfpUrl?, bio? } }

// External wallet login
{ method: 'wallet', walletAddress: string }

For email and Farcaster logins, use result.didToken for backend verification. For OAuth logins, use result.magic.idToken. Farcaster logins also include the user’s Farcaster profile data in result.farcaster.

Examples

Use modal mode to display the widget as an overlay:

JavaScript

import { useState } from 'react';
import { MagicWidget } from '@magic-ext/wallet-kit';

function App() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <>
      <button onClick={() => setIsOpen(true)}>Log in</button>
      <MagicWidget
        displayMode="modal"
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
        closeOnClickOutside
        closeOnSuccess
        onSuccess={(result) => console.log(result)}
      />
    </>
  );
}

Loading State

The widget fetches configuration from your Magic dashboard before rendering. During this time, it returns null. To show a loading indicator, render the widget with isOpen={false} and wait for onReady:

JavaScript

import { useState } from 'react';
import { Magic } from 'magic-sdk';
import { MagicWidget, WalletKitExtension } from '@magic-ext/wallet-kit';

// Create Magic instance once, outside the component
const magic = new Magic('YOUR_API_KEY', {
  extensions: [new WalletKitExtension()],
});

function LoginPage() {
  const [isLoading, setIsLoading] = useState(true);
  const [isOpen, setIsOpen] = useState(false);

  const handleReady = () => {
    setIsLoading(false);
    setIsOpen(true);
  };

  return (
    <>
      {isLoading && <div>Loading...</div>}
      <MagicWidget
        isOpen={isOpen}
        onReady={handleReady}
        onSuccess={(result) => console.log(result)}
      />
    </>
  );
}

Create the Magic instance outside your component or use useMemo to prevent recreating it on every render.

Theming

The widget automatically applies your Magic dashboard theme settings including colors and light/dark mode. Configure these in your Magic Dashboard.

Embedded Wallets

Authentication

Wallets

SDKs

Blockchains

Wallet Kit

Compatibility

Use Cases

Getting Started

Installation

Usage

Configuration

Farcaster

WalletConnect

Account Switching

API Reference

Props

Examples

Loading State

Theming

Resources

​Compatibility

​Use Cases

​Getting Started

​Installation

​Usage

​Configuration

​Farcaster

​WalletConnect

​Account Switching

​API Reference

​Props

​Login Results

​Examples

​Modal Mode

​Loading State

​Theming

​Resources

Compatibility

Use Cases

Getting Started

Installation

Usage

Configuration

Farcaster

WalletConnect

Account Switching

API Reference

Props

Login Results

Examples

Modal Mode

Loading State

Theming

Resources