# PaywallOptions

Configuration for paywall presentation and behavior in the Superwall Flutter SDK.

> **Tip**

`PaywallOptions` is provided via the `paywalls` parameter on [`SuperwallOptions`](/docs/flutter/sdk-reference/SuperwallOptions) and is passed when calling [`configure`](/docs/flutter/sdk-reference/configure).



Purpose [#purpose]

Customize how paywalls look and behave, including preload behavior, alerts, dismissal, and haptics.

Signature [#signature]

```dart
class PaywallOptions {
  bool isHapticFeedbackEnabled = true;
  RestoreFailed restoreFailed = RestoreFailed();
  bool shouldShowPurchaseFailureAlert = true;
  bool shouldPreload = true;
  Map<DeviceTier, bool> preloadDeviceOverrides = const {};
  bool automaticallyDismiss = true;
  TransactionBackgroundView transactionBackgroundView = TransactionBackgroundView.spinner;
  bool shouldShowWebRestorationAlert = true;
  Map<String, String>? overrideProductsByName;
  bool shouldShowWebPurchaseConfirmationAlert = true;
  void Function(PaywallInfo?)? onBackPressed;
}

class RestoreFailed {
  String title = 'No Subscription Found';
  String message = "We couldn't find an active subscription for your account.";
  String closeButtonTitle = 'Okay';
}

enum TransactionBackgroundView { spinner, none }

enum DeviceTier { ultraLow, low, mid, high, ultraHigh, unknown }
```

Parameters [#parameters]

<TypeTable
  type="{
  isHapticFeedbackEnabled: {
    type: &#x22;bool&#x22;,
    description: &#x22;Enables haptic feedback during key paywall interactions.&#x22;,
    default: &#x22;true&#x22;,
  },
  restoreFailed: {
    type: &#x22;RestoreFailed&#x22;,
    description: &#x22;Messaging for the restore-failed alert.&#x22;,
    required: true,
  },
  &#x22;restoreFailed.title&#x22;: {
    type: &#x22;String&#x22;,
    description: &#x22;Title for restore-failed alert.&#x22;,
    default: &#x22;No Subscription Found&#x22;,
  },
  &#x22;restoreFailed.message&#x22;: {
    type: &#x22;String&#x22;,
    description: &#x22;Message for restore-failed alert.&#x22;,
    default: &#x22;We couldn't find an active subscription for your account.&#x22;,
  },
  &#x22;restoreFailed.closeButtonTitle&#x22;: {
    type: &#x22;String&#x22;,
    description: &#x22;Close button title for restore-failed alert.&#x22;,
    default: &#x22;Okay&#x22;,
  },
  shouldShowPurchaseFailureAlert: {
    type: &#x22;bool&#x22;,
    description: &#x22;Shows an alert after a purchase fails. Set to `false` if you handle failures via a `PurchaseController`.&#x22;,
    default: &#x22;true&#x22;,
  },
  shouldPreload: {
    type: &#x22;bool&#x22;,
    description: &#x22;Preloads and caches trigger paywalls and products during SDK initialization.&#x22;,
    default: &#x22;true&#x22;,
  },
  preloadDeviceOverrides: {
    type: &#x22;Map<DeviceTier, bool>&#x22;,
    description: &#x22;Android only. Per-device-tier overrides for `shouldPreload`. Only the tiers you specify are overridden; the rest fall back to `shouldPreload`. Use this to disable preloading on low-end devices while keeping it enabled on mid/high-end devices.&#x22;,
    default: &#x22;const {}&#x22;,
  },
  automaticallyDismiss: {
    type: &#x22;bool&#x22;,
    description: &#x22;Automatically dismisses the paywall on successful purchase or restore.&#x22;,
    default: &#x22;true&#x22;,
  },
  transactionBackgroundView: {
    type: &#x22;TransactionBackgroundView&#x22;,
    description: &#x22;View shown behind the system payment sheet during a transaction.&#x22;,
    default: &#x22;.spinner&#x22;,
  },
  shouldShowWebRestorationAlert: {
    type: &#x22;bool&#x22;,
    description: &#x22;Shows an alert asking the user to try restoring on the web if web checkout is enabled.&#x22;,
    default: &#x22;true&#x22;,
  },
  overrideProductsByName: {
    type: &#x22;Map<String, String>?&#x22;,
    description: &#x22;Overrides products on all paywalls using name\u2192identifier mapping (e.g., `\&#x22;primary\&#x22;` \u2192 `\&#x22;com.example.premium_monthly\&#x22;`).&#x22;,
  },
  shouldShowWebPurchaseConfirmationAlert: {
    type: &#x22;bool&#x22;,
    description: &#x22;Shows a localized alert confirming a successful web checkout purchase.&#x22;,
    default: &#x22;true&#x22;,
  },
  onBackPressed: {
    type: &#x22;void Function(PaywallInfo?)?&#x22;,
    description: &#x22;Android only. Invoked when the system back button is pressed while a paywall is visible. Call `Superwall.shared.dismiss()` inside if you want to close the paywall.&#x22;,
  },
}"
/>

Usage [#usage]

```dart
final paywallOptions = PaywallOptions()
  ..isHapticFeedbackEnabled = true
  ..shouldShowPurchaseFailureAlert = false
  ..shouldPreload = true
  ..automaticallyDismiss = true
  ..transactionBackgroundView = TransactionBackgroundView.spinner
  ..overrideProductsByName = {
    'primary': 'com.example.premium_monthly',
    'tertiary': 'com.example.premium_annual',
  }
  ..shouldShowWebRestorationAlert = true
  ..shouldShowWebPurchaseConfirmationAlert = true
  ..onBackPressed = (paywallInfo) {
    // Android-only callback
    Superwall.shared.dismiss();
  };

final options = SuperwallOptions(
  paywalls: paywallOptions,
);

await Superwall.configure(
  'pk_your_api_key',
  options: options,
);
```

Related [#related]

* [`SuperwallOptions`](/docs/flutter/sdk-reference/SuperwallOptions)