@quotadev/react

Drop-in React components for displaying AI usage and billing to your customers.

Install

npm install @quotadev/react @quotadev/sdk

Quick Start

Wrap your app with QuotaProvider, then use the components anywhere:

import { QuotaProvider, UsageMeter, UsageHistory } from "@quotadev/react";

function App() {
  return (
    <QuotaProvider apiKey={process.env.QUOTA_API_KEY}>
      <Dashboard />
    </QuotaProvider>
  );
}

function Dashboard() {
  return (
    <>
      <UsageMeter
        customerId="cus_abc123"
        feature="ai-summarization"
        showUpgradePrompt
        upgradeUrl="/pricing"
      />
      <UsageHistory
        customerId="cus_abc123"
        period="current_month"
        theme="dark"
      />
    </>
  );
}

Components

<QuotaProvider>

Context provider that configures the SDK for all child components.

| Prop | Type | Default | Description | | --------- | -------- | -------------------------- | ------------------ | | apiKey | string | — | Your Quota API key | | baseUrl | string | https://api.usequota.dev | API base URL |

<UsageMeter>

Displays current usage as a progress bar with optional upgrade prompt.

| Prop | Type | Default | Description | | ------------------- | ---------------------- | ------- | -------------------------------- | | customerId | string | — | Customer to show usage for | | feature | string | — | Filter by feature | | showUpgradePrompt | boolean | false | Show prompt when near/over limit | | upgradeUrl | string | — | URL for the upgrade CTA | | label | string | — | Custom label text | | size | "sm" \| "md" \| "lg" | "md" | Size variant | | className | string | — | Custom CSS class |

<UsageHistory>

Displays usage history as a chart or table.

| Prop | Type | Default | Description | | ------------ | ---------------------------------------------------- | ----------------- | ---------------------------- | | customerId | string | — | Customer to show history for | | period | "current_month" \| "last_30_days" \| "last_7_days" | "current_month" | Time period | | feature | string | — | Filter by feature | | theme | "light" \| "dark" \| "auto" | "auto" | Color theme | | view | "chart" \| "table" | "chart" | Display mode | | className | string | — | Custom CSS class |

Hooks

useQuota()

Returns a configured Quota SDK instance from context.

import { useQuota } from "@quotadev/react";

function MyComponent() {
  const quota = useQuota();

  const handleAction = async () => {
    const check = await quota.check({
      customerId: "cus_abc123",
      feature: "ai-summarization",
      estimatedTokens: 500,
    });

    if (!check.allowed) {
      alert("Usage limit reached");
    }
  };
}

useUsage(options)

Fetches current usage data for a customer.

import { useUsage } from "@quotadev/react";

function UsageDisplay() {
  const { data, isLoading, error } = useUsage({
    customerId: "cus_abc123",
    feature: "ai-summarization",
    pollInterval: 30000, // refresh every 30s
  });

  if (isLoading) return <span>Loading...</span>;
  if (!data) return null;

  return (
    <div>
      <p>{data.tokens.toLocaleString()} tokens used</p>
      <p>{data.percentUsed}% of limit</p>
    </div>
  );
}

useHistory()

Fetches usage history records for a customer.

Peer Dependencies

• react >= 18
• react-dom >= 18

License

MIT