> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nozle.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# UsageGate

> Shows content while usage is below its limit, and a fallback once the limit is reached.

`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.

**Light**

![Three UpgradePrompt fallbacks shown by FeatureGate, PlanGate and UsageGate, light theme](https://mintcdn.com/nozle-d78f01d8/Ae2cAgwEfN_SPqzG/images/react/components/gates/light.png?fit=max\&auto=format\&n=Ae2cAgwEfN_SPqzG\&q=85\&s=0414411c172fdb32ba1ab8688d81854d)

**Dark**

![Three UpgradePrompt fallbacks shown by FeatureGate, PlanGate and UsageGate, dark theme](https://mintcdn.com/nozle-d78f01d8/Ae2cAgwEfN_SPqzG/images/react/components/gates/dark.png?fit=max\&auto=format\&n=Ae2cAgwEfN_SPqzG\&q=85\&s=ddd64cbd1e0e0fbf421f4ce913d3cb5f)

**Minimal**

![Three UpgradePrompt fallbacks shown by FeatureGate, PlanGate and UsageGate, minimal theme](https://mintcdn.com/nozle-d78f01d8/Ae2cAgwEfN_SPqzG/images/react/components/gates/minimal.png?fit=max\&auto=format\&n=Ae2cAgwEfN_SPqzG\&q=85\&s=dc342269c821e58e8ca09ffa2b89102f)

**Neobrutal**

![Three UpgradePrompt fallbacks shown by FeatureGate, PlanGate and UsageGate, neobrutal theme](https://mintcdn.com/nozle-d78f01d8/Ae2cAgwEfN_SPqzG/images/react/components/gates/neobrutal.png?fit=max\&auto=format\&n=Ae2cAgwEfN_SPqzG\&q=85\&s=2e3abf2dec81f5e05736835e7cdb4a42)

**Nozle**

![Three UpgradePrompt fallbacks shown by FeatureGate, PlanGate and UsageGate, nozle theme](https://mintcdn.com/nozle-d78f01d8/Ae2cAgwEfN_SPqzG/images/react/components/gates/nozle.png?fit=max\&auto=format\&n=Ae2cAgwEfN_SPqzG\&q=85\&s=b567628265058dea4dd6daa05480c109)

**Nozle Dark**

![Three UpgradePrompt fallbacks shown by FeatureGate, PlanGate and UsageGate, nozleDark theme](https://mintcdn.com/nozle-d78f01d8/Ae2cAgwEfN_SPqzG/images/react/components/gates/nozle-dark.png?fit=max\&auto=format\&n=Ae2cAgwEfN_SPqzG\&q=85\&s=744f5323c74235888d0d005c54147e96)

## Importing UsageGate

```tsx theme={null}
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.

```tsx components/new-project.tsx theme={null}
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)`](/sdks/react/hooks#the-hooks) returns `used` and `limit`. A `null` limit means unlimited, so skip the gate then:

```tsx theme={null}
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`](/sdks/react/components/upgrade-prompt). The screenshot shows the fallbacks of [`FeatureGate`](/sdks/react/components/feature-gate), [`PlanGate`](/sdks/react/components/plan-gate) and `UsageGate`, each an `UpgradePrompt`.

![Three UpgradePrompt fallbacks shown by FeatureGate, PlanGate and UsageGate, light theme](https://mintcdn.com/nozle-d78f01d8/Ae2cAgwEfN_SPqzG/images/react/components/gates/light.png?fit=max\&auto=format\&n=Ae2cAgwEfN_SPqzG\&q=85\&s=0414411c172fdb32ba1ab8688d81854d)

```tsx theme={null}
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

**usage** `number` *required*

The usage so far.

**limit** `number` *required*

The limit. At or above it, `fallback` renders.

**children** `ReactNode` *required*

The content available below the limit.

**fallback** `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.

## Related

> **[UsageMeter](/sdks/react/components/usage-meter)**
>
> Show how close the limit is.

> **[UsageAlert](/sdks/react/components/usage-alert)**
>
> Warn before the limit.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.