UsageGate

UsageGate renders its children while usage is below limit, and fallback once usage reaches it. When to use

Around a “Create” button for something with a monthly cap.
Around an API console or generator that consumes a metered feature.
When reaching the limit counts as used up (usage >= limit) and you want a fallback for that state.

Gates only change what the interface shows. Enforce the limit on your server.

Three UpgradePrompt fallbacks shown by FeatureGate, PlanGate and UsageGate, light theme

Importing UsageGate

import {
  UsageGate,
  UpgradePrompt,
  type UsageGateProps,
} from '@nozle-js/react'

Rendering UsageGate

UsageGate has no look of its own and fetches nothing: you pass the usage and the limit.

components/new-project.tsx

export function NewProject({ used, limit }: { used: number; limit: number }) {
  return (
    <UsageGate usage={used} limit={limit} fallback={<UpgradePrompt text={`You used all ${limit} projects`} />}>
      <button type="button">New project</button>
    </UsageGate>
  )
}

Data

The gate needs two numbers: usage so far and limit. It has no loading state.

Live data

useEntitlement(featureCode) returns used and limit. A null limit means unlimited, so skip the gate then:

import { useEntitlement } from '@nozle-js/react'

export function ApiConsole() {
  const { data } = useEntitlement('api_calls')
  if (!data) return null
  const editor = <textarea aria-label="Request body" />
  if (data.limit === null) return editor
  return (
    <UsageGate usage={data.used ?? 0} limit={data.limit} fallback={<UpgradePrompt text="You used all your API calls" />}>
      {editor}
    </UsageGate>
  )
}

Examples

Upgrade prompt as fallback

At or above the limit the fallback renders, usually an UpgradePrompt. The screenshot shows the fallbacks of FeatureGate, PlanGate and UsageGate, each an UpgradePrompt.

export function Generate({ used, openPlans }: { used: number; openPlans: () => void }) {
  return (
    <UsageGate usage={used} limit={100} fallback={<UpgradePrompt text="You used all 100 generations this month" onUpgrade={openPlans} />}>
      <button type="button">Generate</button>
    </UsageGate>
  )
}

API reference

number

required

The usage so far.

number

required

The limit. At or above it, fallback renders.

ReactNode

required

The content available below the limit.

ReactNode

default:null

Rendered when usage >= limit.

States

State	What shows
`usage` below `limit`	`children`.
`usage` at or above `limit`	`fallback`, or nothing without one.

UsageGate has no loading state.

Appearance

UsageGate takes no appearance and has no element keys; style the fallback you pass.

UsageMeter

Show how close the limit is.

UsageAlert

Warn before the limit.

Setup

Components

Billing

Entitlements

Importing UsageGate

Rendering UsageGate

Data

Live data

Examples

Upgrade prompt as fallback

API reference

States

Appearance

UsageMeter

UsageAlert

​Importing UsageGate

​Rendering UsageGate

​Data

​Live data

​Examples

​Upgrade prompt as fallback

​API reference

​States

​Appearance

​Related

UsageMeter

UsageAlert

Importing UsageGate

Rendering UsageGate

Data

Live data

Examples

Upgrade prompt as fallback

API reference

States

Appearance

Related