SubscriptionGuard class

Declaratively gate any widget behind a subscription tier.

Reads the current subscription state from SubscriptionGuardScope and determines whether the child should be shown, hidden, disabled, blurred, or replaced based on the user's tier and the configured GuardBehavior.

There are three ways to construct a SubscriptionGuard:

Tier-based (hierarchy) — the default constructor checks whether the user's tier level meets or exceeds the required tier:

SubscriptionGuard(
  requiredTier: 'pro',
  child: AdvancedAnalyticsWidget(),
)

Feature-based — looks up the required tier from the config's feature map:

SubscriptionGuard.feature(
  featureId: 'export_pdf',
  child: ExportButton(),
)

Allowed tiers (exact match) — grants access only if the user's tier id is in the provided list (not hierarchy-based):

SubscriptionGuard.allowedTiers(
  tierIds: ['pro', 'enterprise'],
  child: TeamFeatureWidget(),
)

Custom locked UI:

SubscriptionGuard(
  requiredTier: 'pro',
  behavior: GuardBehavior.replace,
  lockedBuilder: (context, requiredTier, currentTier) {
    return MyCustomUpgradePrompt(tier: requiredTier);
  },
  child: AdvancedAnalyticsWidget(),
)

See also:

• GuardBehavior, the enum controlling what happens when access is denied.
• DefaultLockedWidget, the built-in fallback UI for GuardBehavior.replace.
• SubscriptionGuardProvider, which must be an ancestor in the widget tree.
• SubscriptionGuardScope, where the current tier and config are read from.
• SubscriptionRouteGuard, for route-level (navigation) access checks.

Inheritance

• Object
• DiagnosticableTree
• Widget
• StatelessWidget
• SubscriptionGuard

Constructors

SubscriptionGuard({Key? key, required String? requiredTier, required Widget child, GuardBehavior? behavior, Widget lockedBuilder(BuildContext context, Tier requiredTier, Tier currentTier)?, bool allowDuringTrial = true, VoidCallback? onBlocked, double blurMinHeight = 180.0})

Creates a SubscriptionGuard that gates child behind the tier identified by requiredTier using hierarchy-based access checks.

const

SubscriptionGuard.allowedTiers({Key? key, required List<String>? tierIds, required Widget child, GuardBehavior? behavior, Widget lockedBuilder(BuildContext context, Tier requiredTier, Tier currentTier)?, bool allowDuringTrial = true, VoidCallback? onBlocked, double blurMinHeight = 120.0})

Creates a SubscriptionGuard that grants access only if the user's current tier id is in the tierIds list.

const

SubscriptionGuard.feature({Key? key, required String? featureId, required Widget child, GuardBehavior? behavior, Widget lockedBuilder(BuildContext context, Tier requiredTier, Tier currentTier)?, bool allowDuringTrial = true, VoidCallback? onBlocked, double blurMinHeight = 120.0})

Creates a SubscriptionGuard that gates child behind a feature defined in SubscriptionConfig.features.

const

Properties

allowDuringTrial → bool

Whether to grant access to trialing users.

final

behavior → GuardBehavior?

The guard behavior to apply when access is denied.

final

blurMinHeight → double

Minimum height for the blurred area when GuardBehavior.blur is active.

final

child → Widget

The widget to display when the user has access.

final

featureId → String?

The feature id to look up in the config's feature map.

final

hashCode → int

The hash code for this object.

no setter, inherited

key → Key?

Controls how one widget replaces another widget in the tree.

final, inherited

lockedBuilder → Widget Function(BuildContext context, Tier requiredTier, Tier currentTier)?

An optional widget-level override for the locked UI.

final

onBlocked → VoidCallback?

An optional callback invoked when this guard blocks the user.

final

requiredTier → String?

The minimum tier id required for hierarchy-based access.

final

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

tierIds → List<String>?

The list of specific tier ids allowed access.

final

Methods

build(BuildContext context) → Widget

Describes the part of the user interface represented by this widget.

override

createElement() → StatelessElement

Creates a StatelessElement to manage this widget's location in the tree.

inherited

debugDescribeChildren() → List<DiagnosticsNode>

Returns a list of DiagnosticsNode objects describing this node's children.

inherited

debugFillProperties(DiagnosticPropertiesBuilder properties) → void

Add additional properties associated with the node.

inherited

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode

Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.

inherited

toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) → String

A string representation of this object.

inherited

toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug, int wrapWidth = 65}) → String

Returns a string representation of this node and its descendants.

inherited

toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String

Returns a one-line detailed description of the object.

inherited

toStringShort() → String

A short, textual description of this widget.

inherited

Operators

operator ==(Object other) → bool

The equality operator.

inherited