subscription_guard library

A declarative, provider-agnostic subscription tier gating package for Flutter.

Gate features, widgets, and routes based on subscription tiers with zero purchase SDK dependency.

Overview

subscription_guard lets you define subscription tiers, map features to those tiers, and declaratively gate any widget, route, or action based on the user's current tier — all without coupling to a specific purchase SDK.

The package follows Flutter's InheritedWidget pattern:

1. Configure your tiers and features with SubscriptionConfig.
2. Provide subscription state with SubscriptionGuardProvider.
3. Guard widgets with SubscriptionGuard and routes with SubscriptionRouteGuard or subscriptionRedirect.
4. Display trial status with TrialBanner.
5. Debug with SubscriptionGuardDebugOverlay.

Quick Start

import 'package:subscription_guard/subscription_guard.dart';

// 1. Define your tiers
final config = SubscriptionConfig(
  tiers: [
    Tier(id: 'free', level: 0, label: 'Free'),
    Tier(id: 'pro', level: 1, label: 'Pro'),
    Tier(id: 'premium', level: 2, label: 'Premium'),
  ],
  features: {
    'advanced_stats': 'pro',
    'export_pdf': 'pro',
    'team_management': 'premium',
  },
);

// 2. Wrap your app
SubscriptionGuardProvider(
  config: config,
  currentTier: 'free',
  onUpgradeRequested: (tier) => showPaywall(tier),
  child: MyApp(),
);

// 3. Guard any widget
SubscriptionGuard(
  requiredTier: 'pro',
  child: PremiumFeatureWidget(),
);

Key Classes

Class	Purpose
Tier	Represents a single subscription tier.
SubscriptionConfig	Central config with tiers and feature map.
GuardBehavior	Controls locked behavior (hide, disable, replace, blur).
TrialInfo	Tracks trial/grace period state.
SubscriptionGuardProvider	Top-level state widget (wrap your app).
SubscriptionGuardScope	InheritedWidget for reading state.
SubscriptionGuard	Declarative widget-level gating.
DefaultLockedWidget	Built-in locked UI fallback.
TrialBanner	Trial countdown banner.
SubscriptionGuardDebugOverlay	Dev-only debug panel.
SubscriptionRouteGuard	Programmatic route access checks.
subscriptionRedirect	GoRouter-compatible redirect (tier).
subscriptionFeatureRedirect	GoRouter-compatible redirect (feature).
SubscriptionPageRoute	MaterialPageRoute with built-in gating.
RouteAccessResult	Result of a route access check.

Classes

DefaultLockedWidget

The built-in fallback UI displayed when a feature is locked behind a higher subscription tier.

RouteAccessResult

Holds the result of a route or feature access check.

SubscriptionConfig

Central configuration that defines all subscription tiers and feature-to-tier mappings.

SubscriptionGuard

Declaratively gate any widget behind a subscription tier.

SubscriptionGuardDebugOverlay

A floating debug overlay for testing subscription tiers during development.

SubscriptionGuardProvider

A StatefulWidget that manages subscription state and provides it to all descendant widgets via SubscriptionGuardScope.

SubscriptionGuardScope

An InheritedWidget that sits in the widget tree and exposes subscription state to all descendant widgets.

SubscriptionPageRoute<T>

A MaterialPageRoute that automatically guards its content behind a subscription tier.

SubscriptionRouteGuard

A collection of static utility methods for programmatic route access checks and guarded navigation.

Tier

Represents a single subscription tier.

TrialBanner

A banner widget that displays the user's trial status and a countdown of remaining days.

TrialInfo

Holds trial or grace period information for the current subscription.

Enums

DebugOverlayPosition

Initial position for the debug overlay floating action button.

GuardBehavior

Defines how a locked feature should behave when the user's tier is insufficient.

Functions

subscriptionFeatureRedirect({required String featureId, required String redirectPath, bool allowDuringTrial = true, Map<String, String>? redirectQueryParams, String? customRedirect(BuildContext context, Tier requiredTier, Tier currentTier)?}) → String? Function(BuildContext context, dynamic state)

Returns a redirect function compatible with GoRouter's redirect parameter that gates a route behind a feature defined in the subscription config.

subscriptionRedirect({required String requiredTier, required String redirectPath, bool allowDuringTrial = true, Map<String, String>? redirectQueryParams, String? customRedirect(BuildContext context, Tier requiredTier, Tier currentTier)?}) → String? Function(BuildContext context, dynamic state)

Returns a redirect function compatible with GoRouter's redirect parameter that gates a route behind a subscription tier.