[ [UI.120] Credits ] Balance Display

Balance Display

> Shows the user's current AI credit balance with a progress bar indicating usage against monthly allowance. Color-coded to show remaining capacity.

Import

[ [0x5B] IMPORT ]

1import { BalanceDisplay } from "@/components/credits"

Preview

[ [0x00] BALANCE DISPLAY ]

[CREDITS]:

750 / 1000

starter tier

1<BalanceDisplay />

Variants

[ [0x00] COMPACT MODE ]

750

1<BalanceDisplay compact />

[ [0x00] LOW BALANCE WARNING ]

[CREDITS]:

350 / 1000

starter tier

1// Automatically shows warning when balance < 50%

[ [0x00] CRITICAL BALANCE ]

[CREDITS]:

150 / 1000

starter tier

1// Automatically shows critical when balance < 20%

[ [0x00] DIFFERENT TIERS ]

[CREDITS]:

80 / 100

free tier

[CREDITS]:

800 / 1000

starter tier

[CREDITS]:

8000 / 10000

pro tier

1// Tier displayed automatically from user's subscription

API Reference

[ [0x00] API REFERENCE ]

Prop	Type	Default	Description
className	`string`	-	Additional CSS classes to apply.
compact	`boolean`	`false`	Show minimal display with just the credit count.

Usage

[ [0xF8] DASHBOARD INTEGRATION ]

Add to user dashboard to show current credit balance. Automatically fetches from /api/credits/balance.

1'use client';
2
3import { BalanceDisplay } from '@/components/credits';
4
5export default function DashboardPage() {
6  return (
7    <div className="space-y-6">
8      <h1>Dashboard</h1>
9
10      {/* Auto-fetches balance, tier, and allowance */}
11      <BalanceDisplay />
12
13      {/* Compact mode for sidebars/headers */}
14      <BalanceDisplay compact />
15    </div>
16  );
17}

[ [0xDC] REQUIRED API ENDPOINT ]

The component expects GET /api/credits/balance to return this format:

1// GET /api/credits/balance response
2{
3  "balance": 750,
4  "monthlyAllowance": 1000,
5  "tier": "starter",
6  "lastRefill": "2024-12-01T00:00:00.000Z"
7}
8
9// Already implemented at:
10// src/app/api/credits/balance/route.ts

[ [0x81] COLOR STATES ]

Progress bar automatically changes color based on remaining credits:

1// Green (bg-primary): > 50% remaining
2// Yellow (bg-warning): 20-50% remaining
3// Red (bg-destructive): < 20% remaining
4
5// Example: 750/1000 = 75% = Green
6// Example: 350/1000 = 35% = Yellow
7// Example: 150/1000 = 15% = Red

Accessibility

[ [0x58] A11Y ]

Progress bar indicates remaining credits visually
Color-coded states (green/yellow/red) for quick recognition
Numeric display provides exact values
Tier label indicates subscription level

Variants

[ [0x00] COMPACT MODE ]

750

1<BalanceDisplay compact />

[ [0x00] LOW BALANCE WARNING ]

[CREDITS]:

350 / 1000

starter tier

1// Automatically shows warning when balance < 50%

[ [0x00] CRITICAL BALANCE ]

[CREDITS]:

150 / 1000

starter tier

1// Automatically shows critical when balance < 20%

[ [0x00] DIFFERENT TIERS ]

[CREDITS]:

80 / 100

free tier

[CREDITS]:

800 / 1000

starter tier

[CREDITS]:

8000 / 10000

pro tier

1// Tier displayed automatically from user's subscription

Prop

Type

Default

Description

className

string

Additional CSS classes to apply.

compact

boolean

false

Show minimal display with just the credit count.

Usage

[ [0xF8] DASHBOARD INTEGRATION ]

Add to user dashboard to show current credit balance. Automatically fetches from /api/credits/balance.

1'use client';
2
3import { BalanceDisplay } from '@/components/credits';
4
5export default function DashboardPage() {
6  return (
7    <div className="space-y-6">
8      <h1>Dashboard</h1>
9
10      {/* Auto-fetches balance, tier, and allowance */}
11      <BalanceDisplay />
12
13      {/* Compact mode for sidebars/headers */}
14      <BalanceDisplay compact />
15    </div>
16  );
17}

[ [0xDC] REQUIRED API ENDPOINT ]

The component expects GET /api/credits/balance to return this format:

1// GET /api/credits/balance response
2{
3  "balance": 750,
4  "monthlyAllowance": 1000,
5  "tier": "starter",
6  "lastRefill": "2024-12-01T00:00:00.000Z"
7}
8
9// Already implemented at:
10// src/app/api/credits/balance/route.ts

[ [0x81] COLOR STATES ]

Progress bar automatically changes color based on remaining credits:

1// Green (bg-primary): > 50% remaining
2// Yellow (bg-warning): 20-50% remaining
3// Red (bg-destructive): < 20% remaining
4
5// Example: 750/1000 = 75% = Green
6// Example: 350/1000 = 35% = Yellow
7// Example: 150/1000 = 15% = Red