ATOM Documentation

← Back to App

BudgetExceededBanner Component Usage

Overview

The BudgetExceededBanner component displays upgrade prompts when budget limit is reached or approached. It provides smart messaging based on utilization percentage and includes a plan comparison modal.

Component Location

/Users/rushiparikh/projects/atom-saas/src/components/billing/BudgetExceededBanner.tsx

Props

interface BudgetExceededBannerProps {
  currentPlan: string              // Current plan ID ('free', 'solo', 'team', 'enterprise')
  currentSpend: number            // Current spend in USD
  budgetLimit: number             // Budget limit in USD
  utilizationPercent: number      // Utilization percentage (0-100+)
  onUpgrade: () => void           // Callback when upgrade button clicked
  onIncreaseBudget: () => void    // Callback when increase budget button clicked
  className?: string              // Optional CSS classes
}

Features

1. Smart Warning Messages

The banner displays different messages based on utilization:

  • **90% utilization**: "⚠️ Approaching budget limit (90%)" (amber warning)
  • **95-99% utilization**: "⚠️ Budget limit reached" (red warning)
  • **100%+ utilization**: "🛑 Budget limit reached - exceeded by X%" (red critical)

2. Two Action Buttons

  • **"View Plans"** - Opens plan comparison modal with detailed comparison
  • **"Adjust Budget"** / **"Increase Budget"** - Opens budget edit dialog

3. Plan Comparison Modal

When clicking "View Plans", a modal shows:

  • Current plan vs next tier comparison table
  • ACU limits for each plan
  • Memory limits
  • Agent limits
  • Overage rates
  • Price difference
  • "Upgrade Now" and "Increase Budget Instead" buttons

4. Usage Projection

Calculates and displays when the budget will be exceeded based on current usage rate:

  • "At current rate, you'll exceed your budget by [date]"
  • Only shows when utilization is < 100% but on track to exceed

5. Upgrade Recommendation

Shows targeted upgrade messaging:

  • "Upgrade to Team plan for 10x more ACU"
  • Calculates actual ACU multiplier based on plan tiers

6. Dismissible

  • "X" button in top-right corner
  • Hides banner for current session only
  • Uses React state (not persisted)

Usage Example

'use client'

import { BudgetExceededBanner } from '@/components/billing/BudgetExceededBanner'
import { useState } from 'react'

export default function BillingSettingsPage() {
  const [isDialogOpen, setIsDialogOpen] = useState(false)
  const { data: budget } = useSWR('/api/billing/budget', fetchBudgetStatus)

  return (
    <div>
      {/* Banner shows when utilization >= 90% */}
      {budget && budget.utilization_percent >= 90 && (
        <BudgetExceededBanner
          currentPlan="solo"                    // or from session
          currentSpend={45.50}                  // from budget API
          budgetLimit={50.00}                   // from budget API
          utilizationPercent={91.0}             // from budget API
          onUpgrade={() => router.push('/pricing')}
          onIncreaseBudget={() => setIsDialogOpen(true)}
        />
      )}

      {/* Rest of billing page */}
    </div>
  )
}

Integration with Billing Page

The component is already integrated into the billing page at:

/Users/rushiparikh/projects/atom-saas/src/app/settings/billing/page.tsx

Implementation Details

// Import the component
import { BudgetExceededBanner } from '@/components/billing/BudgetExceededBanner'

// Add to the page (after imports, in main return)
{budget && budget.utilization_percent >= 90 && (
  <BudgetExceededBanner
    currentPlan={(session?.user as any)?.plan_type || 'free'}
    currentSpend={budget.current_spend_usd}
    budgetLimit={budget.budget_limit_usd}
    utilizationPercent={budget.utilization_percent}
    onUpgrade={() => router.push('/pricing')}
    onIncreaseBudget={() => setIsDialogOpen(true)}
  />
)}

Styling

The component uses:

  • **Tailwind CSS** for styling
  • **Lucide React** icons (AlertTriangle, TrendingUp, ArrowUpRight, X, Calendar)
  • **Existing design system** colors and patterns
  • **Responsive design** - adapts to mobile/desktop

Color Scheme

  • **90-94% utilization**: Amber warning colors
  • **95-100% utilization**: Red warning colors
  • **100%+ utilization**: Red critical colors

Plan Comparison Data

The component uses pricing data from:

/Users/rushiparikh/projects/atom-saas/src/lib/pricing/config.ts

Plan Tiers

  1. **Free** - $0/mo, 1,000 ACU
  2. **Solo** - $19/mo, 50,000 ACU (50x)
  3. **Team** - $79/mo, 300,000 ACU (6x from Solo, 300x from Free)
  4. **Enterprise** - $299/mo, Custom ACU

ACU Multipliers

The component automatically calculates ACU multipliers:

  • Free → Solo: 50x more ACU
  • Solo → Team: 6x more ACU
  • Team → Enterprise: Custom (no comparison shown)

TypeScript Support

Fully typed with TypeScript:

import { BudgetExceededBanner } from '@/components/billing/BudgetExceededBanner'

// All props are type-checked
// No runtime errors for missing props

Testing

To test the component, you can temporarily set different utilization percentages:

// Test 90% warning
<BudgetExceededBanner utilizationPercent={90} ... />

// Test 100% warning
<BudgetExceededBanner utilizationPercent={100} ... />

// Test exceeded (110%)
<BudgetExceededBanner utilizationPercent={110} ... />

Dependencies

  • React hooks: useState, useMemo
  • Lucide React icons
  • Existing UI components (Button)
  • Pricing config

Accessibility

  • role="alert" for screen readers
  • aria-live="polite" for polite announcements
  • Proper ARIA labels on buttons
  • Keyboard navigation support
  • High contrast colors for warnings

Future Enhancements

Potential improvements:

  1. **Persist dismissal** - Store in localStorage instead of session state
  2. **Custom threshold** - Allow users to set when banner appears (80%, 85%, etc.)
  3. **Multiple banners** - Show different banners for different warnings
  4. **Analytics tracking** - Track banner views and upgrade conversions
  5. **A/B testing** - Test different messaging and button placements