Trial Expiry Card | Billing SDK

The Trial Expiry Card is a compact component designed for dashboards and sidebars. It shows a live countdown timer (days, hours, minutes, seconds) and a list of premium features to encourage upgrades.

Trial Period

Active

Days

Hours

Min

Sec

Included with upgrade

Unlimited API requests

Advanced analytics dashboard

Priority email support

Custom domain integration

src/components/trial-expiry-card-demo.tsx

"use client";

import { TrialExpiryCard } from "@/components/billingsdk/trial-expiry-card";

export default function TrialExpiryCardDemo() {
  // for demo set trial to expire in 5 days
  const trialEndDate = new Date();
  trialEndDate.setDate(trialEndDate.getDate() + 5);

  return (
    <div className="bg-background flex h-full min-h-[500px] w-full items-center justify-center rounded-lg border-2 p-6">
      <TrialExpiryCard
        trialEndDate={trialEndDate}
        onUpgrade={() => {
          console.log("Upgrade clicked");
        }}
        features={[
          "Unlimited API requests",
          "Advanced analytics dashboard",
          "Priority email support",
          "Custom domain integration",
        ]}
        className="w-full max-w-md"
      />
    </div>
  );
}

Installation

npx shadcn@latest add @billingsdk/trial-expiry-card

pnpm dlx shadcn@latest add @billingsdk/trial-expiry-card

yarn dlx shadcn@latest add @billingsdk/trial-expiry-card

bunx shadcn@latest add @billingsdk/trial-expiry-card

npx @billingsdk/cli add trial-expiry-card

pnpm dlx @billingsdk/cli add trial-expiry-card

yarn dlx @billingsdk/cli add trial-expiry-card

bunx @billingsdk/cli add trial-expiry-card

Usage

import { TrialExpiryCard } from "@/components/billingsdk/trial-expiry-card";

Basic Example with Live Countdown

// Using trialEndDate for real-time countdown
const trialEndDate = new Date("2025-10-15T23:59:59");

<TrialExpiryCard
  trialEndDate={trialEndDate}
  onUpgrade={() => {
    // Handle upgrade action
    console.log("User wants to upgrade");
  }}
/>

Using Days Remaining Only

// No live countdown, just days remaining
<TrialExpiryCard
  daysRemaining={5}
  onUpgrade={() => {
    // Handle upgrade action
  }}
  upgradeButtonText="Go Premium"
/>

With Custom Features

<TrialExpiryCard
  trialEndDate="2025-10-20T23:59:59"
  features={[
    "Unlimited API requests",
    "Advanced analytics dashboard",
    "Priority email support",
    "Custom domain integration",
  ]}
  onUpgrade={() => {
    // Handle upgrade action
  }}
/>

Custom Title and Description

<TrialExpiryCard
  trialEndDate="2025-10-20"
  title="Premium Trial"
  description="Experience all premium features"
  upgradeButtonText="Subscribe Now"
  onUpgrade={() => {
    router.push("/upgrade");
  }}
/>

Live Countdown Timer

When using trialEndDate, the card displays a real-time countdown showing:

Days remaining
Hours remaining
Minutes remaining
Seconds remaining

The timer automatically updates every second until the trial expires.

Status Badges

The card displays automatic status badges based on days remaining:

Expired (0 days)

Red "Expired" badge
Timer shows all zeros

Critical (1-2 days)

Red "Expiring Soon" badge
Urgent visual emphasis

Warning (3-6 days)

Gray "Active" badge
Moderate visual emphasis

Info (7+ days)

Blue "Active" badge
Calm visual emphasis

Props

Prop	Type	Required	Description
`trialEndDate`	`Date \| string`	❌	The trial end date (ISO string or Date object). Enables live countdown.
`daysRemaining`	`number`	❌	Direct number of days remaining (alternative to trialEndDate). No live countdown.
`onUpgrade`	`() => void \| Promise<void>`	❌	Callback function when upgrade button is clicked
`className`	`string`	❌	Additional CSS classes for styling
`title`	`string`	❌	Card title (default: "Trial Period")
`description`	`string`	❌	Card description text
`upgradeButtonText`	`string`	❌	Custom text for upgrade button (default: "Upgrade Now")
`features`	`string[]`	❌	List of premium features to display (max 4 shown)

Features

Real-Time Countdown: Live updating timer when using trialEndDate
Flexible Display: Use trialEndDate for live countdown or daysRemaining for static days
Feature Highlights: Display up to 4 premium features with checkmark icons
Status Badges: Automatic badge colors based on urgency
Responsive Design: Adapts to different container widths
Dark Mode Support: Fully themed for light and dark modes
Loading States: Built-in loading state for async upgrade actions

Notes

Either trialEndDate or daysRemaining must be provided
If both are provided, daysRemaining takes precedence
The countdown timer only appears when using trialEndDate and days > 0
Maximum of 4 features displayed (first 4 from array)
Timer updates every second using React's useEffect and setInterval
Fully supports dark mode theming

Example

src/components/trial-expiry-card-demo.tsx

"use client";

import { TrialExpiryCard } from "@/components/billingsdk/trial-expiry-card";

export default function TrialExpiryCardDemo() {
  // for demo set trial to expire in 5 days
  const trialEndDate = new Date();
  trialEndDate.setDate(trialEndDate.getDate() + 5);

  return (
    <div className="bg-background flex h-full min-h-[500px] w-full items-center justify-center rounded-lg border-2 p-6">
      <TrialExpiryCard
        trialEndDate={trialEndDate}
        onUpgrade={() => {
          console.log("Upgrade clicked");
        }}
        features={[
          "Unlimited API requests",
          "Advanced analytics dashboard",
          "Priority email support",
          "Custom domain integration",
        ]}
        className="w-full max-w-md"
      />
    </div>
  );
}

Trial Expiry CardPlaygroundCopy Page

Included with upgrade

Trial Expiry Card
Playground