FeatureGate Widget
Component Detail
Description
A conditional rendering wrapper widget that gates any child widget behind a single boolean feature flag check. Accepts a flag key and optional fallback widget, hiding or showing content based on the flag value resolved from the current organization context.
feature-gate-widget
Summaries
The FeatureGate Widget is the mechanism that allows the business to safely deliver new capabilities to selected organizations before a broad rollout, dramatically reducing the risk associated with feature releases. By wrapping any piece of the interface behind a single flag check, product and operations teams can enable or disable features per organization without deploying new code. This supports phased rollouts, beta programs, and emergency feature disablement — giving business stakeholders direct control over what each customer sees. The result is faster iteration, lower release risk, and the ability to tailor the product experience to different organizational tiers or readiness levels, supporting both upsell opportunities and careful enterprise onboarding.
FeatureGate is a low-complexity shared UI component with a single dependency on the feature flag provider. Its simplicity is a deliberate design choice — the gating logic is entirely declarative at the widget level, keeping feature-specific code clean and easy to review. From a delivery perspective, this component should be implemented before any feature that needs phased rollout, and its adoption should be enforced through code review guidelines. The optional `fallback` parameter allows teams to ship graceful degradation UI alongside the gated feature, which should be treated as a delivery requirement rather than an optional polish item.
Testing requirements include verifying both flag-enabled and flag-disabled states for every gated widget, and ensuring the Riverpod provider correctly reflects real flag values in integration test environments.
FeatureGate is a stateless `ConsumerWidget` that reads `featureFlagProvider(flagKey)` from Riverpod and conditionally renders either `child` or `fallback ?? SizedBox.shrink()`. The widget constructor requires `flagKey` (a `LabelKeys`-style constant string) and `child`, with an optional `fallback` widget. The provider watch is scoped to the single flag key, meaning only widgets gated by a changed flag rebuild — not the entire screen.
Internally, the widget does no business logic: evaluation of the flag's boolean value is entirely delegated to `featureFlagProvider`, which handles organization scoping, caching, and async loading. When the provider is in a loading or error state, FeatureGate should treat the flag as disabled to fail safe. Add a `debugLabel` to the `Semantics` wrapper in debug builds to make flag boundaries visible in the widget inspector.
Responsibilities
- Accept a flag key and resolve it against the active organization's flag map
- Render child widget when flag is enabled, fallback or nothing when disabled
- Integrate with Riverpod to reactively rebuild when flag values change
Interfaces
FeatureGate({required String flagKey, required Widget child, Widget? fallback})
build(BuildContext context)
watch featureFlagProvider
Relationships
Related Data Entities (1)
Data entities managed by this component