Does Save actually update anything on the backend?

No. Clicking Save only updates local component state and shows a confirmation message. Call your own API from handleSave to persist the caps.

How do I enforce the hard cap once it's saved?

This component only collects the values. Store them in your database, and check the customer's current usage against the hard cap before processing further metered requests.

What does the throttle switch actually control?

In this component it just tracks on/off state. Use it as a flag your backend reads to decide whether to hard-stop usage or allow overages once the cap is hit.

Can the alert threshold be higher than the hard cap?

No, the Save button is disabled and an inline message appears if you try. The threshold has to be at or below the hard cap.

Is there a slider instead of a number input?

No, this component uses plain number inputs for both caps rather than a slider, so it works without any extra Radix-based slider dependency.

Can I use this for more than one resource type?

Render one instance per resource (for example, one for API credits and one for storage), each with its own resourceLabel and cap values.

Billing Usage Cap Settings

A settings panel for letting customers control their own spending on metered resources. Two number inputs set an alert threshold and a hard cap, a switch turns on automatic throttling once the hard cap is hit, and a Save button confirms the change. The alert threshold is validated against the hard cap before saving is allowed.

By Staaarter Team

Billing

Updated July 2, 2026

Docs

Live preview

Docs

Installation

A real shadcn registry command, not a copy-paste stand-in: it fetches this block plus its button, input, label dependencies and any missing npm packages, and installs them straight into your project.

npx shadcn add https://staaarter.com/r/billing-usage-cap-settings.json

Prefer not to use the CLI? Copy the source from the Code toggle above into src/components/blocks/billing/billing146.tsx instead.

Usage

The file also exports billing146Demo, the exact props behind the preview above. Spread it to get a working section in one line, then replace it with your own data.

import { Billing146, billing146Demo } from "@/components/blocks/billing/billing146";

export default function Page() {
  return <Billing146 {...billing146Demo} />;
}

Props

Prop	Type	Default	Description
heading	string	"Usage cap settings"	Heading at the top of the panel.
description	string	none	Optional one-line note under the heading.
resourceLabel	string	"API credits"	Name of the metered resource, used in the threshold label and throttle copy.
currentUsageNote	string	none	Optional line showing how much has been used so far this cycle.
currencySymbol	string	"$"	Symbol shown before both number inputs.
defaultSoftCap	number	none	Starting value of the alert-threshold input.
defaultHardCap	number	none	Starting value of the hard-cap input.
defaultThrottleEnabled	boolean	false	Whether the automatic-throttle switch starts on.
saveLabel	string	"Save changes"	Label on the save button.
className	string	none	Extra classes for the outer container.

Behavior notes

Both cap fields and the throttle switch are local state; editing any of them clears the 'Saved' confirmation shown after a prior save.
Save is blocked, and the button disabled, whenever the alert threshold is entered higher than the hard cap; an inline error explains why.
Clicking Save only flips a local 'saved' flag that shows a checkmark and 'Saved' text, no network request is made. Wire handleSave's call site to your API to actually persist the values.
The throttle switch is a hand-built button with role="switch" and aria-checked, matching the toggle pattern used elsewhere in this category, since the UI kit has no Switch primitive.
Both number inputs use type="number" with inputMode="decimal" so mobile keyboards show a numeric pad, but the component does not clamp typed values beyond the soft-cap-vs-hard-cap check.

Frequently asked questions

More Billing Blocks

View all →

Billing Invoice List

Invoice history table with status badges, formatted amounts, and a per-row download link, built with shadcn/ui and Tailwind CSS.

Billing Failed Payment Alert

High-contrast failed-payment alert with a message, a retry button, and an optional update-payment-method button, built with shadcn/ui and Tailwind CSS.

Billing Credit Balance

Compact credit balance card with a large total, an optional purchased-versus-promotional breakdown, a low-balance notice, and a top-up button.

Billing Payment Methods

A saved payment method list for React and Next.js with brand icons, a default badge, near-expiry warnings, and remove/set-default actions per row.

Billing Add Card

A card entry form for React and Next.js with auto-formatted fields, internal brand detection, and per-field validation feedback built with shadcn/ui and Tailwind CSS.

Billing Coupon Code

An inline promo code input for React and Next.js with a simulated loading state, an applied summary showing the discount amount, and an invalid-code message.