Staaarter

Billing Grace Period Countdown

An alert block for accounts with a failed payment that are still in a grace period before access is cut off. It shows days and hours remaining, a bar showing how much of the grace window has elapsed, and a resolve-payment button. Once the countdown reaches zero it swaps to a suspended-access state with a different message and a restore-access button.

By Staaarter Team
Billing
Updated July 14, 2026
Docs
Live preview

Docs

Installation

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

npx shadcn add https://staaarter.com/r/billing-grace-period-countdown.json

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

Usage

The file also exports billing63Demo, 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 { Billing63, billing63Demo } from "@/components/blocks/billing/billing63";

export default function Page() {
  return <Billing63 {...billing63Demo} />;
}

Props

PropTypeDefaultDescription
headingstring"Your account is in a grace period"Heading shown while the grace period is still active.
messagestringnoneSupporting sentence shown under the heading while active.
daysRemainingnumbernoneWhole days left in the grace period. Combine with hoursRemaining for the full remaining time.
hoursRemainingnumber0Additional hours left beyond daysRemaining.
totalGraceDaysnumbernoneThe full length of the grace period; when set, renders a progress bar showing how much time is left.
amountDuestringnoneOptional formatted amount shown under the countdown.
resolveLabelstring"Update payment method"Label on the action button while the grace period is active.
resolveHrefstringnoneDestination for the action button.
suspendedHeadingstring"Access suspended"Heading shown once the countdown reaches zero.
suspendedMessagestring(see source)Message shown once the countdown reaches zero.
classNamestringnoneExtra classes for the outer alert container.

Behavior notes

  • daysRemaining and hoursRemaining are plain numbers you compute server-side or on each page load from your own grace-period-end timestamp; the component never reads the clock itself, so there's no client/server render mismatch.
  • The suspended state activates when both daysRemaining and hoursRemaining are zero or less, swapping the heading, message, icon, and button label without any additional prop.
  • The optional progress bar only renders when totalGraceDays is passed; it shows the remaining fraction of the grace window, not the elapsed fraction.
  • The action button is a plain anchor rendered through the Button component's render prop, so resolveHref can point straight at your payment update page.
  • This component has no internal timer. If you want it to visibly count down while the page is open, recompute daysRemaining and hoursRemaining on an interval in the parent and pass fresh values down as props.

Frequently asked questions