Mode

Built-in Modes

Mode.dialog

Dialog mode embeds the hosted Porto Dialog (an iframe pointing to id.porto.sh) and forwards every request that requires user interaction to that dialog.

Diagram

In the diagram below, Mode.dialog is utilized within the Application to communicate with the Porto Dialog (id.porto.sh).

Usage

import { Porto, Mode } from 'porto'
 
const porto = Porto.create({
  mode: Mode.dialog(), 
})

Options

fallback

• Type: Mode.Mode
• Default: Mode.relay()

Mode to fall back to if the renderer does not support background operations (e.g. popups and web views).

host

• Type: string
• Default: "https://id.porto.sh/dialog"

URL of the dialog embed.

import { Porto, Mode } from 'porto'
 
const porto = Porto.create({
  mode: Mode.dialog({
    host: 'https://account.my-wallet.com/dialog', 
  }),
})

renderer

• Type: Dialog.Dialog
• Default: Dialog.iframe()

The renderer to use for the dialog. Available: Dialog.iframe, Dialog.popup

import { Dialog, Porto, Mode } from 'porto'
 
const porto = Porto.create({
  mode: Mode.dialog({
    renderer: Dialog.popup(), 
  }),
})

theme

• Type: ThemeFragment | undefined

A custom theme to apply to the dialog, where only colorScheme is required. See the Theme API for the list of styling properties that can be defined.

themeController

• Type: Dialog.ThemeController | undefined

A controller to manage the dialog theme, created by Dialog.createThemeController(). It can be used to change the theme of the dialog without reinitializing it, with themeController.setTheme(). This is intended for advanced use cases, theme should be sufficient in regular scenarios.

Mode.reactNative

React Native mode is used to communicate with React Native applications. Setup assumes the use of expo.

Usage

Install required dependencies:

pnpm expo install expo-web-browser expo-auth-session expo-crypto

Since we rely on a few Web Crypto APIs such as crypto.randomUUID and crypto.getRandomValues, we need to polyfill those at the earliest possible stage. So in your entrypoint file (i.e., root index.ts / index.native.ts):

import 'porto/react-native/register'
 
// ...

Then import Porto anywhere in your application:

import { Porto, Mode } from 'porto'
 
const porto = Porto.create({
  mode: Mode.reactNative(), 
})

or

import { Porto } from 'porto/react-native'
 
const porto = Porto.create()

Wagmi usage

import { baseSepolia } from 'porto/core/Chains'
import { Mode } from 'porto/react-native'
import { porto } from 'porto/wagmi'
import { Platform } from 'react-native'
import { createConfig, http } from 'wagmi'
 
const config = createConfig({
  chains: [baseSepolia],
  connectors: [
    porto({
      ...Platform.select({
        web: { mode: Mode.dialog() },
        default: { mode: Mode.reactNative() },
      })
    })
  ],
  multiInjectedProviderDiscovery: false,
  transports: {
    [baseSepolia.id]: http(),
  },
})

Examples

• Porto x Mode.reactNative (dialog) x Wagmi
• Porto x Mode.relay (headless) x SIWE

Options

host

• Type: string
• Default: "https://id.porto.sh/dialog"

URL of the dialog embed.

redirectUri

• Type: { scheme: string, path?: string } | undefined

Where to redirect the user after operations are completed. Defaults to the result of AuthSession.makeRedirectUri({ path: '/' }) if no value is passed.

requestOptions

• Type: WebBrowser.AuthSessionOpenOptions | undefined

Configure style, presentation and certain behaviors of the browser auth session for Android, iOS, and Web. See details.

theme

• Type: ThemeFragment | undefined

A custom theme to apply to the dialog, where only colorScheme is required. See the Theme API for the list of styling properties that can be defined.

themeController

• Type: Dialog.ThemeController | undefined

A controller to manage the dialog theme, created by Dialog.createThemeController(). It can be used to change the theme of the dialog without reinitializing it, with themeController.setTheme(). This is intended for advanced use cases, theme should be sufficient in regular scenarios.

Mode.relay

Interacts with the Porto Relay directly. Signing is performed via the SDK. Account management, chain interop, and transaction management is orchestrated on the Relay.

Diagram

In the diagram below, Mode.relay is utilized within the Porto Dialog (id.porto.sh) to communicate with the Relay.

Usage

import { Porto, Mode } from 'porto'
 
const porto = Porto.create({
  mode: Mode.relay(), 
})

Caveats

• When you run Mode.relay the Passkey Host (WebAuthn Relying Party) becomes your domain, not id.porto.sh. Credentials created here cannot be asserted on other domains, which means users cannot reuse their Porto account created on id.porto.sh.

Options

keystoreHost

• Type: string
• Default: "self"

Keystore host (WebAuthn relying party).

import { Porto, Mode } from 'porto'
 
const porto = Porto.create({
  mode: Mode.relay({
    keystoreHost: 'https://account.my-wallet.com', 
  }),
})

webAuthn

webAuthn.createFn

• Type: WebAuthnP256.createCredential.Options['createFn']

WebAuthn create credential function. Defaults to navigator.credentials.create.

webAuthn.getFn

• Type: WebAuthnP256.sign.Options['getFn']

WebAuthn get credential function. Defaults to navigator.credentials.get.