> ## Documentation Index
> Fetch the complete documentation index at: https://www.dynamic.xyz/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# react-native-extension

<Card title="Recommended: JavaScript SDK for React Native" icon="react" color="#4779FE">
  While this SDK is still supported, we recommend using newer [JavaScript SDK](/docs/javascript/reference/react-native-quickstart), which is optimized for React Native, but also comes with a host of other benefits.
</Card>

The package that gives access to an [Extension](/docs/react-native/reference/package-references/client#extension-method)
that allows adding react native support to our [client](/docs/react-native/reference/client).

## Functions

### `ReactNativeExtension` method

```typescript theme={"system"}
ReactNativeExtension(props?: ReactNativeExtensionProps): Extension<IReactNativeExtension>
```

A method that, when passed to the client instance, injects the following modules into it:

#### `reactNative` module

Provides access to the webview that renders our SDK in the background of your app.

The client itself is only an interface to our SDK, so it must be rendered to your app in order for the client
to work.

| Property  | Type                | Description                                                        |
| --------- | ------------------- | ------------------------------------------------------------------ |
| `WebView` | `() => JSX.Element` | The react native component that renders our SDK in the background. |

## Types

### `ReactNativeExtensionProps` type

Properties which you can pass to the extension.

| Param                     | Type                  | Description                                                                                                                                                                                                                                             |
| ------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `appOrigin`               | `string?`             | The web origin of your app (e.g. `https://demo.dynamic.xyz`). Used for SIWE messages, fetch `Origin` headers, and passkey operations. Deep link redirects use the auto-configured `redirectUrl` from `expo-linking`.                                    |
| `webviewUrl`              | `string?`             | The URL to load in the WebView. Defaults to `https://webview.dynamicauth.com/${version}`.                                                                                                                                                               |
| `webviewDebuggingEnabled` | `boolean?`            | Enables debugging in the WebView (e.g. Safari Web Inspector on iOS, `chrome://inspect` on Android). Useful in development.                                                                                                                              |
| `embeddedWebView`         | `boolean?`            | When `true` on iOS / Android, the SDK hosts the webview-controller in a native overlay window outside the React Native view tree. See [Embedded WebView mode](#embedded-webview-mode). Defaults to `false`. Available from **v4.82.0**.                 |
| `webviewLoad`             | `WebViewLoadOptions?` | Tunable budgets for the webview load engine (attempt count and per-phase timeouts). Applies to both webview paths. See [Tuning and monitoring the WebView load](/docs/react-native/reference/react-native-extension#tuning-and-monitoring-the-webview-load). |

```typescript theme={"system"}
type ReactNativeExtensionProps = {
  appOrigin?: string
  webviewUrl?: string
  webviewDebuggingEnabled?: boolean
  embeddedWebView?: boolean
  webviewLoad?: WebViewLoadOptions
}

type WebViewLoadOptions = {
  maxAttempts?: number
  pageLoadTimeoutMs?: number
  firstAttemptPageLoadTimeoutMs?: number
  sdkReadyTimeoutMs?: number
}
```

### Embedded WebView mode

<Note>
  Available from **v4.82.0**.
</Note>

When `embeddedWebView` is set to `true`, the SDK renders its webview-controller inside a
dedicated native overlay (`WKWebView` on iOS, `android.webkit.WebView` on Android) owned by a
separate UI window outside the React Native view tree.

This isolates the webview from RN re-renders, navigation transitions, and other lifecycle
events that can otherwise tear the webview down — which is useful for apps with complex
navigation stacks where the wallet session needs to survive aggressive remounts.

```typescript theme={"system"}
import { createClient } from '@dynamic-labs/client'
import { ReactNativeExtension } from '@dynamic-labs/react-native-extension'

export const dynamicClient = createClient({
  environmentId: 'YOUR-ENVIRONMENT-ID',
}).extend(
  ReactNativeExtension({
    appOrigin: 'https://your-app.example',
    embeddedWebView: true,
  }),
)
```

<Warning>
  When `embeddedWebView` is `true`, the component returned at
  `dynamicClient.reactNative.WebView` becomes a no-op — **do not render it**. The native
  overlay is created lazily and retained for the process lifetime.
</Warning>

<Note>
  On platforms other than iOS / Android (e.g. web), the `embeddedWebView` flag is ignored
  and the standard `react-native-webview` path is used.
</Note>

Embedded mode runs the same bounded-retry load engine as the standard `react-native-webview`
path, so transient failures are retried automatically and you can observe progress and trigger
a manual retry through the same API — see
[Tuning and monitoring the WebView load](/docs/react-native/reference/react-native-extension#tuning-and-monitoring-the-webview-load).
Once every attempt is exhausted, the failure surfaces as `core.initialization.error` with
`WebViewFailedToLoadError` — treat the SDK as un-initialised and react accordingly.

### `IReactNativeExtension` type

Type of the react native extension.

```typescript theme={"system"}
type IReactNativeExtension = {
  reactNative: {
    WebView: () => JSX.Element
  }
}
```