# React Native AI Usage Meter, tokens and credits (Pro)

> A React Native AI usage meter for iOS, Android and the web: tokens, credits or spend against the plan's limit, split by model, with the reset date, a forecast at the current pace, warning and over-limit states and Upgrade. Bar, ring, gauge, card and compact.

# AI usage meter Pro

How much of an AI allowance is used, as OpenAI's, Anthropic's and Vercel's usage pages show it: tokens, credits or spend against the plan's limit, split by model, with when it resets and where the current pace leads. It turns amber near the limit and red at it, says so in words, and offers Upgrade. A bar for settings, a ring or gauge for a dashboard, a full card, or one compact line for a header.

```tsx
import { AIUsageMeter } from '@patine-ui/pro';
```

```tsx live full
import { AIUsageMeter } from '@patine-ui/pro';

const byModel = [
  { key: 'gpt', label: 'GPT-5', value: 412000 },
  { key: 'claude', label: 'Claude', value: 268000, color: '#D97757' },
  { key: 'embed', label: 'Embeddings', value: 50000, color: '#06B6D4' },
];

export default function Example() {
  return (
    <AIUsageMeter
      title="Monthly tokens"
      used={730000}
      limit={1000000}
      breakdown={byModel}
      resetAt={new Date(Date.now() + 9 * 86400000)}
      forecast={980000}
      history={[12, 18, 15, 22, 30, 26, 34, 41]}
      onUpgrade={() => {}}
      style={{ width: 420 }}
    />
  );
}
```

## Example: AI credits in billing settings

A team plan's billing page: this month's AI spend in euros, split by team, with a warning from 75% and a forecast past the limit. Raise the limit and the meter settles.

```tsx live full
import { useState } from 'react';
import { View } from 'react-native';
import { SegmentedControl, Text } from 'patine-ui';
import { AIUsageMeter } from '@patine-ui/pro';

const TEAMS = [
  { key: 'support', label: 'Support', value: 182 },
  { key: 'eng', label: 'Engineering', value: 141, color: '#7C3AED' },
  { key: 'sales', label: 'Sales', value: 53, color: '#0891B2' },
];

export default function Example() {
  const [limit, setLimit] = useState(400);
  return (
    <View style={{ width: '100%', maxWidth: 440, gap: 12 }}>
      <AIUsageMeter
        title="AI credits, November"
        used={376}
        limit={limit}
        valueFormat="currency"
        currency="EUR"
        breakdown={TEAMS}
        warnAt={0.75}
        forecast={468}
        resetAt={new Date(new Date().getFullYear(), new Date().getMonth() + 1, 1)}
        history={[210, 260, 298, 344, 376]}
      />
      <Text size="sm" color="textSecondary">Monthly limit</Text>
      <SegmentedControl
        items={[{ label: '€400', value: '400' }, { label: '€600', value: '600' }, { label: '€1,000', value: '1000' }]}
        value={String(limit)}
        onValueChange={(v) => setLimit(Number(v))}
        accessibilityLabel="Monthly limit"
      />
    </View>
  );
}
```

## Amounts

`used` against `limit` (or `null` for unlimited) in `unit` (`'tokens'`, `'credits'`, `'requests'`…). `valueFormat` is `'compact'` (1.2M, the default), `'number'` or `'currency'` (values in cents); `formatValue` formats them your way. `breakdown` splits the bar or ring by part; parts that don't add up to `used` get the rest.

## Thresholds and forecast

At `warnAt` (0.8 of the limit) it turns amber and says "You've used 85% of your tokens"; at `dangerAt` (1) red, "You've reached your limit", and the bar shows how far over. `forecast` puts a tick where usage is heading by the reset, red when that passes the limit. `onUpgrade` adds Upgrade once it's amber (or always with `showUpgrade`).

```tsx live full
import { AIUsageMeter } from '@patine-ui/pro';

export default function Example() {
  const [used, setUsed] = React.useState(620);
  React.useEffect(() => {
    const id = setInterval(() => setUsed((u) => (u >= 1150 ? 620 : u + 45)), 900);
    return () => clearInterval(id);
  }, []);
  return <AIUsageMeter used={used} limit={1000} unit="credits" valueFormat="number" onUpgrade={() => {}} style={{ width: 400 }} />;
}
```

## Variants

`variant` is `'card'` (the default), `'bar'`, `'ring'`, `'gauge'` (a half ring) or `'compact'`.

```tsx live full
import { AIUsageMeter } from '@patine-ui/pro';

const byModel = [
  { key: 'chat', label: 'Chat', value: 320 },
  { key: 'image', label: 'Images', value: 140, color: '#EC4899' },
];

export default function Example() {
  return (
    <View style={{ gap: 24, width: 420 }}>
      <AIUsageMeter variant="bar" title="Requests today" used={460} limit={500} unit="requests" valueFormat="number" breakdown={byModel} />
      <View style={{ flexDirection: 'row', gap: 24 }}>
        <AIUsageMeter variant="ring" used={460} limit={1000} valueFormat="number" unit="credits" resetAt={new Date(Date.now() + 3 * 86400000)} />
        <AIUsageMeter variant="gauge" used={1240} limit={2000} valueFormat="currency" unit="spend" />
      </View>
      <AIUsageMeter variant="compact" used={5400} limit={null} unit="requests" valueFormat="number" />
    </View>
  );
}
```

## Accessibility

The bar is a progress bar whose value reads in full: "730K of 1M tokens, 270K left". Warnings are announced as alerts, and color is never the only cue: the state is also said in words.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `used` | `number` | — | |
| `limit` | `number \| null` | — | `null` for unlimited. |
| `unit` | `string` | `'tokens'` | |
| `valueFormat` | `'number'` \| `'compact'` \| `'currency'` | `'compact'` | |
| `currency` / `locale` / `formatValue` | | `'USD'` | |
| `breakdown` | `{ key, label, value, color? }[]` | — | |
| `variant` | `'card'` \| `'bar'` \| `'ring'` \| `'gauge'` \| `'compact'` | `'card'` | |
| `title` | `string` | `'Usage'` | |
| `resetAt` | `Date` \| `string` | — | "Resets in 5 days". |
| `warnAt` / `dangerAt` | `number` | `0.8` / `1` | Shares of the limit. |
| `forecast` | `number` | — | Usage expected by the reset. |
| `history` | `number[]` | — | A sparkline in the card. |
| `onUpgrade` / `showUpgrade` | | | |
| `showLegend` | `boolean` | with a breakdown | |
| `footer` | `ReactNode` | — | Replaces the card's footer. |
| `now` / `loading` | | | |
| `animate` / `labels` / `design` / `theme` / `accessibilityLabel` / `style` | | | |
