Web5 Auth Modal

Social-only wallet connect for Web5 Nexus dapps — Google / Apple / email (and more) through BYOK backends. One branded modal; no MetaMask aggregator.

@web5nexus/authmodal-react@0.3.8@web5nexus/authmodal-core@0.3.2

Why Auth Modal?

Social-first UX — users pick a method; you plug in Web3Auth, Magic, Privy, Particle, or Para
One session — EVM via ChainRouter or custom RPC; optional BTC Taproot/SegWit when the adapter exports a key (Web3Auth)
Host branding — theme.appName, theme.logo, colors, layout — “Powered by Web5 Nexus” is always shown
Vite-ready — each adapter ships /vite helpers (see below)

For a Bitcoin-first product (solo modal, PSBT, Ordinals), use @web5nexus/authmodal-bitcoin instead of (or alongside) Connect Modal BTC derive.

Install

npm i @web5nexus/authmodal-react @web5nexus/authmodal-core \
  @web5nexus/authmodal-web3auth @web5nexus/authmodal-magic \
  @web5nexus/authmodal-privy @web5nexus/authmodal-particle @web5nexus/authmodal-para

Import styles once:

import '@web5nexus/authmodal-react/styles.css'

BYOK env

Env	Purpose
`NEXT_PUBLIC_W3A_CLIENT_ID` / `VITE_W3A_CLIENT_ID`	Web3Auth client id
`NEXT_PUBLIC_MAGIC_API_KEY` / `VITE_MAGIC_API_KEY`	Magic publishable key
`NEXT_PUBLIC_PRIVY_APP_ID`	Privy app id
`NEXT_PUBLIC_PARTICLE_*`	Particle project/client keys
`NEXT_PUBLIC_PARA_API_KEY`	Para API key
`NEXT_PUBLIC_CHAINROUTER_API_KEY`	Optional managed EVM RPC

End users never enter these keys. See Adapters for capability details.

Quick start

import '@web5nexus/authmodal-react/styles.css'
import { AuthModalProvider, ConnectButton } from '@web5nexus/authmodal-react'
import { web3auth } from '@web5nexus/authmodal-web3auth'
import { magic } from '@web5nexus/authmodal-magic'
import { privy } from '@web5nexus/authmodal-privy'
 
const adapters = [
  web3auth({ clientId: process.env.NEXT_PUBLIC_W3A_CLIENT_ID! }),
  magic({ apiKey: process.env.NEXT_PUBLIC_MAGIC_API_KEY! }),
  privy({ appId: process.env.NEXT_PUBLIC_PRIVY_APP_ID! }),
]
 
export default function App() {
  return (
    <AuthModalProvider
      adapters={adapters}
      chains={[1, 8453]}
      transport={{
        mode: 'chainrouter',
        apiKey: process.env.NEXT_PUBLIC_CHAINROUTER_API_KEY!,
        chainId: 1,
      }}
      bitcoin={{ enabled: true, network: 'mainnet', prefer: 'taproot' }}
      preferredAdapters={['web3auth', 'magic', 'privy']}
      theme={{
        mode: 'dark',
        layout: 'auto',
        size: 'md',
        accentColor: '#3DDC97',
        appName: 'My App',
        subtitle: 'Login to continue.',
        logo: 'https://example.com/logo.png',
      }}
    >
      <ConnectButton />
    </AuthModalProvider>
  )
}

Theme

Field	Notes
`mode`	`light` \| `dark` \| `auto`
`layout`	`wide` \| `compact` \| `solo` \| `auto` (1 adapter → solo; 2+ → wide / compact by viewport)
`size`	`sm` \| `md` \| `lg` — widths: solo 340/380/420; wide 380/520/720
`accentColor` / `accentTextColor`	Primary CTA colors
`surfaceColor` / `textColor` / `mutedColor` / `borderColor` / `overlayColor`	Optional overrides
`appName` / `logo` / `subtitle`	Your product brand
`borderRadius` / `fontFamily`	Optional

Layouts: solo is email + social icon row (single-provider chrome). wide / compact show the providers aside + full method list for the selected adapter. Preview every size in the Playground.

Not configurable: modal footer always shows “Powered by Web5 Nexus” (with logo) linking to web5.nexus. Fields title, showPoweredBy, and poweredByUrl are ignored.

Vite helpers

Import the Web3Auth polyfill first, then merge adapter Vite helpers (see the Auth Modal demo vite.config.ts):

import '@web5nexus/authmodal-web3auth/polyfill'
 
import {
  web3authOptimizeDeps,
  web3authProcessPolyfillPlugin,
  web3authViteAliases,
} from '@web5nexus/authmodal-web3auth/vite'
import { magicOptimizeDeps } from '@web5nexus/authmodal-magic/vite'
import { privyOptimizeDeps } from '@web5nexus/authmodal-privy/vite'
import particleWasmPlugin, { particleOptimizeDeps } from '@web5nexus/authmodal-particle/vite'
import { paraOptimizeDeps } from '@web5nexus/authmodal-para/vite'

Hooks

Hook	Role
`useAccount`	address, user, connected, adapterId
`useChain`	chainId, chains, setChain
`useBitcoin`	`p2tr` / `p2wpkh` when BTC derive is enabled + key export
`useConnect` / `useDisconnect`	Programmatic connect / logout (no modal required)
`useAuthModal`	Client + `openModal`

Custom login UI without ConnectButton: see Headless / custom UI (useConnect, createAuthModal, per-provider examples).

B2B CRM bridge (App pk_, Users, MAW): Marketing Hub (@web5nexus/authmodal-marketing).

Bitcoin via Connect Modal vs solo package

	Connect Modal `bitcoin: { enabled: true }`	`@web5nexus/authmodal-bitcoin`
UX	After EVM social login	Dedicated Bitcoin connect modal
Key source	Adapter key export (Web3Auth)	Web3Auth key export
Address types	Prefer taproot / segwit via core	Taproot, SegWit, Legacy, Nested SegWit
PSBT / Ordinals / Runes	Limited / stubs	First-class hooks

→ Full Bitcoin docs: Bitcoin Wallet

Try it

Loading Connect lab…

Also see the full Playground.

Get Started Headless / custom UI