preference

Advanced configuration options to customize SDK behavior and authentication mode.

Type: object Required: No Default: See individual options below

Usage

// Wagmi
import { jaw } from '@jaw.id/wagmi';
import { Mode } from '@jaw.id/core';
import { ReactUIHandler } from '@jaw.id/ui';
 
const connector = jaw({
  apiKey: 'your-api-key',
  preference: {
    mode: Mode.AppSpecific,
    uiHandler: new ReactUIHandler(),
    showTestnets: true,
  },
});

// EIP-1193 Provider
import { JAW, Mode } from '@jaw.id/core';
import { ReactUIHandler } from '@jaw.id/ui';
 
const jaw = JAW.create({
  apiKey: 'your-api-key',
  preference: {
    mode: Mode.AppSpecific,
    uiHandler: new ReactUIHandler(),
    showTestnets: true,
  },
});

Options

mode

Authentication mode that determines where passkey operations occur.

Type: Mode.CrossPlatform | Mode.AppSpecific Default: Mode.CrossPlatform

Mode Comparison

Feature	Mode.CrossPlatform	Mode.AppSpecific
Passkey operations	On `keys.jaw.id` (popup)	Within your dApp
User experience	Redirects to popup	Stays in your app
Wallet reuse	✅ Universal	❌ App-specific only
Origin binding	`keys.jaw.id`	Your domain
Branding	JAW interface	Can use custom UI

CrossPlatform Mode

Passkey operations redirect to keys.jaw.id in a popup, enabling wallet reuse across multiple applications.

// Wagmi
import { jaw } from '@jaw.id/wagmi';
import { Mode } from '@jaw.id/core';
 
const connector = jaw({
  apiKey: 'your-api-key',
  preference: {
    mode: Mode.CrossPlatform,
  },
});

// EIP-1193 Provider
import { JAW, Mode } from '@jaw.id/core';
 
const jaw = JAW.create({
  apiKey: 'your-api-key',
  preference: {
    mode: Mode.CrossPlatform,
  },
});

How it works:

User clicks "Connect" → Popup opens to keys.jaw.id
Passkey operations happen on keys.jaw.id origin
Wallet can be reused across any app using CrossPlatform mode
Users see consistent experience across applications

Benefits:

Single wallet across multiple dApps
Seamless cross-application experience
Users don't recreate wallets for each app
Consistent authentication flow

AppSpecific Mode

Passkey operations stay within your dApp (no redirect). Wallets are specific to your application's origin.

How it works:

User clicks "Connect" → Modal opens within your dApp
Passkey operations happen on your dApp's origin
Passkeys are tied to your domain
Users never leave your application

Benefits:

Users never leave your dApp
Full control over UI/UX
White-label experience
No external redirects

Using ReactUIHandler (Recommended for React)

For React applications, install the @jaw.id/ui package which provides pre-built UI dialogs:

npm

npm install @jaw.id/ui @jaw.id/core

Then configure the SDK with ReactUIHandler:

// Wagmi
import { jaw } from '@jaw.id/wagmi';
import { Mode } from '@jaw.id/core';
import { ReactUIHandler } from '@jaw.id/ui';
 
const connector = jaw({
  apiKey: 'your-api-key',
  preference: {
    mode: Mode.AppSpecific,
    uiHandler: new ReactUIHandler(),
  },
});

// EIP-1193 Provider
import { JAW, Mode } from '@jaw.id/core';
import { ReactUIHandler } from '@jaw.id/ui';
 
const jaw = JAW.create({
  apiKey: 'your-api-key',
  preference: {
    mode: Mode.AppSpecific,
    uiHandler: new ReactUIHandler(),
  },
});

Custom UI Implementation

For non-React apps or fully custom UI, see the Custom UI Handler documentation.

serverUrl

URL to a passkey metadata server for managing passkey credentials (credential IDs, public keys, display names).

Type: string Default: 'https://api.justaname.id/wallet/v2/passkeys' Only works with: Mode.AppSpecific

// Wagmi
import { jaw } from '@jaw.id/wagmi';
import { Mode } from '@jaw.id/core';
import { ReactUIHandler } from '@jaw.id/ui';
 
const connector = jaw({
  apiKey: 'your-api-key',
  preference: {
    mode: Mode.AppSpecific,
    uiHandler: new ReactUIHandler(),
    serverUrl: 'https://custom-backend.example.com/passkeys',
  },
});

// EIP-1193 Provider
import { JAW, Mode } from '@jaw.id/core';
import { ReactUIHandler } from '@jaw.id/ui';
 
const jaw = JAW.create({
  apiKey: 'your-api-key',
  preference: {
    mode: Mode.AppSpecific,
    uiHandler: new ReactUIHandler(),
    serverUrl: 'https://custom-backend.example.com/passkeys',
  },
});

For details on running your own passkey server, see the Custom Passkey Server documentation.

showTestnets

Whether to include testnet networks in the available chains list.

Type: boolean Default: false

// Wagmi
import { jaw } from '@jaw.id/wagmi';
 
const connector = jaw({
  apiKey: 'your-api-key',
  preference: {
    showTestnets: true,
  },
});

// EIP-1193 Provider
import { JAW } from '@jaw.id/core';
 
const jaw = JAW.create({
  apiKey: 'your-api-key',
  preference: {
    showTestnets: true,
  },
});

uiHandler

Custom UI handler for rendering approval dialogs in app-specific mode. When provided, the SDK will use this handler instead of redirecting to external popups.

Type: UIHandler Default: undefined Only works with: Mode.AppSpecific

For custom UI implementations (non-React or advanced use cases), see the Custom UI Handler documentation.

Related Configuration

apiKey - API key for authentication
defaultChainId - Default network selection