# JAW Configuration Reference > Configuration options for JAW - applies to both core and wagmi integrations. **This file is self-contained.** You have everything needed to help with this topic. Do NOT fetch other llms-*.txt files unless the user explicitly asks about a different topic. ## Key Info - **Package:** `@jaw.id/wagmi or @jaw.id/core` - **Dashboard:** https://dashboard.jaw.id - **Docs:** https://docs.jaw.id ## Quick Example ```typescript jaw({ apiKey: 'YOUR_API_KEY', // Required - from dashboard.jaw.id appName: 'My App', // Required - shown in passkey prompts mode: 'crossPlatform', // Optional - 'crossPlatform' | 'appSpecific' paymasterUrl: '...', // Optional - for gas sponsoring ensConfig: { ... }, // Optional - for ENS subnames }) ``` --- ## apiKey Source: https://docs.jaw.id/configuration/apiKey ## apiKey Your JAW API key for authentication with JAW services. **Type:** `string` **Required:** In [app-specific mode](/configuration/mode/app-specific). Optional in cross-platform mode, which is the default. In cross-platform mode the SDK sends whatever it has and the backend decides whether to answer. With a key, the request is attributed to the project that key belongs to, and the allowed domains below are what the key is checked against. Without a key, the caller is identified by the origin the request comes from, and only origins registered with JustaName are served, so ask the team to register yours before dropping the option. App-specific mode always needs a key, because it hands one to the UI handler your application implements. `JAW.create()` rejects an app-specific configuration without one. ### Usage #### With Wagmi (Recommended) ```typescript import { jaw } from '@jaw.id/wagmi'; const connector = jaw({ apiKey: 'your-api-key-here', }); ``` #### With Provider Directly ```typescript import { JAW } from '@jaw.id/core'; const jaw = JAW.create({ apiKey: 'your-api-key-here', }); ``` #### Without a key ```typescript const connector = jaw({ appName: 'My DApp' }); ``` Requests then carry no `api-key` parameter, and the origin your application runs on is what names it. An origin nobody registered is refused. ### How to Get an API Key 1. Visit the [JAW Dashboard](https://dashboard.jaw.id/) 2. Create a new project or select an existing one 3. Navigate to the API Keys section 4. Generate a new API key ### Setting Up Allowed Domains For security, you must configure which domains are allowed to use your API key: 1. In the [JAW Dashboard](https://dashboard.jaw.id/), go to your api-key settings 2. Find the **Allowed Domains** section 3. Add the domains where your application will run: * `localhost` for local development * `yourdomain.com` for production * `staging.yourdomain.com` for staging environments Requests from domains not in your allowed list will be rejected. ### Related Configuration * [appName](/configuration/appName) - Application name * [mode](/configuration/mode) - Authentication mode options ## appLogoUrl Source: https://docs.jaw.id/configuration/appLogoUrl ## appLogoUrl URL to your application's logo image. Displayed alongside your app name in the authentication interface. **Type:** `string | null` **Required:** No **Default:** `null` (uses default icon) ### Usage #### With Wagmi (Recommended) ```typescript import { jaw } from '@jaw.id/wagmi'; const connector = jaw({ apiKey: 'your-api-key', appName: 'My DApp', appLogoUrl: 'https://my-dapp.com/logo.png', }); ``` #### With Provider Directly ```typescript import { JAW } from '@jaw.id/core'; const jaw = JAW.create({ apiKey: 'your-api-key', appName: 'My DApp', appLogoUrl: 'https://my-dapp.com/logo.png', }); ``` ### Where It Appears Your app logo is shown to users in: * Authentication popup header * Transaction approval screens * Permission grant dialogs ### Image Requirements * **Format:** PNG, JPG, or SVG * **Size:** 200x200px minimum (square recommended) * **Protocol:** Must use HTTPS ### Related Configuration * [appName](/configuration/appName) - Application name * [apiKey](/configuration/apiKey) - API key for authentication ## appName Source: https://docs.jaw.id/configuration/appName ## appName The name of your application, displayed to users during authentication and transaction signing. **Type:** `string` **Required:** No **Default:** `'DApp'` ### Usage #### With Wagmi (Recommended) ```typescript import { jaw } from '@jaw.id/wagmi'; const connector = jaw({ apiKey: 'your-api-key', appName: 'My Awesome DApp', }); ``` #### With Provider Directly ```typescript import { JAW } from '@jaw.id/core'; const jaw = JAW.create({ apiKey: 'your-api-key', appName: 'My Awesome DApp', }); ``` ### Where It Appears Your app name is shown to users in: * Authentication popup header * Transaction approval screens * Permission grant dialogs ### Related Configuration * [appLogoUrl](/configuration/appLogoUrl) - Application logo * [apiKey](/configuration/apiKey) - API key for authentication ## defaultChainId Source: https://docs.jaw.id/configuration/defaultChainId ## defaultChainId The default blockchain network to connect to when the SDK initializes. **Type:** `number` **Required:** No **Default:** `1` (Ethereum Mainnet) ### Usage #### With Wagmi (Recommended) ```typescript import { jaw } from '@jaw.id/wagmi'; const connector = jaw({ apiKey: 'your-api-key', defaultChainId: 1, // Mainnet }); ``` #### With Provider Directly ```typescript import { JAW } from '@jaw.id/core'; const jaw = JAW.create({ apiKey: 'your-api-key', defaultChainId: 1, // Mainnet }); ``` ### Using Testnets To use a testnet as the default chain, enable `showTestnets` in preferences: #### With Wagmi (Recommended) ```typescript import { jaw } from '@jaw.id/wagmi'; const connector = jaw({ apiKey: 'your-api-key', defaultChainId: 84532, // Base Sepolia preference: { showTestnets: true, }, }); ``` #### With Provider Directly ```typescript import { JAW } from '@jaw.id/core'; const jaw = JAW.create({ apiKey: 'your-api-key', defaultChainId: 84532, // Base Sepolia preference: { showTestnets: true, }, }); ``` ### Related * [Supported Networks](/supported-networks) - Full list of supported chains * [mode](/configuration/mode) - Authentication mode options * [wallet\_switchEthereumChain](/api-reference/wallet_switchEthereumChain) - Switch networks programmatically ## ens Source: https://docs.jaw.id/configuration/ens ## ens ENS domain used to issue subnames to users during authentication. **Type:** `string` **Required:** No :::warning **Important:** Configuring your ENS at the [JAW Dashboard](https://dashboard.jaw.id/) is a pre-requirement for subname issuance and management. ::: ### Usage #### With Wagmi (Recommended) ```typescript import { jaw } from '@jaw.id/wagmi'; const connector = jaw({ apiKey: 'your-api-key', ens: 'myapp.eth', }); ``` #### With Provider Directly ```typescript import { JAW } from '@jaw.id/core'; const jaw = JAW.create({ apiKey: 'your-api-key', ens: 'myapp.eth', }); ``` ### Description When configured, users can receive a subname under your ENS domain during the authentication flow. For example, if your `ens` is set to `myapp.eth`, users can get subnames like `alice.myapp.eth`. By default, subname will be active on all supported networks. To attach text records on creation, please check the [wallet\_connect](/api-reference/wallet_connect) `subnameTextRecords` capability. ### Related Configuration * [apiKey](/configuration/apiKey) - API key for authentication * [wallet\_connect](/api-reference/wallet_connect) - Add subname text records using wallet\_connect capability ## Configuration Source: https://docs.jaw.id/configuration/index ## Configuration Configuration options for the JAW SDK. These options apply to both the **Wagmi connector** and the **direct provider**. ### Usage #### With Wagmi (Recommended) ```typescript import { jaw } from '@jaw.id/wagmi'; const connector = jaw({ apiKey: 'your-api-key', appName: 'My DApp', appLogoUrl: 'https://my-dapp.com/logo.png', defaultChainId: 1, ens: 'myapp.eth', preference: { showTestnets: true, }, paymasters: { 1: { url: 'https://paymaster.example.com/mainnet' }, }, }); ``` #### With Provider Directly ```typescript import { JAW } from '@jaw.id/core'; const jaw = JAW.create({ apiKey: 'your-api-key', appName: 'My DApp', appLogoUrl: 'https://my-dapp.com/logo.png', defaultChainId: 1, ens: 'myapp.eth', preference: { showTestnets: true, }, paymasters: { 1: { url: 'https://paymaster.example.com/mainnet' }, }, }); ``` ### Configuration Options #### Core Parameters \| Parameter | Type | Required | Description | \| ----------------------------------------------- | -------------------------------------------------------------------- | -------- | ---------------------------------------- | \| [apiKey](/configuration/apiKey) | `string` | Yes | API key for JAW services authentication | \| [appName](/configuration/appName) | `string` | No | Application name displayed to users | \| [appLogoUrl](/configuration/appLogoUrl) | `string \| null` | No | URL to application logo image | \| [ens](/configuration/ens) | `string` | No | ENS domain for issuing subnames | \| [defaultChainId](/configuration/defaultChainId) | `number` | No | Default blockchain network | \| [preference](/configuration/mode) | `object` | No | Advanced SDK behavior options | \| [paymasters](/configuration/paymasters) | `Record }>` | No | Custom paymaster configuration per chain | ### Preference Options The `preference` object contains advanced configuration: \| Option | Type | Default | Description | \| ------------------------------------------------------- | ------------------------------------------ | -------------------- | ---------------------------------------------------------------------------------------------- | \| [mode](/configuration/mode) | `Mode.CrossPlatform` | `Mode.AppSpecific` | `Mode.CrossPlatform` | Authentication mode | \| [uiHandler](/configuration/mode/app-specific#uihandler) | `UIHandler` | `undefined` | UI handler for rendering dialogs (required when mode is `Mode.AppSpecific`) | \| showTestnets | `boolean` | `false` | Include testnet networks (see [Supported Networks](/supported-networks)) | \| authTTL | `number` | `86400` | Session cache TTL in seconds. Set to `0` to disable caching (require auth on every page load). | [Learn more about authentication modes →](/configuration/mode) ### Return Value #### Wagmi Connector The `jaw()` function returns a Wagmi `Connector` that can be used in your wagmi config. ```typescript import { createConfig } from 'wagmi'; import { jaw } from '@jaw.id/wagmi'; const config = createConfig({ connectors: [jaw({ apiKey: 'your-api-key' })], // ... }); ``` #### Provider The `JAW.create()` function returns an object with: ##### provider **Type:** `ProviderInterface` An EIP-1193 compatible Ethereum provider for making RPC requests. ```typescript const jaw = JAW.create({ apiKey: 'your-api-key' }); const accounts = await jaw.provider.request({ method: 'wallet_connect', }); ``` ##### disconnect() **Type:** `() => Promise` Method to disconnect the current session and clean up resources. ```typescript await jaw.disconnect(); ``` ### Minimal Configuration Every option is optional in cross-platform mode, the default. A request without an [apiKey](/configuration/apiKey) is identified by the origin it comes from, which JustaName has to have registered beforehand. ```typescript // Wagmi const connector = jaw({ apiKey: 'your-api-key' }); // Provider const jaw = JAW.create({ apiKey: 'your-api-key' }); ``` [App-specific mode](/configuration/mode/app-specific) is the exception: it requires `apiKey` and a `uiHandler`. ### Related * [Wagmi Integration](/wagmi) - Using with Wagmi * [Provider API](/api-reference) - Direct provider methods * [Supported Networks](/supported-networks) - Available chains ## AppSpecific Mode Source: https://docs.jaw.id/configuration/mode/app-specific ## AppSpecific Mode Passkey operations stay within your dApp with no external redirects. Wallets are specific to your application's origin. ### Usage AppSpecific mode requires a `uiHandler` to render authentication dialogs within your app. #### Using ReactUIHandler (Recommended for React) For React applications, install the `@jaw.id/ui` package which provides pre-built UI dialogs: :::code-group ```bash [npm] npm install @jaw.id/wagmi @jaw.id/ui ``` ```bash [pnpm] pnpm add @jaw.id/wagmi @jaw.id/ui ``` ```bash [yarn] yarn add @jaw.id/wagmi @jaw.id/ui ``` ```bash [bun] bun add @jaw.id/wagmi @jaw.id/ui ``` ::: Then configure the SDK with `ReactUIHandler`: #### With Wagmi (Recommended) ```typescript 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(), }, }); ``` #### With Provider Directly ```typescript 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](/advanced/custom-ui-handler) documentation. ### How It Works 1. User clicks "Connect" in your dApp 2. A modal opens within your application (no popup/redirect) 3. User authenticates with their passkey on your domain's origin 4. Modal closes and user is connected 5. The wallet is tied to your application's origin ### Benefits * **Users never leave your dApp** - No popups or redirects * **Full control over UI/UX** - Customize the authentication experience * **White-label experience** - Your branding throughout * **Origin-bound security** - Passkeys are tied to your domain ### User Flow ``` Your dApp │ │ 1. User clicks Connect │ │ 2. Modal opens (within your app) │ ┌─────────────────────────┐ │ │ Authentication UI │ │ │ (ReactUIHandler or │ │ │ custom uiHandler) │ │ └─────────────────────────┘ │ │ 3. User authenticates with passkey │ │ 4. Modal closes │ │ 5. User connected └────────────────────────────────── ``` ### uiHandler The `uiHandler` is responsible for rendering approval dialogs for wallet operations (connect, sign, transact, etc.). **Type:** `UIHandler` **Required:** Yes (for AppSpecific mode) #### ReactUIHandler For React applications, `ReactUIHandler` from `@jaw.id/ui` provides pre-built, styled dialogs that handle all wallet operations: * Onboarding / Connect * Message signing * Typed data signing (EIP-712) * Transaction approval * Permission management ```typescript import { ReactUIHandler } from '@jaw.id/ui'; const uiHandler = new ReactUIHandler(); ``` #### Custom UIHandler For non-React apps or when you need complete control over the UI, implement the `UIHandler` interface: ```typescript interface UIHandler { init(config: UIHandlerConfig): void; request(method: string, params: unknown): Promise; canHandle(method: string): boolean; cleanup(): void; } ``` See the [Custom UI Handler](/advanced/custom-ui-handler) documentation for the full interface specification and implementation examples. ### Related * [Mode Overview](/configuration/mode) - Compare all authentication modes * [CrossPlatform Mode](/configuration/mode/cross-platform) - Enable wallet reuse across apps * [Custom UI Handler](/advanced/custom-ui-handler) - Build your own authentication UI ## CrossPlatform Mode Source: https://docs.jaw.id/configuration/mode/cross-platform ## CrossPlatform Mode Passkey operations redirect to `keys.jaw.id` in a popup, enabling wallet reuse across multiple applications. This is the default mode. ### Usage #### With Wagmi (Recommended) ```typescript import { jaw } from '@jaw.id/wagmi'; import { Mode } from '@jaw.id/core'; const connector = jaw({ apiKey: 'your-api-key', preference: { mode: Mode.CrossPlatform, }, }); ``` #### With Provider Directly ```typescript import { JAW, Mode } from '@jaw.id/core'; const jaw = JAW.create({ apiKey: 'your-api-key', preference: { mode: Mode.CrossPlatform, }, }); ``` :::info Since CrossPlatform is the default mode, you can omit the `preference` object entirely if you don't need to configure other options. ::: ### How It Works 1. User clicks "Connect" in your dApp 2. A popup opens to `keys.jaw.id` 3. User authenticates with their passkey on the `keys.jaw.id` origin 4. Popup closes and user is connected to your dApp 5. The same wallet can be used across any app using CrossPlatform mode ### Benefits * **Single wallet across multiple dApps** - Users don't need to create separate wallets for each application * **Seamless cross-application experience** - Connect once, use everywhere * **Consistent authentication flow** - Users see the same familiar interface * **No UI implementation required** - Authentication UI is handled by JAW ### User Flow ``` Your dApp keys.jaw.id (popup) │ │ │ 1. User clicks Connect │ │ ─────────────────────────────> │ │ │ 2. Popup opens │ │ │ 3. User authenticates │ with passkey │ │ │ 4. Wallet address returned │ │ <───────────────────────────── │ │ │ 5. User connected │ └──────────────────────────────┘ ``` ### Related * [Mode Overview](/configuration/mode) - Compare all authentication modes * [AppSpecific Mode](/configuration/mode/app-specific) - Keep users within your app ## mode Source: https://docs.jaw.id/configuration/mode/index ## mode Authentication mode that determines where passkey operations occur. **Type:** `Mode.CrossPlatform` | `Mode.AppSpecific` **Default:** `Mode.CrossPlatform` ### Mode Comparison \| Feature | CrossPlatform | 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 | Custom UI supported | :::warning **Important:** Passkeys are always stored by the browser/device (not on any server). The mode determines where passkey operations happen and whether wallets can be reused across applications. ::: ### Choosing a Mode #### Use CrossPlatform (Default) when: * You want users to reuse their wallet across multiple dApps * You prefer a consistent, maintained authentication UI * Quick integration is a priority #### Use AppSpecific when: * You want users to stay entirely within your application * You need full control over the UI/UX * You're building a white-label experience * Wallet portability across apps is not needed ### Related * [CrossPlatform Mode](/configuration/mode/cross-platform) - Detailed setup and usage * [AppSpecific Mode](/configuration/mode/app-specific) - Detailed setup and usage ## paymasters Source: https://docs.jaw.id/configuration/paymasters ## paymasters Custom paymaster configuration for fully sponsoring gas fees on different blockchain networks. **Type:** `Record }>` **Required:** No **Default:** `undefined` :::info\[Gas Payment Options] JAW SDK supports multiple ways to handle transaction gas fees: \| Option | Who Pays | Configuration | \| -------------------- | ---------------------- | --------------------------------------------------- | \| **Native (ETH)** | User | Default behavior | \| **ERC-20 Tokens** | User (with USDC, etc.) | Built-in — user selects token in transaction dialog | \| **Full Sponsorship** | You (dApp) | Requires `paymasters` config (this page) | This page covers **full sponsorship** where you pay gas on behalf of users. ::: ### Usage #### With Wagmi (Recommended) ```typescript import { jaw } from '@jaw.id/wagmi'; const connector = jaw({ apiKey: 'your-api-key', paymasters: { 1: { url: 'https://paymaster.example.com/mainnet' }, 8453: { url: 'https://paymaster.example.com/base', context: { sponsorshipPolicyId: 'sp_my_policy' }, }, }, }); ``` #### With Provider Directly ```typescript import { JAW } from '@jaw.id/core'; const jaw = JAW.create({ apiKey: 'your-api-key', paymasters: { 1: { url: 'https://paymaster.example.com/mainnet' }, 8453: { url: 'https://paymaster.example.com/base', context: { sponsorshipPolicyId: 'sp_my_policy' }, }, }, }); ``` ### Description Paymasters are services that sponsor transaction gas fees, enabling gasless transactions for your users. The `paymasters` configuration allows you to specify custom paymaster endpoints and context for each supported network. **Benefits:** * **Gasless Transactions**: Users don't need native tokens to pay gas * **Better UX**: Remove friction from onboarding * **Flexible Sponsorship**: Control which transactions to sponsor via context/policies * **Cost Management**: Use your own paymaster infrastructure #### Sponsorship Levels You can configure sponsorship at two levels: ##### Global (SDK Config) Configure paymasters in the SDK initialization to sponsor all transactions by default: ```typescript const connector = jaw({ apiKey: 'your-api-key', paymasters: { 8453: { url: 'https://paymaster.example.com/base' }, }, }); ``` ##### Per-Call Override Override or specify paymasters for individual transactions using EIP-5792 capabilities: ```typescript await provider.request({ method: 'wallet_sendCalls', params: [ { calls: [{ to: '0x...', value: '0x0', data: '0x...' }], capabilities: { paymasterService: { url: 'https://different-paymaster.com', context: { sponsorshipPolicyId: 'special-policy' }, }, }, }, ], }); ``` **Priority:** Per-call `capabilities.paymasterService` > Global `paymasters` config > No sponsorship ### Important Requirements #### EntryPoint Version JAW SDK **only supports EntryPoint v0.8** (ERC-4337 v0.8). Your paymaster service must be compatible with: * [EntryPoint v0.8](https://github.com/eth-infinitism/account-abstraction/releases/tag/v0.8.0) * [EIP-7677](https://eips.ethereum.org/EIPS/eip-7677) Paymaster Web Service Capability #### Compatible Paymaster Providers Works with any EIP-7677 compliant paymaster that supports EntryPoint v0.8: * **[Pimlico](https://dashboard.pimlico.io/)** * **[Etherspot](https://developer.etherspot.io/dashboard)** ### Configuration Format ```typescript paymasters: { [chainId: number]: { url: string; // Paymaster service URL (required) context?: Record; // Additional context sent with requests (optional) } } ``` #### Properties \| Property | Type | Required | Description | \| --------- | ------------------------- | -------- | ------------------------------------------------------------------------ | \| `url` | `string` | Yes | The paymaster service endpoint URL | \| `context` | `Record` | No | Additional context passed to the paymaster (e.g., sponsorship policy ID) | ### Examples #### Basic Configuration ```typescript import { jaw } from '@jaw.id/wagmi'; const connector = jaw({ apiKey: 'your-api-key', paymasters: { 8453: { url: 'https://paymaster.etherspot.io/base' }, }, }); ``` #### With Sponsorship Policy ```typescript import { jaw } from '@jaw.id/wagmi'; const connector = jaw({ apiKey: 'your-api-key', paymasters: { 8453: { url: 'https://paymaster.etherspot.io/base', context: { sponsorshipPolicyId: 'sp_my_policy_id', }, }, }, }); ``` #### Multiple Networks ```typescript import { jaw } from '@jaw.id/wagmi'; const connector = jaw({ apiKey: 'your-api-key', paymasters: { 1: { url: 'https://pm.etherspot.io/eth' }, // Ethereum Mainnet 10: { url: 'https://pm.etherspot.io/op' }, // Optimism 8453: { url: 'https://pm.etherspot.io/base' }, // Base 42161: { url: 'https://pm.etherspot.io/arb' }, // Arbitrum 84532: { url: 'https://api.pimlico.io/v2/84532/rpc?apikey=YOUR_API_KEY', // Base Sepolia context: { sponsorshipPolicyId: 'sp_test_policy' }, }, }, }); ``` ### Paymaster Services #### Recommended Provider * **[Etherspot](https://developer.etherspot.io/dashboard)** * **[Pimlico](https://dashboard.pimlico.io/)** #### Other Compatible Providers Ensure any provider you use supports: * EntryPoint v0.8 * EIP-7677 Paymaster Web Service Capability ### Related * [eth\_sendTransaction](/api-reference/eth_sendTransaction) - Sponsor Transactions * [wallet\_sendCalls](/api-reference/wallet_sendCalls) - Sponsor Calls Bundle ## theme Source: https://docs.jaw.id/configuration/theme ## theme Customize the appearance of SDK UI dialogs (onboarding, signing, transactions, permissions). **Type:** `JawTheme` **Required:** No **Default:** `{ mode: 'auto', borderRadius: 'md', fontStack: 'system' }` :::info Theming applies to **both** authentication modes. Pass `theme` in the constructor (the `jaw()` connector or `JAW.create()`) and it travels to the wallet dialog automatically: * **AppSpecific** — dialogs are rendered by `ReactUIHandler` inside your app and themed directly in the host DOM. * **CrossPlatform** — the theme rides the connection handshake to the keys.jaw\.id dialog (embedded iframe or popup), so it re-themes to match your app instead of using its own default styling. The simple props and the semantic `colors` palette below work in both modes. The Layer 3 raw-CSS escape hatch only reaches **AppSpecific** dialogs, since the cross-platform dialog runs in a separate origin. ::: ### Quick Start Pass `theme` in the constructor. It works the same way in both authentication modes. #### With Wagmi (Recommended) ```typescript import { jaw } from '@jaw.id/wagmi'; const connector = jaw({ apiKey: 'your-api-key', appName: 'My App', theme: { mode: 'dark', accentColor: '#6366f1', borderRadius: 'lg', }, }); ``` #### With Provider Directly ```typescript import { JAW } from '@jaw.id/core'; const jaw = JAW.create({ apiKey: 'your-api-key', theme: { mode: 'dark', accentColor: '#6366f1', borderRadius: 'lg', }, }); ``` ### Theme Properties \| Property | Type | Default | Description | \| ----------------------- | --------------------------------- | ------------- | -------------------------------------------------------------------------------- | \| `mode` | `'light' \| 'dark' \| 'auto'` | `'auto'` | Color scheme. `'auto'` follows the user's system preference. | \| `accentColor` | `string` | — | Primary color as hex (e.g. `'#6366f1'`). Applied to buttons, focus rings, links. | \| `accentColorForeground` | `string` | auto-detected | Text color on accent backgrounds. Auto-detected from luminance if omitted. | \| `borderRadius` | `'sm' \| 'md' \| 'lg'` | `'md'` | Corner rounding for cards, buttons, and inputs. | \| `fontStack` | `'system' \| 'rounded' \| 'mono'` | `'system'` | Font family preset. | \| `colors` | `JawThemeColors` | — | Semantic palette overrides as plain hex colors (see below). | ### Three Layers of Customization #### Layer 1: Simple Props (recommended) Covers 90% of use cases. Pass `mode`, `accentColor`, and `borderRadius`. ```typescript const jaw = JAW.create({ apiKey: 'your-api-key', theme: { mode: 'dark', accentColor: '#e11d48', // Rose borderRadius: 'lg', }, }); ``` #### Layer 2: Semantic Colors (full re-skins) For a complete custom look, pass a `colors` palette — every value is an ordinary hex color. Any key you omit keeps its default, and explicit colors win over `accentColor`. ```typescript const jaw = JAW.create({ apiKey: 'your-api-key', theme: { mode: 'dark', borderRadius: 'lg', colors: { background: '#0E2F28', card: '#123A31', foreground: '#ECFDF5', primary: '#34E3A0', primaryForeground: '#052E22', muted: '#17453B', mutedForeground: '#93C0B1', border: '#1F5449', // Status colors are themeable too warning: '#F5C24B', positive: '#34E3A0', negative: '#F0836E', }, }, }); ``` The full list of keys is in the [Color Reference](#color-reference) below. :::note `colors` works in **both modes** and every key is overridable. ::: #### Layer 3: Raw CSS (escape hatch) Target `[data-jaw-modal-container]` in your own CSS. No SDK changes needed. This only applies to **AppSpecific** mode — the cross-platform dialog is served from keys.jaw\.id in a separate origin, so use the simple props or `colors` to theme it. ```css [data-jaw-modal-container] { /* Color variables take bare OKLCH channels ("L C H"), not oklch(...) or hex */ --jaw-color-primary: 0.65 0.25 270; --jaw-color-background: 0.12 0.01 260; font-family: 'Inter', sans-serif; } ``` ### Passing Theme to ReactUIHandler You can pass the theme in two places. Both work, and the constructor theme takes precedence: :::code-group ```typescript [Via JAW.create()] // Theme flows through SDK -> UIHandler.init() const jaw = JAW.create({ apiKey: 'your-api-key', theme: { mode: 'dark', accentColor: '#6366f1' }, preference: { mode: Mode.AppSpecific, uiHandler: new ReactUIHandler(), }, }); ``` ```typescript [Via ReactUIHandler constructor] // Constructor theme takes precedence over JAW.create() theme const jaw = JAW.create({ apiKey: 'your-api-key', preference: { mode: Mode.AppSpecific, uiHandler: new ReactUIHandler({ theme: { mode: 'dark', accentColor: '#6366f1' }, }), }, }); ``` ::: ### Auto Mode (System Preference) When `mode` is `'auto'` (the default), the SDK detects the user's system color scheme and switches dynamically. If the user changes their OS dark/light preference while a dialog is open, it updates live. ```typescript theme: { mode: 'auto'; } // follows system preference ``` ### Updating the Theme at Runtime If your app toggles light/dark after the provider is created, call `setTheme()` to push the new theme to the live dialog without rebuilding the provider or reconnecting. In CrossPlatform mode this re-themes the embedded keys.jaw\.id dialog in place. :::code-group ```typescript [Core SDK] // jaw is the object returned by JAW.create() jaw.provider.setTheme({ mode: 'dark', accentColor: '#6366f1' }); ``` ```tsx [Wagmi] import { useConnect } from 'wagmi'; import type { JawTheme } from '@jaw.id/core'; const { connectors } = useConnect(); const jaw = connectors.find((c) => c.id === 'jaw') as { setTheme?: (theme: JawTheme | undefined) => void } | undefined; jaw?.setTheme?.({ mode: 'dark', accentColor: '#6366f1' }); ``` ::: ### Color Reference Every key you can set in `colors`, with the CSS variable it maps to (only needed for the raw-CSS escape hatch). \| Key | CSS variable | Description | \| ----------------------- | ------------------------------------ | --------------------------------------- | \| `background` | `--jaw-color-background` | Dialog backdrop | \| `foreground` | `--jaw-color-foreground` | Primary text | \| `card` | `--jaw-color-card` | Card/section backgrounds | \| `cardForeground` | `--jaw-color-card-foreground` | Card text | \| `popover` | `--jaw-color-popover` | Popover backgrounds | \| `popoverForeground` | `--jaw-color-popover-foreground` | Popover text | \| `primary` | `--jaw-color-primary` | Buttons, links, key actions | \| `primaryForeground` | `--jaw-color-primary-foreground` | Text on primary backgrounds | \| `secondary` | `--jaw-color-secondary` | Secondary backgrounds | \| `secondaryForeground` | `--jaw-color-secondary-foreground` | Secondary text | \| `muted` | `--jaw-color-muted` | Muted/disabled backgrounds | \| `mutedForeground` | `--jaw-color-muted-foreground` | Muted text | \| `accent` | `--jaw-color-accent` | Hover/active state backgrounds | \| `accentForeground` | `--jaw-color-accent-foreground` | Accent text | \| `border` | `--jaw-color-border` | Borders and dividers | \| `input` | `--jaw-color-input` | Input field borders | \| `ring` | `--jaw-color-ring` | Focus ring color | \| `destructive` | `--jaw-color-destructive` | Error/danger backgrounds | \| `destructiveForeground` | `--jaw-color-destructive-foreground` | Error/danger text | \| `destructiveHover` | `--jaw-color-destructive-hover` | Destructive button hover state | \| `success` | `--jaw-color-success` | Success state | \| `successForeground` | `--jaw-color-success-foreground` | Success text | \| `warning` | `--jaw-color-warning` | Warning state | \| `warningForeground` | `--jaw-color-warning-foreground` | Warning text | \| `info` | `--jaw-color-info` | Info state | \| `infoForeground` | `--jaw-color-info-foreground` | Info text | \| `positive` | `--jaw-color-positive` | Incoming asset amounts ("You get") | \| `negative` | `--jaw-color-negative` | Outgoing asset amounts ("You send") | \| `scrim` | `--jaw-color-scrim` | Modal overlay backdrop | \| `halo` | `--jaw-color-halo` | Animated edge glow on the dialog card | \| `identiconTile` | `--jaw-color-identicon-tile` | Tile behind account identicons | \| `identiconRing` | `--jaw-color-identicon-ring` | Hairline ring around the identicon tile | \| `shadow` | `--jaw-color-shadow` | Elevation shadow color | Border radius and font come from the `borderRadius` and `fontStack` props (CSS variables `--jaw-radius` and `--jaw-font-family`). ### How Accent Color Works When you set `accentColor`, the SDK colors the primary buttons, links, hover tints, and focus rings from it, and picks a contrasting text color automatically. Dark accents are lightened slightly in dark mode for visibility. To override the auto-picked text color, pass `accentColorForeground`: ```typescript theme: { accentColor: '#1e1e2e', accentColorForeground: '#ffffff', // force white text } ``` ### Related Configuration * [mode](/configuration/mode) - Authentication mode (theming works in both AppSpecific and CrossPlatform) * [AppSpecific](/configuration/mode/app-specific) - AppSpecific mode setup * [appName](/configuration/appName) - App name shown in dialogs * [appLogoUrl](/configuration/appLogoUrl) - App logo shown in dialogs ## transportMode Source: https://docs.jaw.id/configuration/transportMode ## transportMode :::warning **Want the embedded dialog on Safari & Firefox?** These browsers can't verify the iframe's visibility (no IntersectionObserver v2), so by default JAW falls back to a popup there to prevent clickjacking. To enable the embedded dialog for your site on those browsers, message us on [Telegram](https://t.me/+RsFLPfky7-YxZjVk) and we'll add your domain to our trusted allow-list. Chromium-based browsers (Chrome, Edge, Brave) get the embedded dialog with no setup. ::: How the SDK reaches `keys.jaw.id` in **CrossPlatform** mode: an embedded iframe dialog with automatic popup fallback (default), or a popup window. **Type:** `'popup' | 'iframe' | 'auto'` **Required:** No **Default:** `'auto'` (embedded iframe primary) **Applies to:** CrossPlatform mode only (ignored in AppSpecific mode) ### Values \| Value | Behavior | \| ---------- | --------------------------------------------------------------------------------------------------------------------------- | \| `'auto'` | **Default.** Embeds `keys.jaw.id` as an in-page dialog, with automatic popup fallback where iframes can't work (see below). | \| `'iframe'` | Same as `'auto'` in this release. | \| `'popup'` | Legacy behavior: always opens `keys.jaw.id` in a popup window. Set this explicitly to opt out of the embedded dialog. | The fallback matrix below means `'auto'` never does worse than the popup: on browsers or pages where the iframe can't work, the SDK opens a popup exactly as before. If you need the popup unconditionally, set `transportMode: 'popup'`. ### Usage No configuration is needed for the default embedded dialog. To opt out and force the legacy popup: #### With Wagmi (Recommended) ```typescript import { jaw } from '@jaw.id/wagmi'; const connector = jaw({ apiKey: 'your-api-key', appName: 'My App', preference: { transportMode: 'popup', // opt out of the embedded dialog }, }); ``` #### With Provider Directly ```typescript import { JAW } from '@jaw.id/core'; const sdk = JAW.create({ apiKey: 'your-api-key', appName: 'My App', preference: { transportMode: 'popup', // opt out of the embedded dialog }, }); ``` ### Why an iframe? The popup flow opens a separate window for sign-in and transaction confirmation, which interrupts the user and is easy to lose behind the main window. The iframe renders the same `keys.jaw.id` UI inline — a bottom drawer on mobile, a centered dialog on desktop — so the user never leaves the page. The wallet, passkeys, and message protocol are identical across both transports; only the carrier changes. ### Automatic popup fallback Even with `transportMode: 'iframe'`, the SDK falls back to a popup **per request** when an iframe cannot do the job: \| Condition | Why | \| ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | \| **Safari + passkey creation** (`eth_requestAccounts`, `wallet_connect`) | Safari does not support creating passkeys inside cross-origin iframes. Sign-in still happens in the iframe; only first-time credential creation uses a popup. | \| **Non-HTTPS origin** (incl. `http://localhost` dev servers) | The iframe transport requires a real **HTTPS** origin. Any `http://` page — including `http://localhost` and `http://127.0.0.1`, which browsers treat as secure contexts — falls back to the popup. HTTPS (and `https://localhost`) gets the iframe. | \| **Occluded / untrusted embedding** | If the dialog's visibility can't be verified (no IntersectionObserver v2) and the embedder isn't a trusted host, the SDK uses a popup to prevent clickjacking. The user can also choose "Continue in new window" at any time. | In the worst case, `'iframe'` degrades to exactly the popup behavior — it never does worse than today. ### Embedding requirements When you use the iframe transport, the SDK creates the iframe for you with the correct WebAuthn permissions (`allow="publickey-credentials-get …; publickey-credentials-create …"` scoped to the keys origin) and sandbox attributes. **You don't need to configure anything in your app** — no headers, no `allow` attribute, no CSP changes on your side. Requirements that must already hold: * Your app is served over **HTTPS**. Plain-`http://` origins — including `http://localhost` dev servers — fall back to the popup transport (see the fallback matrix above). To exercise the iframe locally, serve your dev app over HTTPS (e.g. `https://localhost`). * The user interacts with the dialog directly (WebAuthn in an iframe requires a user gesture). ### Browser support \| Capability | Chrome / Edge | Firefox | Safari | \| ------------------------------------- | ------------- | ------- | ------------------------------ | \| Passkey sign-in in iframe (`get`) | 84+ | 118+ | 15.5+ | \| Passkey creation in iframe (`create`) | 123+ | 123+ | Not supported → popup fallback | Anything older falls back to the popup transport automatically. ### Notes for Safari users On Safari, browser storage inside a third-party iframe is partitioned per embedding app. A returning user may need to re-authenticate with their passkey (a single tap) rather than being silently reconnected. Sign-in, signing, and transactions all work in the iframe; only first-time passkey **creation** uses a popup. ### See also * [mode](/configuration/mode) — CrossPlatform vs AppSpecific * [CrossPlatform mode](/configuration/mode/cross-platform)