Feature gates

Gate components are presentational. They never fetch customer data and never receive a customer ID. Load entitlement, usage, and plan state through your authenticated backend, then pass the result into the gate.

`FeatureGate`

Renders children when allowed is true, fallback when it is false, and null while loading is true.

import { FeatureGate, UpgradePrompt } from '@nozle-js/react'

<FeatureGate
  allowed={entitlement.allowed}
  loading={entitlement.loading}
  fallback={<UpgradePrompt planName="Growth" />}
>
  <AnalyticsDashboard />
</FeatureGate>

Prop	Type	Default	Description
`allowed`	`boolean`	required	Whether children may render.
`loading`	`boolean`	`false`	Returns `null` while customer state loads.
`fallback`	`ReactNode`	`null`	Rendered when access is denied.
`children`	`ReactNode`	required	Protected content.

`UsageGate`

Renders children while usage < limit. Equality is treated as exhausted.

<UsageGate
  usage={8_200}
  limit={10_000}
  fallback={<span>Monthly limit reached</span>}
>
  <ApiCallForm />
</UsageGate>

Prop	Type	Default	Description
`usage`	`number`	required	Current usage.
`limit`	`number`	required	Usage ceiling.
`fallback`	`ReactNode`	`null`	Rendered when usage is at or above the limit.
`children`	`ReactNode`	required	Content available below the limit.

`PlanGate`

Checks whether currentPlan is included in allowedPlans.

<PlanGate
  currentPlan={billing.planCode}
  allowedPlans={['growth', 'scale']}
  fallback={<UpgradePrompt planName="Growth" />}
>
  <AdvancedSettings />
</PlanGate>

Prop	Type	Default	Description
`currentPlan`	`string`	required	Current plan identifier.
`allowedPlans`	`string[]`	required	Plans that may render children.
`fallback`	`ReactNode`	`null`	Rendered for a plan outside the allowlist.
`children`	`ReactNode`	required	Plan-gated content.

`UpgradePrompt`

Displays an upgrade message and button. Without onUpgrade, the button navigates to /upgrade.

<UpgradePrompt
  planName="Scale"
  onUpgrade={() => router.push('/settings/billing')}
/>

Prop	Type	Default	Description
`text`	`string`	`Upgrade to access this feature`	Message used when `planName` is absent.
`planName`	`string`	—	Produces “Upgrade to [plan] to access this feature.”
`onUpgrade`	`() => void`	Navigate to `/upgrade`	Upgrade action.

`LockedOverlay`

Shows an upgrade prompt over blurred, non-interactive content when locked is true. When unlocked, it returns the children without a wrapper.

<LockedOverlay
  locked={!entitlement.allowed}
  upgradePlanName="Scale"
  onUpgrade={() => setUpgradeOpen(true)}
>
  <AnalyticsPreview />
</LockedOverlay>

Prop	Type	Default	Description
`locked`	`boolean`	required	Enables the blur and overlay.
`upgradeText`	`string`	—	Custom prompt text.
`upgradePlanName`	`string`	—	Plan name passed to `UpgradePrompt`.
`onUpgrade`	`() => void`	Navigate to `/upgrade`	Upgrade action.
`children`	`ReactNode`	required	Preview content.

Backend-driven composition

function ReportingSection() {
  const { data, loading } = useMerchantBillingState()

  return (
    <FeatureGate
      allowed={data?.entitlements.reporting ?? false}
      loading={loading}
      fallback={<UpgradePrompt planName="Growth" />}
    >
      <PlanGate
        currentPlan={data?.planCode ?? ''}
        allowedPlans={['growth', 'scale', 'enterprise']}
      >
        <UsageGate
          usage={data?.usage.reports ?? 0}
          limit={data?.limits.reports ?? 0}
          fallback={<span>Report limit reached</span>}
        >
          <ReportBuilder />
        </UsageGate>
      </PlanGate>
    </FeatureGate>
  )
}

Gates improve the user interface; they are not an authorization boundary. Enforce entitlement and usage rules again on the server before performing protected work.

Setup

Billing

Entitlements

Feature gates

`FeatureGate`

`UsageGate`

`PlanGate`

`UpgradePrompt`

`LockedOverlay`

Backend-driven composition

​FeatureGate

​UsageGate

​PlanGate

​UpgradePrompt

​LockedOverlay

​Backend-driven composition

`FeatureGate`

`UsageGate`

`PlanGate`

`UpgradePrompt`

`LockedOverlay`

Backend-driven composition