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

# react-native-extension

The package that gives access to an [Extension](/react-native/reference/package-references/client#extension-method)
that allows adding react native support to our [client](/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**. |

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

### 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>

There is no automatic load recovery in embedded mode. Any HTTP error, network failure,
blocked navigation, SSL error, or process termination surfaces as
`core.initialization.error` with `WebViewFailedToLoadError` — consumers should 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
  }
}
```