# Credits meter

> A balance pill for an app bar whose digits roll when the balance changes and which turns warning colored when low, plus CreditsCost, a live price line that says what a job costs and what is left after it.

- Type: Component (data)
- Access: Free, open source (MIT)
- Page: https://goodui.dev/native/components/credits-meter
- Markdown: https://goodui.dev/native/components/credits-meter.md
- Registry item: https://goodui.dev/native/r/credits-meter.json
- Dependencies: react-native-reanimated, react-native-svg
- Keywords: react native credits, token balance pill, usage meter, ai credits ui, cost before generate

## When to use

- Apps where actions spend a balance, such as generations or scans.
- Showing the price of a job before it starts, as options change.

## When not to use

- Money balances: use rolling-number with a currency format.
- Plain usage limits with no balance: use a progress ring.

## Installation

With the shadcn CLI (needs a components.json in the Expo app), then `npx expo install --fix` so native dependencies match your Expo SDK. The foundation comes along the first time.

```bash
npx shadcn@latest add https://goodui.dev/native/r/credits-meter.json
npx expo install --fix
```

The component lands in `components/goodui-native/credits-meter/` and imports the foundation from `components/goodui-native/foundation/` with relative paths; it also installs locale, rolling-number.

Built-in strings follow `<GooduiLocaleProvider>` (one [language pack](https://goodui.dev/native/r/locale-tr.json) translates the whole kit); the `labels` prop overrides them for one instance.

## Usage

```tsx
import { CreditsCost, CreditsMeter } from "@/components/goodui-native/credits-meter/credits-meter";

<CreditsMeter balance={credits.balance} lowAt={10} total={40} onPress={() => router.push("/paywall")} />
<CreditsCost cost={quality === "high" ? 8 : 4} balance={credits.balance} />
```

## API reference

### CreditsMeter

`import { CreditsMeter } from "@/components/goodui-native/credits-meter/credits-meter";`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `balance` (required) | `number` | – | Credits left. Changes roll the digits; a drop gives the pill a small kick. |
| `lowAt` | `number` | `10` | At or below this the pill turns warning colored. |
| `total` | `number` | – | Plan allowance. When set, a thin bar under the number shows the share left. |
| `onPress` | `() => void` | – | Opens the store. |
| `labels` | `Partial<CreditsMeterLabels>` | – | – |
| `style` | `StyleProp<ViewStyle>` | – | Style for the outer container. |
| `testID` | `string` | – | Identifier for end-to-end tests. |

### CreditsCost

`import { CreditsCost } from "@/components/goodui-native/credits-meter/credits-meter";`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `cost` (required) | `number` | – | What the current options cost. Rolls live as they change. |
| `balance` (required) | `number` | – | Current balance, for the "left after" line. |
| `labels` | `Partial<CreditsCostLabels>` | – | – |
| `style` | `StyleProp<ViewStyle>` | – | Style for the outer container. |
| `testID` | `string` | – | Identifier for end-to-end tests. |

## Accessibility

- The pill is read as one element with the balance in words, or as a button with a hint when onPress is set.
- CreditsCost is a polite live region, so changes to the price are announced.

## Motion

- Digits roll on every change, and the pill gives a small kick when the balance drops.
- The thin allowance bar springs to its new width.
- Reduced motion: no kick, and the bar jumps to its width.

## Haptics

- Pressing the pill uses the tap cue.

## Performance

- Built on RollingNumber. Changes run on the UI thread.

## Notes for AI

- Show the server's balance. Pair with useCredits from ai-provider while mocking.
- CreditsCost warns when cost is above balance; disable the action yourself in that case.
- CreditBolt is exported for use beside prices elsewhere in the app.

## Related

- [AI provider](https://goodui.dev/native/components/ai-provider.md): The logic layer behind the AI components, with no UI: a typed provider adapter with an offline mock, a credit ledger that keeps subscription and bought credits apart, and a generation queue that charges, refunds and retries.
- [Rolling number](https://goodui.dev/native/components/rolling-number.md): A number whose digits roll in the direction of change, with digits that open and close in place and currency signs that glide instead of jumping.
- [AI paywall screen](https://goodui.dev/native/components/ai-paywall-screen.md): A paywall for AI apps with weekly and yearly plans that each carry a credit allowance. The billed amount is always the largest price, weekly math stays in small text, the auto-renew line sits next to the buy button, and Terms, Privacy and Restore are always shown. check-kit fails if a price variant breaks this.
- [Generation queue](https://goodui.dev/native/components/generation-queue.md): Cards for long AI jobs: each one shows its status, a fill and a light sweep while running, a rolling percentage, and cancel, retry and open actions.

## Guidance for AI tools

Credits meter: A balance pill for an app bar whose digits roll when the balance changes and which turns warning colored when low, plus CreditsCost, a live price line that says what a job costs and what is left after it. Use only the documented props. Keep accessibility, reduced motion and both color schemes intact when adapting it.

Full library index: https://goodui.dev/native/llms.txt