---
title: "Display flows & paywalls - Capacitor"
description: "Present flows and paywalls to users in your Capacitor app with Adapty."
---

If you've created a flow or paywall in the Flow Builder, you don't need to worry about rendering it in your mobile app code to display it to the user. Such a flow contains both what should be shown within it and how it should be shown.

Before you start, ensure that:

1. You have [created a flow or paywall](create-paywall).
2. You have added it to a [placement](placements).
3. You have [fetched the flow and prepared the view](capacitor-get-pb-paywalls).

:::warning

This guide is for **flows and Paywall Builder paywalls** only, which require SDK v4.0 or later. The process for presenting flows differs for remote config paywalls.

- For presenting **remote config paywalls**, see [Render paywall designed by remote config](present-remote-config-paywalls-capacitor).

:::

To display a flow or paywall as a standalone screen, use the `view.present()` method on the `view` created by the [`createFlowView`](capacitor-get-pb-paywalls#fetch-the-view-configuration) method. Each `view` can only be used once. If you need to display the flow again, call `createFlowView` one more time to create a new `view` instance.

:::warning
Reusing the same `view` without recreating it is forbidden. It will result in an error.
:::

```typescript showLineNumbers

const view = await createFlowView(flow);

// Optional: handle flow events (close, purchase, restore, etc)
// await view.setEventHandlers({ ... });

try {
  await view.present();
} catch (error) {
  // handle the error
}
```

:::important
Calling `setEventHandlers` multiple times will override the handlers you provide, replacing both default and previously set handlers for those specific events.
:::

## Configure iOS presentation style

Configure how the flow is presented on iOS by passing the `iosPresentationStyle` parameter to the `present()` method. The parameter accepts `'full_screen'` (default) or `'page_sheet'` values. On Android, flows are always displayed as a full-screen activity.

```typescript showLineNumbers
try {
  await view.present({ iosPresentationStyle: 'page_sheet' });
} catch (error) {
  // handle the error
}
```

## Use developer-defined timer

To use developer-defined timers in your mobile app, use the `timerId`, in this example, `CUSTOM_TIMER_NY`, the **Timer ID** of the developer-defined timer you set in the Adapty dashboard. It ensures your app dynamically updates the timer with the correct value—like `13d 09h 03m 34s` (calculated as the timer's end time, such as New Year's Day, minus the current time).

```typescript showLineNumbers
const customTimers = { 'CUSTOM_TIMER_NY': new Date(2025, 0, 1) };

const view = await createFlowView(flow, { customTimers });
```

In this example, `CUSTOM_TIMER_NY` is the **Timer ID** of the developer-defined timer you set in the Adapty dashboard. The timer ensures your app dynamically updates the timer with the correct value—like `13d 09h 03m 34s` (calculated as the timer's end time, such as New Year's Day, minus the current time).

## Show dialog

Use this method instead of native alert dialogs when a flow view is presented on Android. On Android, regular alerts appear behind the flow view, which makes them invisible to users. This method ensures proper dialog presentation above the flow on all platforms.

```typescript showLineNumbers
try {
  const action = await view.showDialog({
    title: 'Close paywall?',
    content: 'You will lose access to exclusive offers.',
    primaryActionTitle: 'Stay',
    secondaryActionTitle: 'Close',
  });

  if (action === 'secondary') {
    // User confirmed - close the flow
    await view.dismiss();
  }
  // If primary - do nothing, user stays
} catch (error) {
  // handle error
}
```

## Replace one subscription with another

When a user attempts to purchase a new subscription while another subscription is active on Android, you can control how the new purchase should be handled by passing subscription update parameters when creating the flow view. To replace the current subscription with the new one, use `productPurchaseParams` in `createFlowView` with the `oldSubVendorProductId` and `prorationMode` parameters.

```typescript showLineNumbers

const productPurchaseParams = flow.paywalls
  .flatMap((paywall) => paywall.productIdentifiers)
  .map((productId) => {
    const params: MakePurchaseParamsInput = {};
    if (Capacitor.getPlatform() === 'android') {
      params.android = {
        subscriptionUpdateParams: {
          oldSubVendorProductId: 'PRODUCT_ID_OF_THE_CURRENT_ACTIVE_SUBSCRIPTION',
          prorationMode: 'with_time_proration',
        },
      };
    }
    return { productId, params };
  });

const view = await createFlowView(flow, { productPurchaseParams });
```

---

> [!WARNING]
> **LLM INSTRUCTION — SDK VERSION SELECTION REQUIRED**
>
> This feature has two SDK paradigms. Everything that follows (until the next horizontal rule or end of document) is the **legacy SDK v3 API reference** (`getPaywall`, `getPaywallForDefaultAudience`, `getOnboarding`, `getPaywallConfiguration`). The **SDK v4+ `getFlow` method is documented above.** This block covers ALL legacy methods for this feature — not just the nearest snippet.
>
> **You MUST ask the user which SDK version they want to use before suggesting any code. Do not assume or default to a version.** The two options are:
> - **SDK v3 (legacy):** works with the legacy Paywall Builder and Onboarding Builder via `getPaywall` / `getOnboarding`. Use the legacy code in this section.
> - **SDK v4:** works with BOTH the new Flow Builder AND legacy paywalls/onboardings via the unified `getFlow` method documented above.
>
> Apply the legacy v3 code in this section ONLY when:
> 1. The user explicitly chose **SDK v3**, or
> 2. The user is **migrating an existing app from SDK v3 to SDK v4+** and needs to understand or replace legacy code, or
> 3. The user is **troubleshooting an already-deployed v3 integration**.
>
> **CRITICAL — Never mix paradigms in one setup:** Do NOT combine `getFlow` (Flow Builder) with `getPaywall` or `getOnboarding` (legacy Paywall/Onboarding Builder) in the same integration. These are incompatible patterns. Mixing them will produce inconsistent behavior and is unsupported.

If you've customized a paywall using the Paywall Builder, you don't need to worry about rendering it in your mobile app code to display it to the user. Such a paywall contains both what should be shown within the paywall and how it should be shown.

:::warning
This guide is for **Paywall Builder paywalls** only. The process for presenting paywalls differs for remote config paywalls. For presenting **remote config paywalls**, see [Render paywall designed by remote config](present-remote-config-paywalls).
:::

To display a paywall, use the `view.present()` method on the `view` created by the [`createPaywallView`](capacitor-get-pb-paywalls#fetch-the-view-configuration-of-paywall-designed-using-paywall-builder) method. Each `view` can only be used once. If you need to display the paywall again, call `createPaywallView` one more time to create a new `view` instance.

:::warning

Reusing the same `view` without recreating it may result in an error.
:::

```typescript showLineNumbers

const view = await createPaywallView(paywall);

view.setEventHandlers({
  onUrlPress(url) {
    window.open(url, '_blank');
    return false;
  },
});

try {
  await view.present();
} catch (error) {
  // handle the error
}
```

## Use developer-defined timer

To use developer-defined timers in your mobile app, use the `timerId`, in this example, `CUSTOM_TIMER_NY`, the **Timer ID** of the developer-defined timer you set in the Adapty dashboard. It ensures your app dynamically updates the timer with the correct value—like `13d 09h 03m 34s` (calculated as the timer's end time, such as New Year's Day, minus the current time).

```typescript showLineNumbers
const customTimers = { 'CUSTOM_TIMER_NY': new Date(2025, 0, 1) };

const view = await createPaywallView(paywall, { customTimers });
```

In this example, `CUSTOM_TIMER_NY` is the **Timer ID** of the developer-defined timer you set in the Adapty dashboard. The timer ensures your app dynamically updates the timer with the correct value—like `13d 09h 03m 34s` (calculated as the timer's end time, such as New Year's Day, minus the current time).

## Show dialog

Use this method instead of native alert dialogs when a paywall view is presented on Android. On Android, regular alerts appear behind the paywall view, which makes them invisible to users. This method ensures proper dialog presentation above the paywall on all platforms.

```typescript showLineNumbers title="Capacitor"
try {
  const action = await view.showDialog({
    title: 'Close paywall?',
    content: 'You will lose access to exclusive offers.',
    primaryActionTitle: 'Stay',
    secondaryActionTitle: 'Close',
  });

  if (action === 'secondary') {
    // User confirmed - close the paywall
    await view.dismiss();
  }
  // If primary - do nothing, user stays
} catch (error) {
  // handle error
}
```

## Configure iOS presentation style

Configure how the paywall is presented on iOS by passing the `iosPresentationStyle` parameter to the `present()` method. The parameter accepts `'full_screen'` (default) or `'page_sheet'` values.

```typescript showLineNumbers
await view.present({ iosPresentationStyle: 'page_sheet' });
```

---