# Billing SDK CLI Reference
URL: /docs/cli

Complete guide to the Billing SDK CLI for project setup and component management

***

title: Billing SDK CLI Reference
description: Complete guide to the Billing SDK CLI for project setup and component management
---------------------------------------------------------------------------------------------

import { Callout } from 'fumadocs-ui/components/callout'
import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
import { Cards, Card } from 'fumadocs-ui/components/card'

The Billing SDK CLI is a powerful command-line tool that helps you initialize new billing projects, add components, and manage your billing infrastructure with ease.

## Installation

The CLI is published as an npm package and can be used with `npx` without installation:

```bash
npx @billingsdk/cli --help
```

For frequent use, you can install it globally:

```bash
npm install -g @billingsdk/cli
@billingsdk/cli --help
```

## Quick Start

```bash
# Initialize a project (interactive)
npx @billingsdk/cli init

# Add a component to an existing project
npx @billingsdk/cli add <component-name>
```

## Commands

<Cards>
  <Card title="init">
    Initialize a new billing project with framework setup and payment provider integration
  </Card>

  <Card title="add">
    Add individual billing components to your existing project
  </Card>

  <Card title="build">
    Build the component registry for distribution (developer tool)
  </Card>
</Cards>

## Supported Frameworks

| Framework  | Dodo Payments | Stripe      |
| ---------- | ------------- | ----------- |
| Next.js    | Yes           | Yes         |
| Express.js | Yes           | Yes         |
| Hono       | Yes           | Yes         |
| NestJS     | Yes           | Yes         |
| React      | Yes           | Yes         |
| Fastify    | Yes           | Coming soon |

## Supported Payment Providers

### Dodo Payments

* ✅ **Status**: Fully supported
* 📚 **Integration**: Next.js, Express.js, React.js, Hono, Fastify

### Stripe

* ✅ **Status**: Supported for Next.js, React.js, Express.js, and Hono
* 📚 **Integration**: Next.js, React.js, Express.js, Hono
* 🚧 **Adding Soon**: Fastify

## `@billingsdk/cli init`

Initialize a new billing project with complete setup including framework configuration, payment provider integration, and essential dependencies.

### Usage

```bash
npx @billingsdk/cli init
```

### What it does

1. **Framework Selection**: Choose your preferred framework (Next.js, Express.js, Hono, NestJS, Fastify)
2. **Provider Selection**: Select your payment provider (currently Dodo Payments)
3. **Template Installation**: Downloads and installs framework-specific templates
4. **Dependency Management**: Automatically installs required dependencies
5. **File Generation**: Creates necessary configuration files and boilerplate code

### Interactive Setup

The command launches an interactive setup process:

```bash
npx @billingsdk/cli init
```

You'll be prompted to select:

* **Framework**: Next.js (with App Router), Express.js (Node.js web framework), Hono (lightweight web framework for edge runtimes), NestJS (progressive Node.js framework), Fastify (fast and low overhead web framework)
* **Payment Provider**: Dodo Payments or Stripe (Stripe currently supported for Express.js and Hono)

### Generated Files (Dodo Payments)

After running `init` with Dodo Payments, you'll get:

<Tabs items={['Next.js + Dodo Payments', 'Express.js + Dodo Payments', 'React.js + Dodo Payments', 'Hono + Dodo Payments', 'NestJS + Dodo Payments', 'Fastify + Dodo Payments']}>
  <Tab value="Next.js + Dodo Payments">
    ```
    your-project/
    ├── app/api/
    │   ├── (dodopayments)/
    │   │   ├── checkout/route.ts
    │   │   ├── customer/route.ts
    │   │   ├── customer/payments/route.ts
    │   │   ├── customer/subscriptions/route.ts
    │   │   ├── product/route.ts
    │   │   ├── products/route.ts
    │   │   └── webhook/route.ts
    ├── hooks/
    │   └── useBilling.ts
    ├── lib/
    │   └── dodopayments.ts
    └── .env.example
    ```
  </Tab>

  <Tab value="Express.js + Dodo Payments">
    ```
    your-project/
    ├── lib/
    │   └── dodopayments.ts
    └── routes/
        └── dodopayments/
            ├── route.ts
            ├── checkout.ts
            ├── customer.ts
            ├── payments.ts
            ├── products.ts
            ├── subscriptions.ts
            └── webhook.ts
    .env.example
    ```
  </Tab>

  <Tab value="React.js + Dodo Payments">
    ```
    your-project/
    ├── hooks/
    │   └── dodopayments/
    │       └── useBilling.ts
    ├── lib/
    │   └── dodopayments.ts
    .env.example
    ```
  </Tab>

  <Tab value="Hono + Dodo Payments">
    ```
    your-project/
    ├── lib/
    │   └── dodopayments.ts
    └── routes/
        ├── route.ts
        └── dodopayments/
            ├── checkout.ts
            ├── customer.ts
            ├── payments.ts
            ├── products.ts
            ├── subscriptions.ts
            └── webhook.ts
    .env.example
    ```
  </Tab>

  <Tab value="NestJS + Dodo Payments">
    ```
    your-project/
    ├── lib/
    │   └── dodopayments.ts
    └── modules/
        └── dodopayments/
            ├── checkout.controller.ts
            ├── customer.controller.ts
            ├── dodopayments.module.ts
            ├── payments.controller.ts
            ├── products.controller.ts
            ├── subscriptions.controller.ts
            └── webhook.controller.ts
    .env.example
    ```
  </Tab>

  <Tab value="Fastify + Dodo Payments">
    ```
    your-project/
    ├── lib/
    │   └── dodopayments.ts
    └── routes/
        └── dodopayments/
            ├── route.ts
            ├── checkout.ts
            ├── customer.ts
            ├── payments.ts
            ├── products.ts
            ├── subscriptions.ts
            └── webhook.ts
    .env.example
    ```
  </Tab>
</Tabs>

### Generated Files (Stripe)

After running `init` with Stripe, you'll get:

<Tabs items={['Next.js + Stripe', 'React.js + Stripe', 'Express.js + Stripe', 'Hono + Stripe', 'NestJS + Stripe']}>
  <Tab value="Next.js + Stripe">
    ```
    your-project/
    ├── app/api/
    │   └── (stripe)/
    │       ├── checkout
    │       ├── customer
    │       ├── payments
    │       ├── products
    │       ├── subscriptions
    │       └── webhook
    ├── hooks/
    │   └── useBilling.ts
    ├── lib/
    │   └── stripe.ts
    .env.example
    ```
  </Tab>

  <Tab value="React.js + Stripe">
    ```
    your-project/
    ├── hooks/
    │   └── stripe/
    │       └── useBilling.ts
    ├── lib/
    │   └── stripe.ts
    .env.example
    ```
  </Tab>

  <Tab value="Express.js + Stripe">
    ```
    your-project/
    ├── lib/
    │   └── stripe.ts
    └── routes/
        └── stripe/
            ├── route.ts
            ├── checkout.ts
            ├── customer.ts
            ├── payments.ts
            ├── products.ts
            ├── subscriptions.ts
            └── webhook.ts
    .env.example
    ```
  </Tab>

  <Tab value="Hono + Stripe">
    ```
    your-project/
    ├── lib/
    │   └── stripe.ts
    └── routes/
        ├── route.ts
        └── stripe/
            ├── checkout.ts
            ├── customer.ts
            ├── payments.ts
            ├── products.ts
            ├── subscriptions.ts
            └── webhook.ts
    .env.example
    ```
  </Tab>

  <Tab value="NestJS + Stripe">
    ```
    your-project/
    ├── lib/
    │   └── stripe.ts
    └── modules/
        └── stripe/
            ├── checkout.controller.ts
            ├── customer.controller.ts
            ├── payments.controller.ts
            ├── products.controller.ts
            ├── stripe.module.ts
            ├── subscriptions.controller.ts
            └── webhook.controller.ts
    .env.example
    ```
  </Tab>
</Tabs>

### API Routes Included

The init command sets up comprehensive API routes for:

* **Checkout**: Payment processing and order creation
* **Customer Management**: Customer data and subscription handling
* **Product Management**: Product catalog and pricing
* **Webhook Handling**: Payment provider webhook integration

### Setup Instructions

<details>
  <summary><strong>Next.js Setup Instructions</strong></summary>

  ### Basic Next.js Integration

  After running `@billingsdk/cli init` and selecting Next.js, the CLI scaffolds API routes under `app/api/(dodopayments)/*` and adds `lib/dodopayments.ts` and `hooks/useBilling.ts`.

  * Routes are auto-registered by the App Router. No extra wiring is required.
  * Client components can call the API directly or use `hooks/useBilling.ts`.

  #### Environment Configuration

  Copy `.env.example` to `.env.local` in the project root and set:

  ```bash
  # DodoPayments
  DODO_PAYMENTS_API_KEY=your_api_key_here
  DODO_PAYMENTS_ENVIRONMENT=test_mode
  DODO_PAYMENTS_WEBHOOK_KEY=your_webhook_key_here

  # App URL
  NEXT_PUBLIC_APP_URL=http://localhost:3000
  ```

  #### Using the billing hook (optional)

  ```tsx
  // app/(or any client component)
  "use client"
  import { useEffect } from 'react'
  import { useBilling } from "@/app/hooks/useBilling"

  export default function BillingExample() {
    const { fetchProducts } = useBilling()

    useEffect(() => {
      fetchProducts().catch(console.error)
    }, [fetchProducts])

    return null
  }
  ```
</details>

<details>
  <summary><strong>Express.js Setup Instructions</strong></summary>

  ### Basic Express.js Integration

  After running `@billingsdk/cli init` and selecting Express.js, you'll need to integrate the generated routes into your Express application:

  ```javascript
  // app.js or server.js
  const express = require('express');
  const { dodopaymentsRouter } = require('./src/routes/dodopayments/route');

  const app = express();

  // Middleware
  app.use(express.json());

  // Mount DodoPayments routes
  app.use('/api/dodopayments', dodopaymentsRouter);

  // Start server
  const PORT = process.env.PORT || 3000;
  app.listen(PORT, () => {
    console.log(`Server running on port ${PORT}`);
  });
  ```

  #### Environment Configuration

  Create a `.env` file in your project root:

  ```bash
  # DodoPayments Configuration
  DODO_PAYMENTS_API_KEY=your_api_key_here
  DODO_PAYMENTS_ENVIRONMENT=test_mode
  DODO_PAYMENTS_WEBHOOK_KEY=your_webhook_key_here

  # Server Configuration
  PORT=3000
  NODE_ENV=development
  ```

  #### TypeScript Support

  The template includes full TypeScript support. To use with TypeScript:

  ```bash
  npm install -D typescript @types/node ts-node nodemon
  ```

  Create a `tsconfig.json`:

  ```json
  {
    "compilerOptions": {
      "target": "ES2020",
      "module": "commonjs",
      "lib": ["ES2020"],
      "outDir": "./dist",
      "rootDir": "./src",
      "strict": true,
      "esModuleInterop": true,
      "skipLibCheck": true,
      "forceConsistentCasingInFileNames": true,
      "resolveJsonModule": true
    },
    "include": ["src/**/*"],
    "exclude": ["node_modules", "dist"]
  }
  ```

  Update your `package.json` scripts:

  ```json
  {
    "scripts": {
      "dev": "nodemon --exec ts-node src/app.ts",
      "build": "tsc",
      "start": "node dist/app.js"
    }
  }
  ```
</details>

<details>
  <summary><strong>Hono Setup Instructions</strong></summary>

  ### Basic Hono Integration

  After running `@billingsdk/cli init` and selecting Hono, you'll need to integrate the generated routes into your Hono application:

  ```typescript
  // src/index.ts
  import { Hono } from 'hono'
  import { dodopaymentsRouter } from './routes/route'

  const app = new Hono()

  // Mount DodoPayments routes
  app.route('/api/dodopayments', dodopaymentsRouter)

  // Start server
  export default app
  ```

  #### Environment Configuration

  Create a `.env` file in your project root:

  ```bash
  # DodoPayments Configuration
  DODO_PAYMENTS_API_KEY=your_api_key_here
  DODO_PAYMENTS_ENVIRONMENT=test_mode
  DODO_PAYMENTS_WEBHOOK_KEY=your_webhook_key_here

  # Server Configuration
  PORT=3000
  ```

  #### Running with Bun

  Hono works great with Bun. To run your application:

  Add this to your `package.json` scripts:

  ```json
  {
    "scripts": {
      "dev": "bun run --hot src/routes/route.ts"
    }
  }
  ```
</details>

<details>
  <summary><strong>NestJS Setup Instructions</strong></summary>

  ### Basic NestJS Integration

  After running `@billingsdk/cli init` and selecting NestJS, you'll need to integrate the generated modules into your NestJS application:

  ```typescript
  // src/app.module.ts
  import { Module } from '@nestjs/common';
  import { DodoPaymentsModule } from './modules/dodopayments/dodopayments.module';
  import { StripeModule } from './modules/stripe/stripe.module';

  @Module({
    imports: [DodoPaymentsModule, StripeModule],
  })
  export class AppModule {}
  ```

  #### Environment Configuration

  Create a `.env` file in your project root:

  ```bash
  # DodoPayments Configuration
  DODO_PAYMENTS_API_KEY=your_api_key_here
  DODO_PAYMENTS_ENVIRONMENT=test_mode
  DODO_PAYMENTS_WEBHOOK_KEY=your_webhook_key_here

  # Stripe Configuration
  STRIPE_API_KEY=your_api_key_here
  STRIPE_WEBHOOK_SECRET=your_webhook_secret_here

  # Server Configuration
  PORT=3000
  ```
</details>

<details>
  <summary><strong>React.js Setup Instructions</strong></summary>

  ### Basic React.js Integration

  After running `@billingsdk/cli init` and selecting **React.js**, the CLI generates a `lib/dodopayments.ts` and a `hooks/useBilling.ts` file for your project.

  You can use the `useBilling` hook directly in your components to interact with the backend API:

  ```tsx
  // src/App.tsx or any component
  import React, { useEffect } from 'react'
  import { useBilling } from './hooks/useBilling'

  function App() {
    const { fetchProducts, loading, error } = useBilling()

    useEffect(() => {
      const loadProducts = async () => {
        try {
          const products = await fetchProducts()
          console.log('Products:', products)
        } catch (err) {
          console.error('Failed to fetch products:', err)
        }
      }
      loadProducts()
    }, [fetchProducts])

    if (loading) return <p>Loading...</p>
    if (error) return <p style={{ color: 'red' }}>{error}</p>

    return <h1>Welcome to DodoPayments + React</h1>
  }

  export default App
  ```

  #### Environment Configuration

  Create a `.env` (or `.env.local` if using Vite) in your project root:

  ```bash
  # Backend API URL (Express.js server or Next.js API routes)
  VITE_BASE_URL=http://localhost:3000
  ```
</details>

<details>
  <summary><strong>Fastify Setup Instructions</strong></summary>

  ### Basic Fastify Integration

  After running `@billingsdk/cli init` and selecting Fastify, integrate the generated routes into your Fastify application.

  ```ts
  // src/index.ts
  import Fastify from 'fastify'
  import cors from '@fastify/cors'
  import helmet from '@fastify/helmet'
  import { dodopaymentsRoutes } from './routes/dodopayments/route'

  const app = Fastify({ logger: true })

  // Plugins (optional but recommended)
  await app.register(cors)
  await app.register(helmet)

  // Mount DodoPayments routes
  app.register(dodopaymentsRoutes, { prefix: '/api/dodopayments' })

  const start = async () => {
    try {
      const port = Number(process.env.PORT) || 3000
      await app.listen({ port, host: '0.0.0.0' })
      app.log.info(`Server running on port ${port}`)
    } catch (err) {
      app.log.error(err)
      process.exit(1)
    }
  }

  start()
  ```

  #### Environment Configuration

  Create a `.env` file in your project root:

  ```bash
  # DodoPayments Configuration
  DODO_PAYMENTS_API_KEY=your_api_key_here
  DODO_PAYMENTS_ENVIRONMENT=test_mode
  DODO_PAYMENTS_WEBHOOK_KEY=your_webhook_key_here

  # Server Configuration
  PORT=3000
  ```

  #### Scripts

  ```json
  {
    "scripts": {
      "dev": "tsx watch src/server.ts",
      "build": "tsc",
      "start": "node dist/server.js"
    }
  }
  ```
</details>

### Dependencies Installed (Dodo Payments)

<Tabs items={['Next.js', 'Express.js', 'React.js', 'Hono', 'NestJS', 'Fastify']}>
  <Tab value="Next.js">
    ```json
    {
      "dependencies": {
        "dodopayments": "latest",
        "standardwebhooks": "latest",
        "zod": "latest"
      }
    }
    ```
  </Tab>

  <Tab value="Express.js">
    ```json
    {
      "dependencies": {
        "dodopayments": "latest",
        "standardwebhooks": "latest",
        "zod": "latest",
        "express": "latest",
        "@types/express": "latest"
      }
    }
    ```
  </Tab>

  <Tab value="React.js">
    ```json
    {
      "dependencies": {
        "dodopayments": "latest"
      }
    }
    ```
  </Tab>

  <Tab value="Hono">
    ```json
    {
      "dependencies": {
        "dodopayments": "latest",
        "standardwebhooks": "latest",
        "zod": "latest",
        "hono": "latest",
        "@types/bun": "latest"
      }
    }
    ```
  </Tab>

  <Tab value="NestJS">
    ```json
    {
      "dependencies": {
        "dodopayments": "latest",
        "standardwebhooks": "latest",
        "zod": "latest",
        "@nestjs/common": "latest",
        "@nestjs/core": "latest"
      }
    }
    ```
  </Tab>

  <Tab value="Fastify">
    ```json
    {
      "dependencies": {
        "dodopayments": "latest",
        "standardwebhooks": "latest",
        "zod": "latest",
        "fastify": "latest",
        "fastify-raw-body": "latest"
      }
    }
    ```
  </Tab>
</Tabs>

### Dependencies Installed (Stripe)

<Tabs items={['Express.js', 'Hono', 'NestJS']}>
  <Tab value="Express.js">
    ```json
    {
      "dependencies": {
        "stripe": "latest",
        "standardwebhooks": "latest",
        "zod": "latest",
        "express": "latest",
        "@types/express": "latest"
      }
    }
    ```
  </Tab>

  <Tab value="Hono">
    ```json
    {
      "dependencies": {
        "stripe": "latest",
        "standardwebhooks": "latest",
        "zod": "latest",
        "hono": "latest",
        "@types/bun": "latest"
      }
    }
    ```
  </Tab>

  <Tab value="NestJS">
    ```json
    {
      "dependencies": {
        "stripe": "latest",
        "standardwebhooks": "latest",
        "zod": "latest",
        "@nestjs/common": "latest",
        "@nestjs/core": "latest"
      }
    }
    ```
  </Tab>
</Tabs>

### Generated Files (Stripe)

After running `init` with Stripe, you'll get:

<Tabs items={['Next.js + Stripe', 'React.js + Stripe', 'Express.js + Stripe', 'Hono + Stripe']}>
  <Tab value="Next.js + Stripe">
    ```
    your-project/
    ├── app/api/
    │   └── (stripe)/
    │       ├── checkout
    │       ├── customer
    │       ├── payments
    │       ├── products
    │       ├── subscriptions
    │       └── webhook
    ├── hooks/
    │   └── useBilling.ts
    ├── lib/
    │   └── stripe.ts
    .env.example
    ```
  </Tab>

  <Tab value="React.js + Stripe">
    ```
    your-project/
    ├── hooks/
    │   └── stripe/
    │       └── useBilling.ts
    ├── lib/
    │   └── stripe.ts
    .env.example
    ```
  </Tab>

  <Tab value="Express.js + Stripe">
    ```
    your-project/
    ├── lib/
    │   └── stripe.ts
    └── routes/
        └── stripe/
            ├── route.ts
            ├── checkout.ts
            ├── customer.ts
            ├── payments.ts
            ├── products.ts
            ├── subscriptions.ts
            └── webhook.ts
    .env.example
    ```
  </Tab>

  <Tab value="Hono + Stripe">
    ```
    your-project/
    ├── lib/
    │   └── stripe.ts
    └── routes/
        ├── route.ts
        └── stripe/
            ├── checkout.ts
            ├── customer.ts
            ├── payments.ts
            ├── products.ts
            ├── subscriptions.ts
            └── webhook.ts
    .env.example
    ```
  </Tab>
</Tabs>

### API Routes Included

The init command sets up comprehensive API routes for:

* **Checkout**: Payment processing and order creation
* **Customer Management**: Customer data and subscription handling
* **Product Management**: Product catalog and pricing
* **Webhook Handling**: Payment provider webhook integration

### Setup Instructions

<details>
  <summary><strong>Next.js Setup Instructions</strong></summary>

  ### Basic Next.js Integration

  After running `@billingsdk/cli init` and selecting Next.js, the CLI scaffolds API routes under `app/api/(dodopayments)/*` and adds `lib/dodopayments.ts` and `hooks/useBilling.ts`.

  * Routes are auto-registered by the App Router. No extra wiring is required.
  * Client components can call the API directly or use `hooks/useBilling.ts`.

  #### Environment Configuration

  Copy `.env.example` to `.env.local` in the project root and set:

  ```bash
  # DodoPayments
  DODO_PAYMENTS_API_KEY=your_api_key_here
  DODO_PAYMENTS_ENVIRONMENT=test_mode
  DODO_PAYMENTS_WEBHOOK_KEY=your_webhook_key_here

  # App URL
  NEXT_PUBLIC_APP_URL=http://localhost:3000
  ```

  #### Using the billing hook (optional)

  ```tsx
  // app/(or any client component)
  "use client"
  import { useEffect } from 'react'
  import { useBilling } from "@/app/hooks/useBilling"

  export default function BillingExample() {
    const { fetchProducts } = useBilling()

    useEffect(() => {
      fetchProducts().catch(console.error)
    }, [fetchProducts])

    return null
  }
  ```
</details>

<details>
  <summary><strong>Express.js Setup Instructions</strong></summary>

  ### Basic Express.js Integration

  After running `@billingsdk/cli init` and selecting Express.js, you'll need to integrate the generated routes into your Express application:

  ```javascript
  // app.js or server.js
  const express = require('express');
  const { dodopaymentsRouter } = require('./src/routes/dodopayments/route');

  const app = express();

  // Middleware
  app.use(express.json());

  // Mount DodoPayments routes
  app.use('/api/dodopayments', dodopaymentsRouter);

  // Start server
  const PORT = process.env.PORT || 3000;
  app.listen(PORT, () => {
    console.log(`Server running on port ${PORT}`);
  });
  ```

  #### Environment Configuration

  Create a `.env` file in your project root:

  ```bash
  # DodoPayments Configuration
  DODO_PAYMENTS_API_KEY=your_api_key_here
  DODO_PAYMENTS_ENVIRONMENT=test_mode
  DODO_PAYMENTS_WEBHOOK_KEY=your_webhook_key_here

  # Server Configuration
  PORT=3000
  NODE_ENV=development
  ```

  #### TypeScript Support

  The template includes full TypeScript support. To use with TypeScript:

  ```bash


  ```

  Create a `tsconfig.json`:

  ```json
  {
    "compilerOptions": {
      "target": "ES2020",
      "module": "commonjs",
      "lib": ["ES2020"],
      "outDir": "./dist",
      "rootDir": "./src",
      "strict": true,
      "esModuleInterop": true,
      "skipLibCheck": true,
      "forceConsistentCasingInFileNames": true,
      "resolveJsonModule": true
    },
    "include": ["src/**/*"],
    "exclude": ["node_modules", "dist"]
  }
  ```

  Update your `package.json` scripts:

  ```json
  {
    "scripts": {
      "dev": "nodemon --exec ts-node src/app.ts",
      "build": "tsc",
      "start": "node dist/app.js"
    }
  }
  ```
</details>

<details>
  <summary><strong>Hono Setup Instructions</strong></summary>

  ### Basic Hono Integration

  After running `@billingsdk/cli init` and selecting Hono, you'll need to integrate the generated routes into your Hono application:

  ```typescript
  // src/index.ts
  import { Hono } from 'hono'
  import { dodopaymentsRouter } from './routes/route'

  const app = new Hono()

  // Mount DodoPayments routes
  app.route('/api/dodopayments', dodopaymentsRouter)

  // Start server
  export default app
  ```

  #### Environment Configuration

  Create a `.env` file in your project root:

  ```bash
  # DodoPayments Configuration
  DODO_PAYMENTS_API_KEY=your_api_key_here
  DODO_PAYMENTS_ENVIRONMENT=test_mode
  DODO_PAYMENTS_WEBHOOK_KEY=your_webhook_key_here

  # Server Configuration
  PORT=3000
  ```

  #### Running with Bun

  Hono works great with Bun. To run your application:

  Add this to your `package.json` scripts:

  ```json
  {
    "scripts": {
      "dev": "bun run --hot src/routes/route.ts"
    }
  }
  ```
</details>

<details>
  <summary><strong>React.js Setup Instructions</strong></summary>

  ### Basic React.js Integration

  After running `@billingsdk/cli init` and selecting **React.js**, the CLI generates a `lib/dodopayments.ts` and a `hooks/useBilling.ts` file for your project.

  You can use the `useBilling` hook directly in your components to interact with the backend API:

  ```tsx
  // src/App.tsx or any component
  import React, { useEffect } from 'react'
  import { useBilling } from './hooks/useBilling'

  function App() {
    const { fetchProducts, loading, error } = useBilling()

    useEffect(() => {
      const loadProducts = async () => {
        try {
          const products = await fetchProducts()
          console.log('Products:', products)
        } catch (err) {
          console.error('Failed to fetch products:', err)
        }
      }
      loadProducts()
    }, [fetchProducts])

    if (loading) return <p>Loading...</p>
    if (error) return <p style={{ color: 'red' }}>{error}</p>

    return <h1>Welcome to DodoPayments + React</h1>
  }

  export default App
  ```

  #### Environment Configuration

  Create a `.env` (or `.env.local` if using Vite) in your project root:

  ```bash
  # Backend API URL (Express.js server or Next.js API routes)
  VITE_BASE_URL=http://localhost:3000
  ```
</details>

<details>
  <summary><strong>Fastify Setup Instructions</strong></summary>

  ### Basic Fastify Integration

  After running `@billingsdk/cli init` and selecting Fastify, integrate the generated routes into your Fastify application.

  ```ts
  // src/index.ts
  import Fastify from 'fastify'
  import cors from '@fastify/cors'
  import helmet from '@fastify/helmet'
  import { dodopaymentsRoutes } from './routes/dodopayments/route'

  const app = Fastify({ logger: true })

  // Plugins (optional but recommended)
  await app.register(cors)
  await app.register(helmet)

  // Mount DodoPayments routes
  app.register(dodopaymentsRoutes, { prefix: '/api/dodopayments' })

  const start = async () => {
    try {
      const port = Number(process.env.PORT) || 3000
      await app.listen({ port, host: '0.0.0.0' })
      app.log.info(`Server running on port ${port}`)
    } catch (err) {
      app.log.error(err)
      process.exit(1)
    }
  }

  start()
  ```

  #### Environment Configuration

  Create a `.env` file in your project root:

  ```bash
  # DodoPayments Configuration
  DODO_PAYMENTS_API_KEY=your_api_key_here
  DODO_PAYMENTS_ENVIRONMENT=test_mode
  DODO_PAYMENTS_WEBHOOK_KEY=your_webhook_key_here

  # Server Configuration
  PORT=3000
  ```

  #### Scripts

  ```json
  {
    "scripts": {
      "dev": "tsx watch src/server.ts",
      "build": "tsc",
      "start": "node dist/server.js"
    }
  }
  ```
</details>

### Dependencies Installed (Dodo Payments)

<Tabs items={['Next.js', 'Express.js', 'React.js', 'Hono', 'Fastify']}>
  <Tab value="Next.js">
    ```json
    {
      "dependencies": {
        "dodopayments": "latest",
        "standardwebhooks": "latest",
        "zod": "latest"
      }
    }
    ```
  </Tab>

  <Tab value="Express.js">
    ```json
    {
      "dependencies": {
        "dodopayments": "latest",
        "standardwebhooks": "latest",
        "zod": "latest",
        "express": "latest",
        "@types/express": "latest"
      }
    }
    ```
  </Tab>

  <Tab value="React.js">
    ```json
    {
      "dependencies": {
        "dodopayments": "latest"
      }
    }
    ```
  </Tab>

  <Tab value="Hono">
    ```json
    {
      "dependencies": {
        "dodopayments": "latest",
        "standardwebhooks": "latest",
        "zod": "latest",
        "hono": "latest",
        "@types/bun": "latest"
      }
    }
    ```
  </Tab>

  <Tab value="Fastify">
    ```json
    {
      "dependencies": {
        "dodopayments": "latest",
        "standardwebhooks": "latest",
        "zod": "latest",
        "fastify": "latest",
        "fastify-raw-body": "latest"
      }
    }
    ```
  </Tab>
</Tabs>

### Dependencies Installed (Stripe)

<Tabs items={['Express.js', 'Hono']}>
  <Tab value="Express.js">
    ```json
    {
      "dependencies": {
        "stripe": "latest",
        "standardwebhooks": "latest",
        "zod": "latest",
        "express": "latest",
        "@types/express": "latest"
      }
    }
    ```
  </Tab>

  <Tab value="Hono">
    ```json
    {
      "dependencies": {
        "stripe": "latest",
        "standardwebhooks": "latest",
        "zod": "latest",
        "hono": "latest",
        "@types/bun": "latest"
      }
    }
    ```
  </Tab>
</Tabs>

## `@billingsdk/cli add`

Add individual billing components to your existing project using the shadcn/ui registry system.

### Usage

```bash
npx @billingsdk/cli add <component-name>
```

### Available Components

See the [components](/docs/components) page for a list of available components.

### Examples

```bash
# Add a pricing table
npx @billingsdk/cli add pricing-table-one

# Add subscription management
npx @billingsdk/cli add subscription-management

# Add usage monitoring
npx @billingsdk/cli add usage-meter-circle
```

### What happens

1. Downloads the component configuration from the registry
2. Installs the component files in your `components/billingsdk/` directory
3. Updates your project configuration if needed
4. Installs any additional dependencies

<Callout title="Developer Tool">
  This command is primarily used by Billing SDK maintainers. Regular users typically don't need to run this command.
</Callout>

## Troubleshooting

### Common Issues

**Command not found**

```bash
# Make sure you're using npx
npx @billingsdk/cli --help
```

**Permission errors**

```bash
# On Unix systems, you might need to adjust permissions
chmod +x node_modules/.bin/@billingsdk/cli
```

**Network issues**

```bash
# Check your internet connection
# The CLI downloads templates from @billingsdk/cli.com
```

### Getting Help

```bash
# Show all available commands
npx @billingsdk/cli --help

# Get help for a specific command
npx @billingsdk/cli init --help
npx @billingsdk/cli add --help
```

## Development

### Building the CLI

```bash
cd packages/cli
npm run build
```

### Development Mode

```bash
cd packages/cli
npm run dev
```

### Contributing

The CLI is open source and welcomes contributions. See our [contribution guide](/docs/contribution-open-source) for details.

<Callout title="Need Help?">
  If you encounter issues or have questions about the CLI, please [open an issue](https://github.com/dodopayments/billingsdk/issues) on GitHub.
</Callout>


# Contribution & Open Source
URL: /docs/contribution-open-source

Help us improve Billing SDK - built with transparency and community collaboration

***

title: Contribution & Open Source
description: Help us improve Billing SDK - built with transparency and community collaboration
----------------------------------------------------------------------------------------------

import { Callout } from 'fumadocs-ui/components/callout'
import { Cards, Card } from 'fumadocs-ui/components/card'

Billing SDK is built on the principles of open source software - transparency, collaboration, and community-driven development. We believe that great tools should be accessible to everyone and improved by collective effort.

### Why Open Source?

* **🔍 Transparency** - Full visibility into how components work
* **🤝 Community** - Built by developers, for developers
* **🔒 Security** - Open code means better security through peer review
* **📈 Innovation** - Faster iteration through community contributions
* **💰 Cost-Effective** - Free to use, modify, and distribute

## How to Contribute

We welcome contributions from the community! Whether you're fixing bugs, adding new components, or improving documentation, your help makes Billing SDK better for everyone.

### Getting Started

1. **Fork the repository** on GitHub
2. **Clone your fork** locally
3. **Create a new branch** for your changes
4. **Make your changes** following our guidelines
5. **Test thoroughly** to ensure everything works
6. **Submit a pull request** with a clear description

Refer our [CONTRIBUTING.md](https://github.com/dodopayments/billingsdk/blob/main/CONTRIBUTING.md) for more details.

### Contribution Guidelines

<Callout title="Development Setup">
  Make sure you have Node.js 18+ installed and are familiar with React, TypeScript, and Tailwind CSS.
</Callout>

#### Adding New Components

When adding new components:

* Follow the existing component structure and naming conventions
* Include comprehensive TypeScript interfaces
* Add proper documentation with examples
* Ensure responsive design and accessibility
* Test with multiple themes

#### Code Style

* Use TypeScript for all components
* Follow the existing code formatting
* Use meaningful variable and function names
* Add JSDoc comments for complex functions
* Ensure components are accessible

#### Documentation

* Update README files as needed
* Add examples for new components
* Include prop tables and usage instructions
* Test all code examples

### Types of Contributions Welcome

* 🐛 **Bug Fixes** - Help us fix issues and improve stability
* ✨ **New Components** - Add new billing and subscription components
* 📚 **Documentation** - Improve guides, examples, and API docs
* 🎨 **Themes** - Create new visual themes and variants
* 🔧 **Developer Experience** - Improve tooling and development workflow
* 🧪 **Testing** - Add tests and improve coverage

## License & Usage

Billing SDK is released under the GNU General Public License (GPL), ensuring the project remains open and free:

* ✅ Use freely for any purpose
* ✅ Study and modify the source code
* ✅ Distribute copies to help others
* ✅ Distribute modified versions
* ⚠️ Must keep derivatives under GPL license
* ⚠️ Must provide source code when distributing

<Callout title="GPL License Benefits">
  The GPL license ensures that Billing SDK and all derivative works remain free and open source, protecting the commons and ensuring community benefits are preserved.
</Callout>

## Project Links

<Cards>
  <Card href="https://github.com/dodopayments/billingsdk" title="GitHub Repository" description="View source code, report issues, and contribute" />

  <Card href="https://github.com/dodopayments/billingsdk/issues" title="Issue Tracker" description="Report bugs and request features" />
</Cards>

## Community & Support

### Core Maintainers

The project is actively maintained by a team of developers at [DodoPayments](https://dodopayments.com) who are committed to keeping it up-to-date, secure, and feature-rich.

### Community Support

* **Issues & Bugs** - Community-driven issue resolution
* **Feature Requests** - Prioritized based on community needs
* **Documentation** - Collaborative improvement of guides and examples
* **Code Reviews** - Peer review for quality assurance

### Get Involved

* Join discussions in GitHub Issues
* Share your use cases and feedback
* Help answer questions from other users
* Suggest new features and improvements

<Callout title="Get Involved">
  Whether you're a seasoned developer or just getting started, there are many ways to contribute to the project and help make it better for everyone.
</Callout>

## Roadmap

Our development is guided by community feedback and industry needs:

* 🎯 **Short Term** - Bug fixes, performance improvements, new component variants
* 🚀 **Medium Term** - Advanced theming system, more component types, better accessibility
* 🌟 **Long Term** - Framework integrations, design system expansion, enterprise features

Join us in building the future of billing components!

## Learn More

New to here? Don't worry, we welcome your questions.

If you find anything confusing, please give your feedback on [GitHub Issues](https://github.com/dodopayments/billingsdk/issues)!

<Callout title="Questions?">
  If you find anything confusing or need help getting started, please open an issue on [GitHub Issues](https://github.com/dodopayments/billingsdk/issues)!
</Callout>


# Introduction
URL: /docs

Complete billing infrastructure for modern web applications with React components, CLI tooling, and full-stack integration

***

title: Introduction
description: Complete billing infrastructure for modern web applications with React components, CLI tooling, and full-stack integration
---------------------------------------------------------------------------------------------------------------------------------------

import { Cards, Card } from 'fumadocs-ui/components/card'
import { Callout } from 'fumadocs-ui/components/callout'

<div style={{ position: 'relative', paddingBottom: '56.25%', height: 0, overflow: 'hidden', borderRadius: 12 }}>
  <iframe src="https://www.youtube.com/embed/32RVbEllEi0" title="Billing SDK Overview" style={{ position: 'absolute', top: 0, left: 0, width: '100%', height: '100%', border: 0 }} allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerPolicy="strict-origin-when-cross-origin" allowFullScreen />
</div>

Billing SDK is a **complete billing infrastructure solution** that combines modern React components with powerful CLI tooling and full-stack integration, designed to help you ship billing features faster than ever.

Whether you're building a SaaS startup or adding billing to an existing application, Billing SDK provides everything you need: beautiful, production-ready UI components, automated project setup, and seamless payment provider integration.

<Callout title="Built on shadcn/ui">
  All components are built on top of shadcn/ui primitives for consistent design and seamless integration with your existing projects.
</Callout>

## What's Included

Billing SDK provides a complete billing ecosystem with multiple tools and components:

<Cards>
  <Card title="🎨 UI Components Library">
    Beautiful, production-ready billing components including pricing tables, subscription management, usage meters, and cancellation flows.
  </Card>

  <Card title="🛠️ CLI Tool">
    Powerful command-line interface for project initialization, component installation, and framework integration with payment providers.
  </Card>

  <Card title="⚡ Framework Templates">
    Pre-built templates for Next.js with complete API routes, webhooks, and payment provider integration for Dodo Payments.
  </Card>

  <Card title="🔧 Full-Stack Integration">
    Ready-to-use API endpoints for checkout, customer management, product catalog, and webhook handling.
  </Card>

  <Card title="📊 Component Registry">
    Centralized registry system for distributing and managing billing components across projects.
  </Card>

  <Card title="🎯 Developer Experience">
    TypeScript-first approach with comprehensive documentation, examples, and automated setup workflows.
  </Card>
</Cards>

## Component Categories

### Pricing & Conversion

* **Pricing Tables**: Multiple variants (1-column, 2-column, 3-column) with themes and responsive design
* **Banners**: Promotional and notification banners for marketing campaigns

### Subscription Management

* **Subscription Dashboard**: Complete interface for managing active subscriptions
* **Plan Updates**: Upgrade/downgrade flows with confirmation dialogs
* **Payment Methods**: Secure payment method selection and management
* **Invoice History**: Customer invoice display and download capabilities

### Usage & Analytics

* **Usage Meters**: Linear and circular progress indicators for quota tracking
* **Usage Tables**: Detailed usage statistics and consumption reports

### Customer Experience

* **Cancellation Flow**: User-friendly cancellation with retention features
* **Customer Portal**: Self-service account management interface

## Quick Start Options

Choose the approach that fits your project:

### 🚀 New Project (Recommended)

```bash
npx @billingsdk/cli init
```

Perfect for starting fresh with complete billing infrastructure, API routes, and payment integration.

### 🔧 Existing Project

```bash
npx @billingsdk/cli add pricing-table-one
```

Add individual components to your current setup using the CLI or shadcn/ui registry.

### 📚 Manual Installation

```bash
npx shadcn@latest add @billingsdk/component-name
```

Install components directly using shadcn/ui for maximum flexibility.

## Key Features

### Developer Experience

* 🛠️ **CLI Tool** - Interactive setup, component management, and project scaffolding
* ⚡ **One-Command Setup** - Initialize complete billing infrastructure instantly
* 📚 **Comprehensive Documentation** - Guides, examples, and API references
* 🛡️ **TypeScript First** - Full type safety and excellent IDE support

### Component Library

* 🎨 **Multiple Themes** - Classic, minimal, and custom theme variants
* 📱 **Responsive Design** - Mobile-first approach that works across all devices
* 🔧 **Highly Customizable** - CSS variables and theme customization
* 🎯 **Accessibility Ready** - WCAG compliant components with keyboard navigation

### Full-Stack Integration

* 🔌 **Payment Providers** - Ready-to-use Dodo Payments integration
* 🪝 **Webhook Handling** - Automated webhook processing and signature verification
* 📊 **API Routes** - Complete REST API for billing operations
* 🔄 **Real-time Updates** - Live subscription status and usage tracking

### Enterprise Ready

* 🏗️ **Production Tested** - Battle-tested components used in production
* 📈 **Scalable Architecture** - Built to handle high-traffic billing operations
* 🔒 **Security Focused** - Secure payment processing and data handling
* 🎛️ **Monitoring Ready** - Built-in logging and error tracking

## Core Concepts

### Plan Interface

The **[Plan Interface](/docs/interfaces)** is the core data structure that powers all billing components. It defines pricing plans with features, pricing tiers, billing information, and subscription details used consistently across the entire component library.

### Component Registry

Billing SDK uses a sophisticated **[Component Registry](/docs/cli#component-registry)** system that allows for:

* Centralized component distribution
* Version management and updates
* Automated dependency resolution
* Consistent theming across all components

### Framework Integration

Seamless integration with modern frameworks:

* ✅ **Next.js** (App Router) - Full support with API routes and server actions
* 🚧 **Express.js** - Backend API integration (coming soon)
* 🚧 **Additional Frameworks** - Based on community demand

## AI-Ready Documentation

Billing SDK provides an **[LLMs-full.txt](https://billingsdk.com/llms-full.txt)** file that helps AI models understand how to interact with these components. This enables better AI-assisted development and automated code generation.

## Prerequisites

While not strictly required, familiarity with these technologies will enhance your experience:

* **React** - Component composition and state management
* **TypeScript** - Type safety and better developer experience
* **Tailwind CSS** - Styling and theming customization
* **Next.js** - Full-stack application development

Ready to get started? Choose your path above or explore the **[CLI documentation](/docs/cli)** for detailed setup instructions.


# TypeScript Interfaces
URL: /docs/interfaces

Complete TypeScript definitions for all Billing SDK components and data structures

***

title: TypeScript Interfaces
description: Complete TypeScript definitions for all Billing SDK components and data structures
-----------------------------------------------------------------------------------------------

## Plan Interface

The `Plan` interface is used to define the structure of a pricing plan and is shared across all the `PricingTable` components.

```tsx
interface Plan {
    id: string
    title: string
    description: string
    highlight?: boolean
    type?: 'monthly' | 'yearly'
    currency?: string
    monthlyPrice: string
    yearlyPrice: string
    buttonText: string
    badge?: string
    features: {
        name: string
        icon: string
        iconColor?: string
    }[],
    benefits?: string[]
}
```

Whenever you add a new component which uses the `Plan` interface, a file `/lib/billingsdk-config.ts` will be created with the `plans` array.

## CurrentPlan Interface

The `CurrentPlan` interface is used to define the structure of a user's current subscription plan and billing information. It combines plan details with subscription-specific data.

```tsx
interface CurrentPlan {
    plan: Plan
    type: 'monthly' | 'yearly' | 'custom'
    price?: string
    nextBillingDate: string
    paymentMethod: string
    status: 'active' | 'inactive' | 'past_due' | 'cancelled'
}
```

### Properties

* **plan**: The complete `Plan` object containing plan details
* **type**: The billing cycle type (`monthly`, `yearly`, or `custom`)
* **price**: Optional current price (useful for custom pricing)
* **nextBillingDate**: The date when the next billing cycle starts
* **paymentMethod**: The payment method used for the subscription
* **status**: The current status of the subscription plan

A sample of the `/lib/billingsdk-config.ts` file is:

```ts
// lib/billingsdk-config.ts
export interface Plan {
    id: string
    title: string
    description: string
    highlight?: boolean
    type?: 'monthly' | 'yearly'
    currency?: string
    monthlyPrice: string
    yearlyPrice: string
    buttonText: string
    badge?: string
    features: {
        name: string
        icon: string
        iconColor?: string
    }[]
}

export interface CurrentPlan {
    plan: Plan
    type: 'monthly' | 'yearly' | 'custom'
    price?: string
    nextBillingDate: string
    paymentMethod: string
    status: 'active' | 'inactive' | 'past_due' | 'cancelled'
}

export const plans: Plan[] = [
    {
        id: 'starter',
        title: 'Starter',
        description: 'For developers testing out Liveblocks locally.',
        currency: '$',
        monthlyPrice: '0',
        yearlyPrice: '0',
        buttonText: 'Start today for free',
        features: [
            {
                name: 'Presence',
                icon: "check",
                iconColor: 'text-green-500'
            },
            {
                name: 'Comments',
                icon: "check",
                iconColor: 'text-orange-500'
            },
            {
                name: 'Notifications',
                icon: "check",
                iconColor: 'text-teal-500'
            },
            {
                name: 'Text Editor',
                icon: "check",
                iconColor: 'text-blue-500'
            },
            {
                name: 'Sync Datastore',
                icon: "check",
                iconColor: 'text-zinc-500'
            }
        ],
    },
    {
        id: 'pro',
        title: 'Pro',
        description: 'For companies adding collaboration in production.',
        currency: '$',
        monthlyPrice: '20',
        yearlyPrice: '199',
        buttonText: 'Sign up',
        badge: 'Most popular',
        highlight: true,
        features: [
            {
                name: 'Presence',
                icon: "check",
                iconColor: 'text-green-500'
            },
            {
                name: 'Comments',
                icon: "check",
                iconColor: 'text-orange-500'
            },
            {
                name: 'Notifications',
                icon: "check",
                iconColor: 'text-teal-500'
            },
            {
                name: 'Text Editor',
                icon: "check",
                iconColor: 'text-blue-500'
            },
            {
                name: 'Sync Datastore',
                icon: "check",
                iconColor: 'text-zinc-500'
            }
        ],
    },
    {
        id: 'enterprise',
        title: 'Enterprise',
        description: 'For organizations that need more support and compliance features.',
        currency: '$',
        monthlyPrice: 'Custom',
        yearlyPrice: 'Custom',
        buttonText: 'Contact sales',
        features: [
            {
                name: 'Presence',
                icon: "check",
                iconColor: 'text-green-500'
            },
            {
                name: 'Comments',
                icon: "check",
                iconColor: 'text-orange-500'
            },
            {
                name: 'Notifications',
                icon: "check",
                iconColor: 'text-teal-500'
            },
            {
                name: 'Text Editor',
                icon: "check",
                iconColor: 'text-blue-500'
            },
            {
                name: 'Sync Datastore',
                icon: "check",
                iconColor: 'text-zinc-500'
            }
        ],
    }
];
```


# Quick Start
URL: /docs/quick-start

Get up and running with Billing SDK in minutes

***

title: Quick Start
description: Get up and running with Billing SDK in minutes
-----------------------------------------------------------

import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
import { Callout } from 'fumadocs-ui/components/callout'

## Add Components to Your Project

A React or Next.js project with Tailwind CSS is required. Install any component with a single command:

<Tabs items={['shadcn', 'billingSDK']} defaultValue="shadcn" className="bg-transparent border-none">
  <Tab value="shadcn" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="installation-tabs">
      <Tab value="npx">
        ```bash
        npx shadcn@latest add @billingsdk/pricing-table-one
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @billingsdk/pricing-table-one
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @billingsdk/pricing-table-one
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx shadcn@latest add @billingsdk/pricing-table-one
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab value="billingSDK" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="billingsdk-cli-tabs">
      <Tab value="npx">
        ```bash
        npx @billingsdk/cli add pricing-table-one
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx @billingsdk/cli add pricing-table-one
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx @billingsdk/cli add pricing-table-one
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx @billingsdk/cli add pricing-table-one
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

This will automatically install the component and its dependencies into your project.

<Callout title="From Existing Project?">
  All components are designed to integrate seamlessly with existing Next.js and React applications.
</Callout>

## Quick Project Setup with CLI

For new projects or comprehensive billing integration, use our CLI tool for complete project setup with framework configuration and payment provider integration.

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']}>
  <Tab value="npm">
    ```bash
    npx @billingsdk/cli init
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm dlx @billingsdk/cli init
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn dlx @billingsdk/cli init
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bunx @billingsdk/cli init
    ```
  </Tab>
</Tabs>

The CLI provides an interactive setup that will:

* Configure your framework (Next.js with App Router)
* Set up payment provider integration (Dodo Payments, adding more providers soon)
* Generate API routes for checkout, customer management, and webhooks
* Install all necessary dependencies
* Create configuration files and boilerplate code

<Callout title="What gets installed">
  The CLI automatically installs: `provider's-api`, `standardwebhooks`, `zod`, and other essential dependencies.
</Callout>

Refer to the [CLI](/docs/cli) page for more information.

### Add Individual Components

For existing projects, you can also add specific components using the CLI:

```bash
# Add a pricing table
npx @billingsdk/cli add pricing-table-one

# Add subscription management
npx @billingsdk/cli add subscription-management

# Add usage monitoring
npx @billingsdk/cli add usage-meter-circle
```

## Your First Component

Create your first billing component setup.

```tsx title="lib/billingsdk-config.ts"
// no need to manually add this file. already added whenever you install a component.
export const plans = [{
  id: 'starter',
  title: 'Starter',
  description: 'Perfect for getting started',
  monthlyPrice: '$0',
  yearlyPrice: '$0',
  buttonText: 'Get Started',
  features: [
    { name: 'Basic features', icon: 'check' }
  ]
}]
```

Use the component in your application and see it in action.

<Tabs items={['npm', 'pnpm', 'yarn', 'bun']}>
  <Tab value="npm">
    ```bash
    npm run dev
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm run dev
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn dev
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun run dev
    ```
  </Tab>
</Tabs>

## Quick Examples

### Install a Pricing Table

```bash
npx shadcn@latest add @billingsdk/pricing-table-one
```

### Use in Your App

```tsx
import { PricingTableOne } from "@/components/billingsdk/pricing-table-one";
import { plans } from "@/lib/billingsdk-config";

export default function PricingPage() {
  return (
    <PricingTableOne 
      plans={plans}
      title="Choose Your Plan"
      description="Select the perfect plan for your needs"
      onPlanSelect={(planId) => console.log('Selected plan:', planId)}
    />
  );
}
```


# ShadCN CLI 3.0 Integration Guide
URL: /docs/shadcn-cli-3

Comprehensive guide to integrating Billing SDK components using ShadCN CLI 3.0 with MCP support

***

title: ShadCN CLI 3.0 Integration Guide
description: Comprehensive guide to integrating Billing SDK components using ShadCN CLI 3.0 with MCP support
keywords: shadcn, cli, billing-sdk, components, mcp, registry
-------------------------------------------------------------

## Project Initialization

Initialize your project with ShadCN CLI to set up the necessary dependencies and configuration.

<Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="shadcn-cli-3-tabs">
  <Tab value="npx">
    ```bash
    npx shadcn@latest init
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm dlx shadcn@latest init
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn dlx shadcn@latest init
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bunx shadcn@latest init
    ```
  </Tab>
</Tabs>

The `init` command automatically:

* Installs required dependencies
* Adds utility functions to your project
* Configures `tailwind.config.js` with proper settings
* Sets up default component styles and theming

## Adding Components

You can add Billing SDK components to your project using either the standard ShadCN CLI or the dedicated Billing SDK CLI. Choose the method that best fits your workflow.

### Using ShadCN CLI

Add components using the trusted namespace:

<Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="installation-tabs">
  <Tab value="npx">
    ```bash
    npx shadcn@latest add @billingsdk/[component]
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm dlx shadcn@latest add @billingsdk/[component]
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn dlx shadcn@latest add @billingsdk/[component]
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bunx shadcn@latest add @billingsdk/[component]
    ```
  </Tab>
</Tabs>

### Using Billing SDK CLI

For a more streamlined experience, use the dedicated Billing SDK CLI:

<Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="billingsdk-cli-tabs">
  <Tab value="npx">
    ```bash
    npx @billingsdk/cli add [component]
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm dlx @billingsdk/cli add [component]
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn dlx @billingsdk/cli add [component]
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bunx @billingsdk/cli add [component]
    ```
  </Tab>
</Tabs>

> **Note**: Replace `[component]` with the actual component name you want to add, such as `pricing-table-one` or `payment-method-manager`.

## Component Discovery

Explore and discover available Billing SDK components using the built-in discovery commands. These tools help you find the right components for your specific use cases.

{/* ### View Registry

  Get a detailed overview of all available components in the Billing SDK registry:

  <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="shadcn-cli-3-discover-components-tabs">
    <Tab value="npx">
    ```bash
    npx shadcn@latest view @billingsdk
    ```
    </Tab>
    <Tab value="pnpm">
    ```bash
    pnpm dlx shadcn@latest view @billingsdk
    ```
    </Tab>
    <Tab value="yarn">
    ```bash
    yarn dlx shadcn@latest view @billingsdk
    ```
    </Tab>
    <Tab value="bun">
    ```bash
    bunx shadcn@latest view @billingsdk
    ```
    </Tab>
  </Tabs> */}

### List Components

Get a concise list of all available component names:

<Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="shadcn-cli-3-discover-components-list-tabs">
  <Tab value="npx">
    ```bash
    npx shadcn@latest list @billingsdk
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm dlx shadcn@latest list @billingsdk
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn dlx shadcn@latest list @billingsdk
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bunx shadcn@latest list @billingsdk
    ```
  </Tab>
</Tabs>

### Search Components

Search for specific components using keywords or phrases:

<Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="shadcn-cli-3-discover-components-search-tabs">
  <Tab value="npx">
    ```bash
    npx shadcn@latest search @billingsdk -q "banner"
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm dlx shadcn@latest search @billingsdk -q "banner"
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn dlx shadcn@latest search @billingsdk -q "banner"
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bunx shadcn@latest search @billingsdk -q "banner"
    ```
  </Tab>
</Tabs>

### Search Examples

```bash
# Search for pricing-related components
npx shadcn@latest search @billingsdk -q "pricing"

# Find payment method components
npx shadcn@latest search @billingsdk -q "payment"

# Look for subscription management components
npx shadcn@latest search @billingsdk -q "subscription"
```

## MCP (Model Context Protocol) Support

ShadCN CLI 3.0 introduces MCP support, enabling seamless integration with AI assistants for component management. This feature allows your AI coding assistant to directly interact with the component registry and add components to your project through natural language commands.

### Setup Process

#### 1. Configure Registry

First, ensure the Billing SDK registry is configured in your `components.json`:

```json title="components.json"
{
  "registries": {
    "@billingsdk": "https://billingsdk.com/r/{name}.json"
  }
}
```

#### 2. Initialize MCP Server

Initialize the MCP server in your project:

<Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="shadcn-cli-3-mcp-server-tabs">
  <Tab value="npx">
    ```bash
    npx shadcn@latest mcp init
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm dlx shadcn@latest mcp init
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn dlx shadcn@latest mcp init
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bunx shadcn@latest mcp init
    ```
  </Tab>
</Tabs>

### AI-Assisted Component Addition

Once MCP is set up, you can use natural language commands with your AI assistant. Simply describe the component you need:

**Example prompts:**

```bash
Add a pricing table to my project from billingSDK registry
```

```bash
I need a payment method manager component from billingSDK registry
```

```bash
Add a subscription management interface from billingSDK registry
```

```bash
Include a usage meter component for my billing dashboard from billingSDK registry
```

### Benefits of MCP Integration

* **Natural Language Commands**: No need to remember specific component names or commands
* **Context-Aware Suggestions**: AI can suggest appropriate components based on your project needs
* **Streamlined Workflow**: Reduce time spent searching and adding components
* **Error Prevention**: AI assistance helps avoid command syntax errors

### Supported AI Assistants

MCP support works with AI coding assistants that support the Model Context Protocol, including:

* GitHub Copilot
* Cursor AI
* Other MCP-compatible tools

> **Note**: Ensure your AI assistant supports MCP before attempting to use these features. The MCP server must be running for the integration to work properly.

***

## Next Steps

* Explore available [Billing SDK components](../components/index.mdx)
* Learn about [component customization](../theming.mdx)
* Check out [API integration guides](../interfaces.mdx)

For additional support, visit our [GitHub repository](https://github.com/billingsdk) or [Discord community](https://discord.gg/billingsdk).


# Theming
URL: /docs/theming

Customize your components by modifying CSS variables in global.css

***

title: Theming
description: Customize your components by modifying CSS variables in global.css
-------------------------------------------------------------------------------

## How to Change Themes

To change the theme of your components, simply modify the CSS variables in your `global.css` file. The current theme uses these variables:

```css title="src/app/global.css"
:root {
  --radius: 0.625rem;
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --card: oklch(1 0 0);
  --card-foreground: oklch(0.145 0 0);
  --popover: oklch(1 0 0);
  --popover-foreground: oklch(0.145 0 0);
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);
  --secondary: oklch(0.97 0 0);
  --secondary-foreground: oklch(0.205 0 0);
  --muted: oklch(0.97 0 0);
  --muted-foreground: oklch(0.556 0 0);
  --accent: oklch(0.97 0 0);
  --accent-foreground: oklch(0.205 0 0);
  --destructive: oklch(0.577 0.245 27.325);
  --border: oklch(0.922 0 0);
  --input: oklch(0.922 0 0);
  --ring: oklch(0.708 0 0);
}

.dark {
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);
  --card: oklch(0.205 0 0);
  --card-foreground: oklch(0.985 0 0);
  --popover: oklch(0.205 0 0);
  --popover-foreground: oklch(0.985 0 0);
  --primary: oklch(0.922 0 0);
  --primary-foreground: oklch(0.205 0 0);
  --secondary: oklch(0.269 0 0);
  --secondary-foreground: oklch(0.985 0 0);
  --muted: oklch(0.269 0 0);
  --muted-foreground: oklch(0.708 0 0);
  --accent: oklch(0.269 0 0);
  --accent-foreground: oklch(0.985 0 0);
  --destructive: oklch(0.704 0.191 22.216);
  --border: oklch(1 0 0 / 10%);
  --input: oklch(1 0 0 / 15%);
  --ring: oklch(0.556 0 0);
}
```

## Available Themes

### Blue Theme

```css title="src/app/global.css"
:root {
  --radius: 0.625rem;
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --card: oklch(1 0 0);
  --card-foreground: oklch(0.145 0 0);
  --popover: oklch(1 0 0);
  --popover-foreground: oklch(0.145 0 0);
  --primary: oklch(0.6 0.25 253);
  --primary-foreground: oklch(0.985 0 0);
  --secondary: oklch(0.97 0.01 253);
  --secondary-foreground: oklch(0.205 0 0);
  --muted: oklch(0.97 0.01 253);
  --muted-foreground: oklch(0.556 0.01 253);
  --accent: oklch(0.94 0.05 253);
  --accent-foreground: oklch(0.205 0 0);
  --destructive: oklch(0.577 0.245 27.325);
  --border: oklch(0.922 0.01 253);
  --input: oklch(0.922 0.01 253);
  --ring: oklch(0.6 0.25 253);
}

.dark {
  --background: oklch(0.145 0.01 253);
  --foreground: oklch(0.985 0 0);
  --card: oklch(0.205 0.01 253);
  --card-foreground: oklch(0.985 0 0);
  --popover: oklch(0.205 0.01 253);
  --popover-foreground: oklch(0.985 0 0);
  --primary: oklch(0.7 0.2 253);
  --primary-foreground: oklch(0.145 0.01 253);
  --secondary: oklch(0.269 0.01 253);
  --secondary-foreground: oklch(0.985 0 0);
  --muted: oklch(0.269 0.01 253);
  --muted-foreground: oklch(0.708 0.01 253);
  --accent: oklch(0.35 0.05 253);
  --accent-foreground: oklch(0.985 0 0);
  --destructive: oklch(0.704 0.191 22.216);
  --border: oklch(1 0 0 / 10%);
  --input: oklch(1 0 0 / 15%);
  --ring: oklch(0.7 0.2 253);
}
```

### Green Theme

```css title="src/app/global.css"
:root {
  --radius: 0.625rem;
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --card: oklch(1 0 0);
  --card-foreground: oklch(0.145 0 0);
  --popover: oklch(1 0 0);
  --popover-foreground: oklch(0.145 0 0);
  --primary: oklch(0.5 0.2 142);
  --primary-foreground: oklch(0.985 0 0);
  --secondary: oklch(0.97 0.01 142);
  --secondary-foreground: oklch(0.205 0 0);
  --muted: oklch(0.97 0.01 142);
  --muted-foreground: oklch(0.556 0.01 142);
  --accent: oklch(0.94 0.05 142);
  --accent-foreground: oklch(0.205 0 0);
  --destructive: oklch(0.577 0.245 27.325);
  --border: oklch(0.922 0.01 142);
  --input: oklch(0.922 0.01 142);
  --ring: oklch(0.5 0.2 142);
}

.dark {
  --background: oklch(0.145 0.01 142);
  --foreground: oklch(0.985 0 0);
  --card: oklch(0.205 0.01 142);
  --card-foreground: oklch(0.985 0 0);
  --popover: oklch(0.205 0.01 142);
  --popover-foreground: oklch(0.985 0 0);
  --primary: oklch(0.65 0.15 142);
  --primary-foreground: oklch(0.145 0.01 142);
  --secondary: oklch(0.269 0.01 142);
  --secondary-foreground: oklch(0.985 0 0);
  --muted: oklch(0.269 0.01 142);
  --muted-foreground: oklch(0.708 0.01 142);
  --accent: oklch(0.35 0.05 142);
  --accent-foreground: oklch(0.985 0 0);
  --destructive: oklch(0.704 0.191 22.216);
  --border: oklch(1 0 0 / 10%);
  --input: oklch(1 0 0 / 15%);
  --ring: oklch(0.65 0.15 142);
}
```

### Orange Theme

```css title="src/app/global.css"
:root {
  --radius: 0.625rem;
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --card: oklch(1 0 0);
  --card-foreground: oklch(0.145 0 0);
  --popover: oklch(1 0 0);
  --popover-foreground: oklch(0.145 0 0);
  --primary: oklch(0.6 0.2 42);
  --primary-foreground: oklch(0.985 0 0);
  --secondary: oklch(0.97 0.01 42);
  --secondary-foreground: oklch(0.205 0 0);
  --muted: oklch(0.97 0.01 42);
  --muted-foreground: oklch(0.556 0.01 42);
  --accent: oklch(0.94 0.05 42);
  --accent-foreground: oklch(0.205 0 0);
  --destructive: oklch(0.577 0.245 27.325);
  --border: oklch(0.922 0.01 42);
  --input: oklch(0.922 0.01 42);
  --ring: oklch(0.6 0.2 42);
}

.dark {
  --background: oklch(0.145 0.01 42);
  --foreground: oklch(0.985 0 0);
  --card: oklch(0.205 0.01 42);
  --card-foreground: oklch(0.985 0 0);
  --popover: oklch(0.205 0.01 42);
  --popover-foreground: oklch(0.985 0 0);
  --primary: oklch(0.7 0.15 42);
  --primary-foreground: oklch(0.145 0.01 42);
  --secondary: oklch(0.269 0.01 42);
  --secondary-foreground: oklch(0.985 0 0);
  --muted: oklch(0.269 0.01 42);
  --muted-foreground: oklch(0.708 0.01 42);
  --accent: oklch(0.35 0.05 42);
  --accent-foreground: oklch(0.985 0 0);
  --destructive: oklch(0.704 0.191 22.216);
  --border: oklch(1 0 0 / 10%);
  --input: oklch(1 0 0 / 15%);
  --ring: oklch(0.7 0.15 42);
}
```

### Red Theme

```css title="src/app/global.css"
:root {
  --radius: 0.625rem;
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --card: oklch(1 0 0);
  --card-foreground: oklch(0.145 0 0);
  --popover: oklch(1 0 0);
  --popover-foreground: oklch(0.145 0 0);
  --primary: oklch(0.55 0.25 12);
  --primary-foreground: oklch(0.985 0 0);
  --secondary: oklch(0.97 0.01 12);
  --secondary-foreground: oklch(0.205 0 0);
  --muted: oklch(0.97 0.01 12);
  --muted-foreground: oklch(0.556 0.01 12);
  --accent: oklch(0.94 0.05 12);
  --accent-foreground: oklch(0.205 0 0);
  --destructive: oklch(0.577 0.245 27.325);
  --border: oklch(0.922 0.01 12);
  --input: oklch(0.922 0.01 12);
  --ring: oklch(0.55 0.25 12);
}

.dark {
  --background: oklch(0.145 0.01 12);
  --foreground: oklch(0.985 0 0);
  --card: oklch(0.205 0.01 12);
  --card-foreground: oklch(0.985 0 0);
  --popover: oklch(0.205 0.01 12);
  --popover-foreground: oklch(0.985 0 0);
  --primary: oklch(0.7 0.2 12);
  --primary-foreground: oklch(0.145 0.01 12);
  --secondary: oklch(0.269 0.01 12);
  --secondary-foreground: oklch(0.985 0 0);
  --muted: oklch(0.269 0.01 12);
  --muted-foreground: oklch(0.708 0.01 12);
  --accent: oklch(0.35 0.05 12);
  --accent-foreground: oklch(0.985 0 0);
  --destructive: oklch(0.704 0.191 22.216);
  --border: oklch(1 0 0 / 10%);
  --input: oklch(1 0 0 / 15%);
  --ring: oklch(0.7 0.2 12);
}
```

### Cyberpunk Theme

**Fonts**: Orbitron (futuristic sci-fi style) + JetBrains Mono\
**Style**: Dark neon colors with sharp edges and minimal radius

```css title="src/app/global.css"
/* Import fonts */
@import url('https://fonts.googleapis.com/css2?family=Orbitron:wght@400;500;600;700;800;900&family=JetBrains+Mono:ital,wght@0,100;0,200;0,300;0,400;0,500;0,600;0,700;0,800;1,100;1,200;1,300;1,400;1,500;1,600;1,700;1,800&display=swap');

/* Apply fonts */
body {
  font-family: 'Orbitron', monospace;
}

code, pre {
  font-family: 'JetBrains Mono', monospace;
}

:root {
  --radius: 0.125rem;
  --background: oklch(0.05 0.02 270);
  --foreground: oklch(0.9 0.15 320);
  --card: oklch(0.08 0.03 270);
  --card-foreground: oklch(0.85 0.12 320);
  --popover: oklch(0.08 0.03 270);
  --popover-foreground: oklch(0.85 0.12 320);
  --primary: oklch(0.7 0.3 320);
  --primary-foreground: oklch(0.05 0.02 270);
  --secondary: oklch(0.15 0.05 270);
  --secondary-foreground: oklch(0.8 0.15 180);
  --muted: oklch(0.12 0.04 270);
  --muted-foreground: oklch(0.6 0.08 270);
  --accent: oklch(0.6 0.25 180);
  --accent-foreground: oklch(0.05 0.02 270);
  --destructive: oklch(0.65 0.3 15);
  --border: oklch(0.2 0.06 270);
  --input: oklch(0.15 0.05 270);
  --ring: oklch(0.7 0.3 320);
}

.dark {
  --background: oklch(0.02 0.01 270);
  --foreground: oklch(0.95 0.2 320);
  --card: oklch(0.05 0.02 270);
  --card-foreground: oklch(0.9 0.15 320);
  --popover: oklch(0.05 0.02 270);
  --popover-foreground: oklch(0.9 0.15 320);
  --primary: oklch(0.8 0.35 320);
  --primary-foreground: oklch(0.02 0.01 270);
  --secondary: oklch(0.1 0.03 270);
  --secondary-foreground: oklch(0.85 0.2 180);
  --muted: oklch(0.08 0.02 270);
  --muted-foreground: oklch(0.65 0.1 270);
  --accent: oklch(0.7 0.3 180);
  --accent-foreground: oklch(0.02 0.01 270);
  --destructive: oklch(0.7 0.35 15);
  --border: oklch(0.15 0.04 270);
  --input: oklch(0.1 0.03 270);
  --ring: oklch(0.8 0.35 320);
}
```

### Elegant Theme

**Fonts**: Playfair Display (sophisticated serif) + Crimson Text + JetBrains Mono\
**Style**: Warm refined tones with elegant typography and rounded corners

```css title="src/app/global.css"
/* Import fonts */
@import url('https://fonts.googleapis.com/css2?family=Playfair+Display:ital,wght@0,400;0,500;0,600;0,700;0,800;0,900;1,400;1,500;1,600;1,700;1,800;1,900&family=Crimson+Text:ital,wght@0,400;0,600;1,400;1,600&family=JetBrains+Mono:ital,wght@0,100;0,200;0,300;0,400;0,500;0,600;0,700;0,800;1,100;1,200;1,300;1,400;1,500;1,600;1,700;1,800&display=swap');

/* Apply fonts */
body {
  font-family: 'Playfair Display', serif;
}

h1, h2, h3, h4, h5, h6 {
  font-family: 'Playfair Display', serif;
}

p, span {
  font-family: 'Crimson Text', serif;
}

code, pre {
  font-family: 'JetBrains Mono', monospace;
}

:root {
  --radius: 0.75rem;
  --background: oklch(0.98 0.005 60);
  --foreground: oklch(0.15 0.02 30);
  --card: oklch(0.99 0.003 60);
  --card-foreground: oklch(0.15 0.02 30);
  --popover: oklch(0.99 0.003 60);
  --popover-foreground: oklch(0.15 0.02 30);
  --primary: oklch(0.3 0.08 30);
  --primary-foreground: oklch(0.98 0.005 60);
  --secondary: oklch(0.92 0.01 60);
  --secondary-foreground: oklch(0.25 0.05 30);
  --muted: oklch(0.94 0.008 60);
  --muted-foreground: oklch(0.45 0.03 30);
  --accent: oklch(0.88 0.02 45);
  --accent-foreground: oklch(0.2 0.04 30);
  --destructive: oklch(0.5 0.15 15);
  --border: oklch(0.88 0.015 60);
  --input: oklch(0.9 0.012 60);
  --ring: oklch(0.35 0.1 30);
}

.dark {
  --background: oklch(0.08 0.01 30);
  --foreground: oklch(0.95 0.008 60);
  --card: oklch(0.12 0.015 30);
  --card-foreground: oklch(0.92 0.006 60);
  --popover: oklch(0.12 0.015 30);
  --popover-foreground: oklch(0.92 0.006 60);
  --primary: oklch(0.85 0.02 60);
  --primary-foreground: oklch(0.1 0.012 30);
  --secondary: oklch(0.18 0.02 30);
  --secondary-foreground: oklch(0.88 0.008 60);
  --muted: oklch(0.15 0.018 30);
  --muted-foreground: oklch(0.65 0.005 60);
  --accent: oklch(0.25 0.03 45);
  --accent-foreground: oklch(0.9 0.006 60);
  --destructive: oklch(0.65 0.18 15);
  --border: oklch(0.2 0.025 30);
  --input: oklch(0.16 0.02 30);
  --ring: oklch(0.8 0.015 60);
}
```

### Retro Theme

**Fonts**: Fredoka (playful rounded) + Space Grotesk + JetBrains Mono\
**Style**: Warm vintage colors with fun typography and large rounded corners

```css title="src/app/global.css"
/* Import fonts */
@import url('https://fonts.googleapis.com/css2?family=Fredoka:wght@300;400;500;600;700&family=Space+Grotesk:wght@300;400;500;600;700&family=JetBrains+Mono:ital,wght@0,100;0,200;0,300;0,400;0,500;0,600;0,700;0,800;1,100;1,200;1,300;1,400;1,500;1,600;1,700;1,800&display=swap');

/* Apply fonts */
body {
  font-family: 'Fredoka', cursive;
}

h1, h2, h3, h4, h5, h6 {
  font-family: 'Fredoka', cursive;
}

p, span {
  font-family: 'Space Grotesk', sans-serif;
}

code, pre {
  font-family: 'JetBrains Mono', monospace;
}

:root {
  --radius: 1rem;
  --background: oklch(0.96 0.02 50);
  --foreground: oklch(0.2 0.05 20);
  --card: oklch(0.98 0.015 50);
  --card-foreground: oklch(0.2 0.05 20);
  --popover: oklch(0.98 0.015 50);
  --popover-foreground: oklch(0.2 0.05 20);
  --primary: oklch(0.6 0.2 25);
  --primary-foreground: oklch(0.98 0.015 50);
  --secondary: oklch(0.85 0.08 40);
  --secondary-foreground: oklch(0.25 0.06 20);
  --muted: oklch(0.9 0.04 45);
  --muted-foreground: oklch(0.5 0.04 25);
  --accent: oklch(0.75 0.15 60);
  --accent-foreground: oklch(0.2 0.05 20);
  --destructive: oklch(0.55 0.18 15);
  --border: oklch(0.82 0.06 45);
  --input: oklch(0.85 0.05 45);
  --ring: oklch(0.6 0.2 25);
}

.dark {
  --background: oklch(0.12 0.03 20);
  --foreground: oklch(0.92 0.02 50);
  --card: oklch(0.16 0.04 20);
  --card-foreground: oklch(0.9 0.02 50);
  --popover: oklch(0.16 0.04 20);
  --popover-foreground: oklch(0.9 0.02 50);
  --primary: oklch(0.7 0.22 25);
  --primary-foreground: oklch(0.12 0.03 20);
  --secondary: oklch(0.22 0.05 20);
  --secondary-foreground: oklch(0.85 0.06 40);
  --muted: oklch(0.18 0.04 20);
  --muted-foreground: oklch(0.65 0.03 40);
  --accent: oklch(0.35 0.1 60);
  --accent-foreground: oklch(0.9 0.02 50);
  --destructive: oklch(0.65 0.2 15);
  --border: oklch(0.25 0.05 20);
  --input: oklch(0.2 0.04 20);
  --ring: oklch(0.7 0.22 25);
}
```

### Minimal Theme

**Fonts**: System fonts (native OS fonts for ultimate performance)\
**Style**: Pure black and white with no rounded corners - brutalist design

```css title="src/app/global.css"
/* No font imports needed - uses system fonts */

/* Apply fonts */
body {
  font-family: system-ui, -apple-system, sans-serif;
}

code, pre {
  font-family: ui-monospace, monospace;
}

:root {
  --radius: 0rem;
  --background: oklch(1 0 0);
  --foreground: oklch(0 0 0);
  --card: oklch(0.99 0 0);
  --card-foreground: oklch(0 0 0);
  --popover: oklch(1 0 0);
  --popover-foreground: oklch(0 0 0);
  --primary: oklch(0 0 0);
  --primary-foreground: oklch(1 0 0);
  --secondary: oklch(0.95 0 0);
  --secondary-foreground: oklch(0 0 0);
  --muted: oklch(0.96 0 0);
  --muted-foreground: oklch(0.4 0 0);
  --accent: oklch(0.92 0 0);
  --accent-foreground: oklch(0 0 0);
  --destructive: oklch(0 0 0);
  --border: oklch(0.9 0 0);
  --input: oklch(0.95 0 0);
  --ring: oklch(0 0 0);
}

.dark {
  --background: oklch(0 0 0);
  --foreground: oklch(1 0 0);
  --card: oklch(0.03 0 0);
  --card-foreground: oklch(1 0 0);
  --popover: oklch(0 0 0);
  --popover-foreground: oklch(1 0 0);
  --primary: oklch(1 0 0);
  --primary-foreground: oklch(0 0 0);
  --secondary: oklch(0.1 0 0);
  --secondary-foreground: oklch(1 0 0);
  --muted: oklch(0.08 0 0);
  --muted-foreground: oklch(0.7 0 0);
  --accent: oklch(0.15 0 0);
  --accent-foreground: oklch(1 0 0);
  --destructive: oklch(0.8 0 0);
  --border: oklch(0.2 0 0);
  --input: oklch(0.1 0 0);
  --ring: oklch(1 0 0);
}
```

### Neon Theme

**Fonts**: Space Grotesk (modern geometric) + JetBrains Mono\
**Style**: Vibrant neon colors with electric purple/cyan accents

```css title="src/app/global.css"
/* Import fonts */
@import url('https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@300;400;500;600;700&family=JetBrains+Mono:ital,wght@0,100;0,200;0,300;0,400;0,500;0,600;0,700;0,800;1,100;1,200;1,300;1,400;1,500;1,600;1,700;1,800&display=swap');

/* Apply fonts */
body {
  font-family: 'Space Grotesk', sans-serif;
}

code, pre {
  font-family: 'JetBrains Mono', monospace;
}

:root {
  --radius: 0.5rem;
  --background: oklch(0.08 0.01 270);
  --foreground: oklch(0.95 0.15 300);
  --card: oklch(0.12 0.02 270);
  --card-foreground: oklch(0.9 0.12 300);
  --popover: oklch(0.12 0.02 270);
  --popover-foreground: oklch(0.9 0.12 300);
  --primary: oklch(0.75 0.35 300);
  --primary-foreground: oklch(0.08 0.01 270);
  --secondary: oklch(0.18 0.03 180);
  --secondary-foreground: oklch(0.85 0.2 180);
  --muted: oklch(0.15 0.02 270);
  --muted-foreground: oklch(0.65 0.08 300);
  --accent: oklch(0.7 0.3 180);
  --accent-foreground: oklch(0.08 0.01 270);
  --destructive: oklch(0.7 0.35 15);
  --border: oklch(0.25 0.05 270);
  --input: oklch(0.2 0.03 270);
  --ring: oklch(0.75 0.35 300);
}

.dark {
  --background: oklch(0.04 0.005 270);
  --foreground: oklch(0.98 0.2 300);
  --card: oklch(0.08 0.01 270);
  --card-foreground: oklch(0.95 0.15 300);
  --popover: oklch(0.08 0.01 270);
  --popover-foreground: oklch(0.95 0.15 300);
  --primary: oklch(0.8 0.4 300);
  --primary-foreground: oklch(0.04 0.005 270);
  --secondary: oklch(0.12 0.02 180);
  --secondary-foreground: oklch(0.9 0.25 180);
  --muted: oklch(0.1 0.01 270);
  --muted-foreground: oklch(0.7 0.1 300);
  --accent: oklch(0.75 0.35 180);
  --accent-foreground: oklch(0.04 0.005 270);
  --destructive: oklch(0.75 0.4 15);
  --border: oklch(0.2 0.03 270);
  --input: oklch(0.15 0.02 270);
  --ring: oklch(0.8 0.4 300);
}
```

### Sunset Theme

**Fonts**: Inter + Fira Code (clean and professional)\
**Style**: Warm orange/red gradients like a sunset

```css title="src/app/global.css"
/* Import fonts */
@import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700;800&family=Fira+Code:wght@300;400;500;600;700&display=swap');

/* Apply fonts */
body {
  font-family: 'Inter', sans-serif;
}

code, pre {
  font-family: 'Fira Code', monospace;
}

:root {
  --radius: 0.75rem;
  --background: oklch(0.97 0.02 35);
  --foreground: oklch(0.2 0.05 15);
  --card: oklch(0.99 0.01 35);
  --card-foreground: oklch(0.2 0.05 15);
  --popover: oklch(0.99 0.01 35);
  --popover-foreground: oklch(0.2 0.05 15);
  --primary: oklch(0.65 0.25 25);
  --primary-foreground: oklch(0.99 0.01 35);
  --secondary: oklch(0.85 0.08 45);
  --secondary-foreground: oklch(0.25 0.06 15);
  --muted: oklch(0.92 0.03 40);
  --muted-foreground: oklch(0.5 0.04 20);
  --accent: oklch(0.7 0.2 50);
  --accent-foreground: oklch(0.2 0.05 15);
  --destructive: oklch(0.6 0.2 15);
  --border: oklch(0.88 0.05 40);
  --input: oklch(0.9 0.04 40);
  --ring: oklch(0.65 0.25 25);
}

.dark {
  --background: oklch(0.15 0.03 15);
  --foreground: oklch(0.92 0.02 35);
  --card: oklch(0.18 0.04 15);
  --card-foreground: oklch(0.9 0.02 35);
  --popover: oklch(0.18 0.04 15);
  --popover-foreground: oklch(0.9 0.02 35);
  --primary: oklch(0.75 0.3 25);
  --primary-foreground: oklch(0.15 0.03 15);
  --secondary: oklch(0.25 0.05 15);
  --secondary-foreground: oklch(0.8 0.06 45);
  --muted: oklch(0.2 0.04 15);
  --muted-foreground: oklch(0.65 0.03 35);
  --accent: oklch(0.4 0.15 50);
  --accent-foreground: oklch(0.9 0.02 35);
  --destructive: oklch(0.7 0.25 15);
  --border: oklch(0.3 0.06 15);
  --input: oklch(0.22 0.04 15);
  --ring: oklch(0.75 0.3 25);
}
```

### Ocean Theme

**Fonts**: Poppins + Source Code Pro (friendly and readable)\
**Style**: Deep blue tones with aquatic feel

```css title="src/app/global.css"
/* Import fonts */
@import url('https://fonts.googleapis.com/css2?family=Poppins:wght@300;400;500;600;700;800&family=Source+Code+Pro:wght@300;400;500;600;700&display=swap');

/* Apply fonts */
body {
  font-family: 'Poppins', sans-serif;
}

code, pre {
  font-family: 'Source Code Pro', monospace;
}

:root {
  --radius: 0.5rem;
  --background: oklch(0.98 0.01 220);
  --foreground: oklch(0.18 0.02 200);
  --card: oklch(0.99 0.005 220);
  --card-foreground: oklch(0.18 0.02 200);
  --popover: oklch(0.99 0.005 220);
  --popover-foreground: oklch(0.18 0.02 200);
  --primary: oklch(0.55 0.2 210);
  --primary-foreground: oklch(0.99 0.005 220);
  --secondary: oklch(0.92 0.02 220);
  --secondary-foreground: oklch(0.25 0.03 200);
  --muted: oklch(0.94 0.015 220);
  --muted-foreground: oklch(0.45 0.02 200);
  --accent: oklch(0.85 0.05 190);
  --accent-foreground: oklch(0.2 0.02 200);
  --destructive: oklch(0.55 0.18 15);
  --border: oklch(0.88 0.02 220);
  --input: oklch(0.9 0.015 220);
  --ring: oklch(0.55 0.2 210);
}

.dark {
  --background: oklch(0.1 0.02 200);
  --foreground: oklch(0.95 0.01 220);
  --card: oklch(0.14 0.025 200);
  --card-foreground: oklch(0.92 0.01 220);
  --popover: oklch(0.14 0.025 200);
  --popover-foreground: oklch(0.92 0.01 220);
  --primary: oklch(0.7 0.25 210);
  --primary-foreground: oklch(0.1 0.02 200);
  --secondary: oklch(0.2 0.03 200);
  --secondary-foreground: oklch(0.85 0.02 220);
  --muted: oklch(0.16 0.025 200);
  --muted-foreground: oklch(0.65 0.01 220);
  --accent: oklch(0.3 0.08 190);
  --accent-foreground: oklch(0.9 0.01 220);
  --destructive: oklch(0.65 0.2 15);
  --border: oklch(0.25 0.04 200);
  --input: oklch(0.18 0.03 200);
  --ring: oklch(0.7 0.25 210);
}
```

### Forest Theme

**Fonts**: Merriweather (classic serif) + Roboto Mono\
**Style**: Natural green tones with earthy feel

```css title="src/app/global.css"
/* Import fonts */
@import url('https://fonts.googleapis.com/css2?family=Merriweather:wght@300;400;700;900&family=Roboto+Mono:wght@300;400;500;600;700&display=swap');

/* Apply fonts */
body {
  font-family: 'Merriweather', serif;
}

code, pre {
  font-family: 'Roboto Mono', monospace;
}

:root {
  --radius: 0.625rem;
  --background: oklch(0.97 0.01 120);
  --foreground: oklch(0.2 0.03 90);
  --card: oklch(0.98 0.008 120);
  --card-foreground: oklch(0.2 0.03 90);
  --popover: oklch(0.98 0.008 120);
  --popover-foreground: oklch(0.2 0.03 90);
  --primary: oklch(0.4 0.15 130);
  --primary-foreground: oklch(0.98 0.008 120);
  --secondary: oklch(0.9 0.02 110);
  --secondary-foreground: oklch(0.25 0.04 90);
  --muted: oklch(0.93 0.015 120);
  --muted-foreground: oklch(0.5 0.02 100);
  --accent: oklch(0.82 0.06 140);
  --accent-foreground: oklch(0.2 0.03 90);
  --destructive: oklch(0.55 0.18 15);
  --border: oklch(0.85 0.03 120);
  --input: oklch(0.88 0.025 120);
  --ring: oklch(0.4 0.15 130);
}

.dark {
  --background: oklch(0.12 0.02 90);
  --foreground: oklch(0.92 0.01 120);
  --card: oklch(0.16 0.025 90);
  --card-foreground: oklch(0.9 0.01 120);
  --popover: oklch(0.16 0.025 90);
  --popover-foreground: oklch(0.9 0.01 120);
  --primary: oklch(0.65 0.2 130);
  --primary-foreground: oklch(0.12 0.02 90);
  --secondary: oklch(0.22 0.03 90);
  --secondary-foreground: oklch(0.85 0.02 110);
  --muted: oklch(0.18 0.025 90);
  --muted-foreground: oklch(0.65 0.01 120);
  --accent: oklch(0.35 0.1 140);
  --accent-foreground: oklch(0.9 0.01 120);
  --destructive: oklch(0.65 0.2 15);
  --border: oklch(0.28 0.04 90);
  --input: oklch(0.2 0.03 90);
  --ring: oklch(0.65 0.2 130);
}
```

### Lavender Theme

**Fonts**: Nunito (soft and rounded) + Cascadia Code\
**Style**: Soft purple/pink with gentle gradients

```css title="src/app/global.css"
/* Import fonts */
@import url('https://fonts.googleapis.com/css2?family=Nunito:wght@300;400;500;600;700;800&display=swap');

/* Apply fonts */
body {
  font-family: 'Nunito', sans-serif;
}

code, pre {
  font-family: 'Cascadia Code', monospace;
}

:root {
  --radius: 0.875rem;
  --background: oklch(0.98 0.01 280);
  --foreground: oklch(0.2 0.02 260);
  --card: oklch(0.99 0.008 280);
  --card-foreground: oklch(0.2 0.02 260);
  --popover: oklch(0.99 0.008 280);
  --popover-foreground: oklch(0.2 0.02 260);
  --primary: oklch(0.6 0.18 280);
  --primary-foreground: oklch(0.99 0.008 280);
  --secondary: oklch(0.92 0.02 290);
  --secondary-foreground: oklch(0.25 0.03 260);
  --muted: oklch(0.94 0.015 280);
  --muted-foreground: oklch(0.5 0.02 270);
  --accent: oklch(0.85 0.05 300);
  --accent-foreground: oklch(0.2 0.02 260);
  --destructive: oklch(0.55 0.18 15);
  --border: oklch(0.88 0.02 280);
  --input: oklch(0.9 0.015 280);
  --ring: oklch(0.6 0.18 280);
}

.dark {
  --background: oklch(0.1 0.015 260);
  --foreground: oklch(0.95 0.01 280);
  --card: oklch(0.14 0.02 260);
  --card-foreground: oklch(0.92 0.01 280);
  --popover: oklch(0.14 0.02 260);
  --popover-foreground: oklch(0.92 0.01 280);
  --primary: oklch(0.75 0.22 280);
  --primary-foreground: oklch(0.1 0.015 260);
  --secondary: oklch(0.2 0.025 260);
  --secondary-foreground: oklch(0.85 0.02 290);
  --muted: oklch(0.16 0.02 260);
  --muted-foreground: oklch(0.65 0.01 280);
  --accent: oklch(0.3 0.08 300);
  --accent-foreground: oklch(0.9 0.01 280);
  --destructive: oklch(0.65 0.2 15);
  --border: oklch(0.25 0.03 260);
  --input: oklch(0.18 0.025 260);
  --ring: oklch(0.75 0.22 280);
}
```

### Midnight Theme

**Fonts**: IBM Plex Sans/Mono (technical and clean)\
**Style**: Deep navy with subtle blue accents

```css title="src/app/global.css"
/* Import fonts */
@import url('https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@300;400;500;600;700&family=IBM+Plex+Mono:wght@300;400;500;600;700&display=swap');

/* Apply fonts */
body {
  font-family: 'IBM Plex Sans', sans-serif;
}

code, pre {
  font-family: 'IBM Plex Mono', monospace;
}

:root {
  --radius: 0.375rem;
  --background: oklch(0.95 0.005 240);
  --foreground: oklch(0.15 0.01 220);
  --card: oklch(0.97 0.003 240);
  --card-foreground: oklch(0.15 0.01 220);
  --popover: oklch(0.97 0.003 240);
  --popover-foreground: oklch(0.15 0.01 220);
  --primary: oklch(0.25 0.05 240);
  --primary-foreground: oklch(0.97 0.003 240);
  --secondary: oklch(0.88 0.01 240);
  --secondary-foreground: oklch(0.2 0.015 220);
  --muted: oklch(0.9 0.008 240);
  --muted-foreground: oklch(0.45 0.008 230);
  --accent: oklch(0.82 0.02 250);
  --accent-foreground: oklch(0.15 0.01 220);
  --destructive: oklch(0.5 0.15 15);
  --border: oklch(0.85 0.01 240);
  --input: oklch(0.87 0.008 240);
  --ring: oklch(0.25 0.05 240);
}

.dark {
  --background: oklch(0.08 0.008 220);
  --foreground: oklch(0.95 0.005 240);
  --card: oklch(0.12 0.01 220);
  --card-foreground: oklch(0.92 0.005 240);
  --popover: oklch(0.12 0.01 220);
  --popover-foreground: oklch(0.92 0.005 240);
  --primary: oklch(0.8 0.08 240);
  --primary-foreground: oklch(0.08 0.008 220);
  --secondary: oklch(0.18 0.015 220);
  --secondary-foreground: oklch(0.85 0.01 240);
  --muted: oklch(0.15 0.012 220);
  --muted-foreground: oklch(0.65 0.005 240);
  --accent: oklch(0.25 0.03 250);
  --accent-foreground: oklch(0.9 0.005 240);
  --destructive: oklch(0.65 0.18 15);
  --border: oklch(0.22 0.02 220);
  --input: oklch(0.16 0.012 220);
  --ring: oklch(0.8 0.08 240);
}
```

## Common Issues & Troubleshooting Section

### 1. CSS Import Order Error

**Error:** `@import rules must precede all rules aside from @charset and @layer statements`

**Problem:** Font imports placed after other CSS rules.

**Solution:** Always place ALL `@import` statements at the very beginning of your CSS file:

```css
/* ✅ CORRECT - All imports at the top */
@import 'tailwindcss';
@import 'fumadocs-ui/css/vitepress.css';
@import 'fumadocs-ui/css/preset.css';
@import "tw-animate-css";
@import url('https://fonts.googleapis.com/css2?family=...');

/* Then your other CSS rules */
@custom-variant dark (&:is(.dark *));
@theme inline { /* ... */ }
```

```css
/* ❌ WRONG - Import after other rules */
@theme inline { /* ... */ }
@import url('https://fonts.googleapis.com/css2?family=...'); /* This will fail */
```

### 2. Unknown Utility Class Errors

**Error:** `Cannot apply unknown utility class 'border-border'`

**Problem:** Using custom utilities without proper Tailwind configuration.

**Solutions:**

**Option A: Remove problematic utilities (Quick Fix)**

```css
@layer base {
  * {
    @apply outline-ring/50; /* Remove border-border */
  }
  body {
    @apply bg-background text-foreground;
  }
}
```

**Option B: Configure Tailwind for custom utilities**
Add to your `tailwind.config.js`:

```js
module.exports = {
  theme: {
    extend: {
      colors: {
        border: "hsl(var(--border))",
        ring: "hsl(var(--ring))",
        background: "hsl(var(--background))",
        foreground: "hsl(var(--foreground))",
        // Add other custom colors as needed
      }
    }
  }
}
```

## Additional Resources

* [ShadCN Theming](https://ui.shadcn.com/docs/theming)
* [CSS @import MDN Documentation](https://developer.mozilla.org/en-US/docs/Web/CSS/@import)
* [Tailwind CSS Custom Colors](https://tailwindcss.com/docs/customizing-colors)


# Components
URL: /docs/components

Comprehensive collection of billing and subscription management components with production-ready features.

***

title: Components
description: Comprehensive collection of billing and subscription management components with production-ready features.
-----------------------------------------------------------------------------------------------------------------------

### Pricing Components

Professional pricing table components designed for conversion optimization and clear feature presentation.

| Component                                                                     | Description                                                                                              |
| ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| **[Pricing Table One](/docs/components/pricing-table/pricing-table-one)**     | Essential pricing table with classic and minimal theme variants                                          |
| **[Pricing Table Two](/docs/components/pricing-table/pricing-table-two)**     | Advanced pricing table with enhanced layouts and feature comparison                                      |
| **[Pricing Table Three](/docs/components/pricing-table/pricing-table-three)** | Enterprise-grade pricing table with custom styling and advanced features                                 |
| **[Pricing Table Four](/docs/components/pricing-table/pricing-table-four)**   | Modern gradient pricing table with contemporary design and smooth animations                             |
| **[Pricing Table Five](/docs/components/pricing-table/pricing-table-five)**   | Modern pricing table with contact us plan                                                                |
| **[Pricing Table Six](/docs/components/pricing-table/pricing-table-six)**     | Contemporary pricing table featuring gradient styling, smooth animations, and an enterprise-focused plan |
| **[Pricing Table Seven](/docs/components/pricing-table/pricing-table-seven)** | Feature-comparison pricing table with aligned cards and user slider for comprehensive plan comparison    |

### Subscription Management

Comprehensive subscription management interfaces for billing dashboards and user account management.

| Component                                                                 | Description                                                                               |
| ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| **[Manage Subscription](/docs/components/manage-subscription)**           | Complete subscription dashboard with billing history and account details                  |
| **[Invoice History](/docs/components/invoice-history)**                   | Read-only table showing past invoices and receipts                                        |
| **[Usage Table](/docs/components/usage-table)**                           | Per-model LLM usage with token counts, cache reads, and API cost                          |
| **[Update Plan Card](/docs/components/update-plan/update-plan-card)**     | Inline plan upgrade interface with feature comparison and pricing                         |
| **[Update Plan Dialog](/docs/components/update-plan/update-plan-dialog)** | Modal dialog for seamless plan changes with confirmation flow                             |
| **[Limited Offer Dialog](/docs/components/limited-offer-dialog)**         | Time-sensitive promotional offers with customizable content and call-to-action buttons    |
| **[Proration Preview](/docs/components/proration-preview)**               | Interactive billing adjustment preview for subscription plan changes with cost breakdowns |

### Payment Processing

Comprehensive payment method selection and processing interfaces for secure checkout experiences.

| Component                                                               | Description                                                                                                                               |
| ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **[Payment Details](/docs/components/payment-details)**                 | Complete payment details form with card details, billing information, country selection, and validation                                   |
| **[Payment Details Two](/docs/components/payment-details-two)**         | Complete payment details form with card details, billing information, country selection, built with React Hook Form and custom validation |
| **[Payment Success Dialog](/docs/components/payment-success-dialog)**   | Success confirmation modal with confetti animation and next steps                                                                         |
| **[Payment Method Selector](/docs/components/payment-method-selector)** | Interactive payment method selector supporting cards, digital wallets, UPI, and BNPL services                                             |
| **[Payment Card](/docs/components/payment-card)**                       | A comprehensive final payment interface for processing transactions with card details, billing information, and visual card preview       |

### Cancellation Management

Thoughtfully designed cancellation flows with retention strategies and user feedback collection.

| Component                                                                                         | Description                                                                   |
| ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| **[Cancel Subscription Dialog](/docs/components/cancel-subscription/cancel-subscription-dialog)** | Comprehensive cancellation flow with feedback collection and retention offers |
| **[Cancel Subscription Card](/docs/components/cancel-subscription/cancel-subscription-card)**     | Compact cancellation interface for quick subscription termination             |

### Billing & Usage Analytics

Visual usage meters and analytics components for displaying quotas, limits, and consumption data.

| Component                                                                 | Description                                                                                                         |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| **[Billing Screen](/docs/components/billing-screen)**                     | Complete billing dashboard with credit balance, plan details, and interactive credit card visual                    |
| **[Usage Meter Linear](/docs/components/usage-meter/usage-meter-linear)** | Horizontal progress bar for displaying usage percentages and limits                                                 |
| **[Usage Meter Circle](/docs/components/usage-meter/usage-meter-circle)** | Circular progress indicator for API limits and storage consumption                                                  |
| **[Detailed Usage Table](/docs/components/detailed-usage-table)**         | Detailed usage table for showing API calls, tokens, and storage consumption                                         |
| **[Billing Setting](/docs/components/billing-setting)**                   | Billing Setting component with Tabbed navigation for billing preferences, payment method, invoices and usage limits |
| **[Billing Settings 2](/docs/components/billing-settings-2)**             | Inline billing preferences form with currency, tax ID, and email toggles                                            |
| **[Upcoming Charges](/docs/components/upcoming-charges)**                 | Preview of upcoming billing cycle charges with itemized breakdown                                                   |

### Marketing & Promotion

Engagement components for announcements, promotions, and user onboarding experiences.

| Component                                 | Description                                                          |
| ----------------------------------------- | -------------------------------------------------------------------- |
| **[Top Banner](/docs/components/banner)** | Promotional banner with multiple variants for announcements and CTAs |

## Technical Specifications

### Core Features

* **Full TypeScript Support** - Complete type safety with IntelliSense
* **Theme Integration** - Automatic light/dark mode with CSS variables
* **Responsive Design** - Mobile-first approach with breakpoint optimization
* **Accessibility Compliance** - WCAG 2.1 AA standards with screen reader support
* **Customizable Styling** - CSS variables and prop-based theming system
* **Comprehensive Documentation** - Usage examples, API reference, and best practices

### Integration & Compatibility

* **React 18+** with hooks support
* **Next.js 13+** App Router compatibility
* **shadcn/ui** design system integration
* **Tailwind CSS** utility-first styling
* **npm/pnpm/yarn** package manager support

## Resources

* **[Quick Start Guide](/docs/quick-start)** - Installation and initial setup
* **[API Reference](/docs/interfaces)** - TypeScript interfaces and data structures
* **[Theming Guide](/docs/theming)** - Customization and brand integration
* **[Contributing Guide](/docs/contribution-open-source)** - Development and contribution guidelines


# Top Banner
URL: /docs/components/banner

The Top Banner component displays a banner at the top of the page.

***

title: Top Banner
description: The Top Banner component displays a banner at the top of the page.
-------------------------------------------------------------------------------

You can change the variant of the banner to `default`, `minimal`, `popup`, `destructive`, `warning`, `success`, `info`, or `announcement`.

## Default Banner

<Tabs items={['Preview', 'Code']} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="banner">
      <BannerDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/banner-demo.tsx"
    import { Banner } from "@/components/billingsdk/banner";

    export default function FreeTrialBannerDemo() {
      return (
        <div className="bg-background-secondary flex h-full min-h-[500px] w-full flex-col gap-6 overflow-hidden rounded-lg border-2">
          <Banner
            title="🎉 Start your free trial today!"
            description="Get 30 days free access to all premium features"
            buttonText="Start Free Trial"
            buttonLink="https://example.com/signup"
            variant="default" // default, minimal, popup
          />

          {/* minimal hero example */}
          <section className="flex flex-col items-center justify-center gap-4 py-16 text-center">
            <h1 className="text-foreground-secondary text-3xl font-bold tracking-tight">
              Create next-generation digital products
            </h1>
            <div className="flex flex-col gap-2">
              <p className="text-muted-foreground max-w-md">
                Build faster with our platform
              </p>
              <a className="hover:text-primary underline underline-offset-4 transition">
                Get Started →
              </a>
            </div>
          </section>
        </div>
      );
    }

    ```
  </Tab>
</Tabs>

## Installation

<Tabs items={['shadcn', 'billingSDK']} defaultValue="shadcn" className="bg-transparent border-none">
  <Tab value="shadcn" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="installation-tabs">
      <Tab value="npx">
        ```bash
        npx shadcn@latest add @billingsdk/banner
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @billingsdk/banner
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @billingsdk/banner
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx shadcn@latest add @billingsdk/banner
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab value="billingSDK" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="billingsdk-cli-tabs">
      <Tab value="npx">
        ```bash
        npx @billingsdk/cli add banner
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx @billingsdk/cli add banner
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx @billingsdk/cli add banner
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx @billingsdk/cli add banner
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## Minimal Banner

<Tabs items={['Preview', 'Code']} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="banner">
      <BannerDemoTwo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/banner-demo-two.tsx"
    import { Banner } from "@/components/billingsdk/banner";

    export default function FreeTrialBannerDemo() {
      return (
        <div className="bg-background-secondary flex h-full min-h-[500px] w-full flex-col gap-6 overflow-hidden rounded-lg border border-2">
          <Banner
            title="🎉 Explore your next destination today!"
            description="Discover the best places to visit in the world"
            variant="minimal" // default, minimal, popup
          />

          {/* minimal hero example */}
          <section className="flex flex-col items-center justify-center gap-4 py-16 text-center">
            <h1 className="text-foreground-secondary text-3xl font-bold tracking-tight">
              Discover the best places to visit in the world
            </h1>
            <div className="flex flex-col gap-2">
              <p className="text-muted-foreground max-w-md">
                Explore the best places to visit in the world
              </p>
              <a className="hover:text-primary underline underline-offset-4 transition">
                Get Started →
              </a>
            </div>
          </section>
        </div>
      );
    }

    ```
  </Tab>
</Tabs>

## Popup Banner

<Tabs items={['Preview', 'Code']} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="banner">
      <BannerDemoThree />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/banner-demo-three.tsx"
    "use client";

    import { Banner } from "@/components/billingsdk/banner";
    import { useState } from "react";
    import { Button } from "./ui/button";

    export default function FreeTrialBannerDemoThree() {
      const [showBanner, setShowBanner] = useState(false);
      return (
        <div className="flex h-full min-h-[500px] w-full flex-col items-center justify-center gap-4 rounded-lg border">
          {showBanner && (
            <Banner
              title="🎉 Start your free trial today!"
              description="Get 30 days free access to all premium features"
              variant="popup" // default, minimal, popup
            />
          )}
          <div className="flex h-full w-full flex-row items-center justify-center gap-4">
            <Button onClick={() => setShowBanner(true)}>Show Banner</Button>
          </div>
        </div>
      );
    }

    ```
  </Tab>
</Tabs>

## Gradient Banner

The banner component supports animated gradient backgrounds with custom colors. The gradient automatically adapts to both light and dark themes.

<Tabs items={['Preview', 'Code']} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="banner">
      <BannerGradientDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/banner-gradient-demo.tsx"
    "use client";

    import { Banner } from "@/components/billingsdk/banner";
    import { useState } from "react";
    import { Button } from "./ui/button";
    export const gradientColors = [
      "rgba(0,149,255,0.56)",
      "rgba(231,77,255,0.77)",
      "rgba(255,0,0,0.73)",
      "rgba(131,255,166,0.66)",
    ];
    export default function BannerGradientDemo() {
      const [showBanner, setShowBanner] = useState(false);

      return (
        <div className="w-full space-y-8">
          {/* Default Variant */}
          <div className="space-y-4">
            <h3 className="text-lg font-medium">Default Banner</h3>
            <Banner
              title="🌈 Experience the magic of gradients!"
              description="Beautiful animated gradient background with custom colors"
              buttonText="Start Free Trial"
              buttonLink="https://example.com/signup"
              variant="default"
              gradientColors={gradientColors}
              className="w-full"
            />
          </div>

          {/* Minimal Variant */}
          <div className="space-y-4">
            <h3 className="text-lg font-medium">Minimal Banner</h3>
            <Banner
              title="🎉 Start your free trial today!"
              description="Get 30 days free access"
              variant="minimal"
              gradientColors={gradientColors}
            />
          </div>

          {/* Interactive Popup Demo */}
          <div className="space-y-4">
            <h3 className="text-lg font-medium">Popup Banner</h3>
            <div className="flex justify-center">
              <Button variant="outline" onClick={() => setShowBanner(true)}>
                Show Gradient Banner
              </Button>
            </div>
            {showBanner && (
              <Banner
                title="🎉 Start your free trial today!"
                description="Get 30 days free access to all premium features"
                variant="popup"
                gradientColors={gradientColors}
              />
            )}
          </div>
        </div>
      );
    }

    ```
  </Tab>
</Tabs>

## Destructive Banner

<Tabs items={['Preview', 'Code']} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="banner">
      <BannerDestructiveDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/banner-destructive-demo.tsx"
    import { Banner } from "@/components/billingsdk/banner";

    export default function FreeTrialBannerDemo() {
      return (
        <div className="bg-background-secondary flex h-full min-h-[500px] w-full flex-col gap-6 overflow-hidden rounded-lg border-2">
          <Banner
            title="⚠️ Payment Failed - Subscription Suspended"
            description="Your subscription will be canceled in 3 days if payment is not updated"
            buttonText="Update Payment"
            buttonLink="https://example.com/billing"
            variant="destructive"
          />

          {/* minimal hero example */}
          <section className="flex flex-col items-center justify-center gap-4 py-16 text-center">
            <h1 className="text-foreground-secondary text-3xl font-bold tracking-tight">
              Create next-generation digital products
            </h1>
            <div className="flex flex-col gap-2">
              <p className="text-muted-foreground max-w-md">
                Build faster with our platform
              </p>
              <a className="hover:text-primary underline underline-offset-4 transition">
                Get Started →
              </a>
            </div>
          </section>
        </div>
      );
    }

    ```
  </Tab>
</Tabs>

## Warning Banner

<Tabs items={['Preview', 'Code']} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="banner">
      <BannerWarningDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/banner-warning-demo.tsx"
    import { Banner } from "@/components/billingsdk/banner";

    export default function BannerWarningDemo() {
      return (
        <div className="bg-background-secondary flex h-full min-h-[500px] w-full flex-col gap-6 overflow-hidden rounded-lg border-2">
          <Banner
            title="⚠️ System Maintenance Scheduled"
            description="Our services will be temporarily unavailable on Sunday, 2AM-4AM UTC for scheduled maintenance"
            buttonText="Learn More"
            buttonLink="https://example.com/maintenance"
            variant="warning"
          />

          {/* minimal hero example */}
          <section className="flex flex-col items-center justify-center gap-4 py-16 text-center">
            <h1 className="text-foreground-secondary text-3xl font-bold tracking-tight">
              System Status Dashboard
            </h1>
            <div className="flex flex-col gap-2">
              <p className="text-muted-foreground max-w-md">
                Monitor system health and maintenance schedules
              </p>
              <a className="hover:text-primary underline underline-offset-4 transition">
                View Status →
              </a>
            </div>
          </section>
        </div>
      );
    }

    ```
  </Tab>
</Tabs>

## Success Banner

<Tabs items={['Preview', 'Code']} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="banner">
      <BannerSuccessDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/banner-success-demo.tsx"
    import { Banner } from "@/components/billingsdk/banner";

    export default function BannerSuccessDemo() {
      return (
        <div className="bg-background-secondary flex h-full min-h-[500px] w-full flex-col gap-6 overflow-hidden rounded-lg border-2">
          <Banner
            title="✅ Payment Processed Successfully"
            description="Your subscription has been activated and you now have access to all premium features"
            buttonText="View Dashboard"
            buttonLink="https://example.com/dashboard"
            variant="success"
          />

          {/* minimal hero example */}
          <section className="flex flex-col items-center justify-center gap-4 py-16 text-center">
            <h1 className="text-foreground-secondary text-3xl font-bold tracking-tight">
              Welcome to Premium
            </h1>
            <div className="flex flex-col gap-2">
              <p className="text-muted-foreground max-w-md">
                Enjoy unlimited access to all features
              </p>
              <a className="hover:text-primary underline underline-offset-4 transition">
                Explore Features →
              </a>
            </div>
          </section>
        </div>
      );
    }

    ```
  </Tab>
</Tabs>

## Info Banner

<Tabs items={['Preview', 'Code']} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="banner">
      <BannerInfoDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/banner-info-demo.tsx"
    import { Banner } from "@/components/billingsdk/banner";

    export default function BannerInfoDemo() {
      return (
        <div className="bg-background-secondary flex h-full min-h-[500px] w-full flex-col gap-6 overflow-hidden rounded-lg border-2">
          <Banner
            title="ℹ️ New API Version Available"
            description="API v2.1 is now available with improved performance and new endpoints"
            buttonText="View Docs"
            buttonLink="https://example.com/api-docs"
            variant="info"
          />

          {/* minimal hero example */}
          <section className="flex flex-col items-center justify-center gap-4 py-16 text-center">
            <h1 className="text-foreground-secondary text-3xl font-bold tracking-tight">
              Developer Resources
            </h1>
            <div className="flex flex-col gap-2">
              <p className="text-muted-foreground max-w-md">
                Access documentation, guides, and API references
              </p>
              <a className="hover:text-primary underline underline-offset-4 transition">
                Browse Docs →
              </a>
            </div>
          </section>
        </div>
      );
    }

    ```
  </Tab>
</Tabs>

## Announcement Banner

<Tabs items={['Preview', 'Code']} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="banner">
      <BannerAnnouncementDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/banner-announcement-demo.tsx"
    import { Banner } from "@/components/billingsdk/banner";

    export default function BannerAnnouncementDemo() {
      return (
        <div className="bg-background-secondary flex h-full min-h-[500px] w-full flex-col gap-6 overflow-hidden rounded-lg border-2">
          <Banner
            title="🚀 Introducing Advanced Analytics"
            description="Get deeper insights into your billing data with our new analytics dashboard"
            buttonText="Explore Now"
            buttonLink="https://example.com/analytics"
            variant="announcement"
          />

          {/* minimal hero example */}
          <section className="flex flex-col items-center justify-center gap-4 py-16 text-center">
            <h1 className="text-foreground-secondary text-3xl font-bold tracking-tight">
              Advanced Analytics
            </h1>
            <div className="flex flex-col gap-2">
              <p className="text-muted-foreground max-w-md">
                Powerful insights to grow your business
              </p>
              <a className="hover:text-primary underline underline-offset-4 transition">
                Get Started →
              </a>
            </div>
          </section>
        </div>
      );
    }

    ```
  </Tab>
</Tabs>

## Usage

```tsx
import { Banner } from "@/components/billingsdk/banner";
```

```tsx
// Default Banner
<Banner
  title="🎉 Start your free trial today!"
  description="Get 30 days free access to all premium features"
  buttonText="Start Free Trial"
  buttonIcon={<Rocket />}
  buttonLink="https://example.com/signup"
  variant="default" // default, minimal, popup
/>
```

```tsx
// Minimal Banner
<Banner
  title="🎉 Start your free trial today!"
  description="Get 30 days free access to all premium features"
  variant="minimal" // default, minimal, popup
/>
```

```tsx
// Popup Banner
<Banner
  title="🎉 Start your free trial today!"
  description="Get 30 days free access to all premium features"
  variant="popup" // default, minimal, popup
/>
```

```tsx
// Gradient Banner
<Banner
  title="🌈 Experience the magic of gradients!"
  description="Beautiful animated gradient background with custom colors"
  buttonText="Learn More"
  buttonLink="https://example.com/gradients"
  variant="default"
  gradientColors={[
    "rgba(0,149,255,0.56)",
    "rgba(231,77,255,0.77)",
    "rgba(255,0,0,0.73)",
    "rgba(131,255,166,0.66)"
  ]}
/>
```

```tsx
// Destructive Banner
<Banner
  title="⚠️ Payment Failed - Subscription Suspended"
  description="Your subscription will be canceled in 3 days if payment is not updated"
  buttonText="Update Payment"
  buttonLink="https://example.com/billing"
  variant="destructive"
/>
```

```tsx
// Warning Banner
<Banner
  title="⚠️ System Maintenance Scheduled"
  description="Our services will be temporarily unavailable on Sunday, 2AM-4AM UTC"
  buttonText="Learn More"
  buttonLink="https://example.com/maintenance"
  variant="warning"
/>
```

```tsx
// Success Banner
<Banner
  title="✅ Payment Processed Successfully"
  description="Your subscription has been activated and you now have access to all premium features"
  buttonText="View Dashboard"
  buttonLink="https://example.com/dashboard"
  variant="success"
/>
```

```tsx
// Info Banner
<Banner
  title="ℹ️ New API Version Available"
  description="API v2.1 is now available with improved performance and new endpoints"
  buttonText="View Docs"
  buttonLink="https://example.com/api-docs"
  variant="info"
/>
```

```tsx
// Announcement Banner
<Banner
  title="🚀 Introducing Advanced Analytics"
  description="Get deeper insights into your billing data with our new analytics dashboard"
  buttonText="Explore Now"
  buttonLink="https://example.com/analytics"
  variant="announcement"
/>
```

## Props

| Prop             | Type                                                                                                       | Required | Description                                             |
| ---------------- | ---------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------- |
| `className`      | `string`                                                                                                   | ❌        | Additional CSS classes for styling                      |
| `title`          | `string`                                                                                                   | ✅        | The title of the banner                                 |
| `description`    | `string`                                                                                                   | ❌        | The description of the banner                           |
| `buttonText`     | `string`                                                                                                   | ❌        | The text of the button                                  |
| `buttonIcon`     | `React.ReactNode`                                                                                          | ❌        | The icon of the button                                  |
| `buttonLink`     | `string`                                                                                                   | ❌        | The link of the button                                  |
| `variant`        | `"default" \| "minimal" \| "popup" \| "destructive" \| "warning" \| "success" \| "info" \| "announcement"` | ✅        | The variant of the banner                               |
| `autoDismiss`    | `number`                                                                                                   | ❌        | The time in milliseconds to auto dismiss the banner     |
| `onDismiss`      | `() => void`                                                                                               | ❌        | The function to call when the banner is dismissed       |
| `gradientColors` | `string[]`                                                                                                 | ❌        | Array of color strings for animated gradient background |

## Gradient Colors

The `gradientColors` prop accepts an array of color strings (preferably in rgba format with alpha transparency). The gradient creates a smooth animated background effect.

### Color Guidelines:

* Use rgba colors with alpha values between 0.5-0.8 for best results
* Colors are automatically filtered for optimal contrast in both themes
* The gradient animation uses a 70-degree angle for a diagonal effect

## Example

```tsx title="src/components/banner-demo.tsx"
import { Banner } from "@/components/billingsdk/banner";

export default function FreeTrialBannerDemo() {
  return (
    <div className="bg-background-secondary flex h-full min-h-[500px] w-full flex-col gap-6 overflow-hidden rounded-lg border-2">
      <Banner
        title="🎉 Start your free trial today!"
        description="Get 30 days free access to all premium features"
        buttonText="Start Free Trial"
        buttonLink="https://example.com/signup"
        variant="default" // default, minimal, popup
      />

      {/* minimal hero example */}
      <section className="flex flex-col items-center justify-center gap-4 py-16 text-center">
        <h1 className="text-foreground-secondary text-3xl font-bold tracking-tight">
          Create next-generation digital products
        </h1>
        <div className="flex flex-col gap-2">
          <p className="text-muted-foreground max-w-md">
            Build faster with our platform
          </p>
          <a className="hover:text-primary underline underline-offset-4 transition">
            Get Started →
          </a>
        </div>
      </section>
    </div>
  );
}

```


# Billing Screen
URL: /docs/components/billing-screen

Complete billing dashboard with credit balance, plan details, and interactive credit card visual

***

title: Billing Screen
description: Complete billing dashboard with credit balance, plan details, and interactive credit card visual
-------------------------------------------------------------------------------------------------------------

<Tabs items={['Preview', 'Code']} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="billing-screen">
      <BillingScreenDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/billing-screen-demo.tsx"
    "use client";

    import { BillingScreen } from "@/components/billingsdk/billing-screen";

    export function BillingScreenDemo() {
      return (
        <div className="p-6">
          <BillingScreen
            planName="Premium Plan"
            planPrice="$20/mo"
            renewalDate="Oct 7, 2025"
            totalBalance="$6.59"
            username="rajoninternet"
            giftedCredits="$1.73"
            monthlyCredits="$3.13"
            monthlyCreditsLimit="$20.00"
            purchasedCredits="$0.00"
            resetDays={4}
            autoRechargeEnabled={false}
            onViewPlans={() => console.log("View Plans clicked")}
            onCancelPlan={() => console.log("Cancel Plan clicked")}
            onBuyCredits={() => console.log("Buy Credits clicked")}
            onEnableAutoRecharge={() => console.log("Enable Auto-recharge clicked")}
          />
        </div>
      );
    }

    ```
  </Tab>
</Tabs>

## Installation

<Tabs items={['shadcn', 'billingSDK']} defaultValue="shadcn" className="bg-transparent border-none">
  <Tab value="shadcn" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="installation-tabs">
      <Tab value="npx">
        ```bash
        npx shadcn@latest add @billingsdk/billing-screen
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @billingsdk/billing-screen
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @billingsdk/billing-screen
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx shadcn@latest add @billingsdk/billing-screen
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab value="billingSDK" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="billingsdk-cli-tabs">
      <Tab value="npx">
        ```bash
        npx @billingsdk/cli add billing-screen
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx @billingsdk/cli add billing-screen
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx @billingsdk/cli add billing-screen
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx @billingsdk/cli add billing-screen
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## Usage

```tsx
import { BillingScreen } from "@/components/billingsdk/billing-screen";
```

```tsx
<BillingScreen
  planName="Premium Plan"
  planPrice="$20/mo"
  renewalDate="Oct 7, 2025"
  totalBalance="$6.59"
  username="rajoninternet"
  giftedCredits="$1.73"
  monthlyCredits="$3.13"
  monthlyCreditsLimit="$20.00"
  purchasedCredits="$0.00"
  resetDays={4}
  autoRechargeEnabled={false}
  onViewPlans={() => console.log("View Plans clicked")}
  onCancelPlan={() => console.log("Cancel Plan clicked")}
  onBuyCredits={() => console.log("Buy Credits clicked")}
  onEnableAutoRecharge={() => console.log("Enable Auto-recharge clicked")}
  className="w-full"
/>
```

## Props

| Prop                   | Type         | Required | Description                                                  |
| ---------------------- | ------------ | -------- | ------------------------------------------------------------ |
| `className`            | `string`     | ❌        | Additional CSS classes                                       |
| `planName`             | `string`     | ❌        | Name of the current plan (default: "Premium Plan")           |
| `planPrice`            | `string`     | ❌        | Price of the current plan (default: "$20/mo")                |
| `renewalDate`          | `string`     | ❌        | Date when the plan renews (default: "Oct 7, 2025")           |
| `totalBalance`         | `string`     | ❌        | Total available credit balance (default: "$6.59")            |
| `username`             | `string`     | ❌        | Username displayed on credit card (default: "rajoninternet") |
| `giftedCredits`        | `string`     | ❌        | Amount of gifted credits (default: "$1.73")                  |
| `monthlyCredits`       | `string`     | ❌        | Amount of monthly credits used (default: "$3.13")            |
| `monthlyCreditsLimit`  | `string`     | ❌        | Total monthly credit limit (default: "$20.00")               |
| `purchasedCredits`     | `string`     | ❌        | Amount of purchased credits (default: "$0.00")               |
| `resetDays`            | `number`     | ❌        | Days until monthly credits reset (default: 4)                |
| `autoRechargeEnabled`  | `boolean`    | ❌        | Whether auto-recharge is enabled (default: false)            |
| `onViewPlans`          | `() => void` | ❌        | Callback when "View Plans" button is clicked                 |
| `onCancelPlan`         | `() => void` | ❌        | Callback when "Cancel Plan" button is clicked                |
| `onBuyCredits`         | `() => void` | ❌        | Callback when "Buy Credits" button is clicked                |
| `onEnableAutoRecharge` | `() => void` | ❌        | Callback when auto-recharge toggle is clicked                |

## Theming

The component is styled using the `shadcn/ui` library. You can customize the colors and fonts by overriding the CSS variables. You can also get the theme from the [Theming](/docs/theming) page.

## Example

```tsx title="src/components/billing-screen-demo.tsx"
"use client";

import { BillingScreen } from "@/components/billingsdk/billing-screen";

export function BillingScreenDemo() {
  return (
    <div className="p-6">
      <BillingScreen
        planName="Premium Plan"
        planPrice="$20/mo"
        renewalDate="Oct 7, 2025"
        totalBalance="$6.59"
        username="rajoninternet"
        giftedCredits="$1.73"
        monthlyCredits="$3.13"
        monthlyCreditsLimit="$20.00"
        purchasedCredits="$0.00"
        resetDays={4}
        autoRechargeEnabled={false}
        onViewPlans={() => console.log("View Plans clicked")}
        onCancelPlan={() => console.log("Cancel Plan clicked")}
        onBuyCredits={() => console.log("Buy Credits clicked")}
        onEnableAutoRecharge={() => console.log("Enable Auto-recharge clicked")}
      />
    </div>
  );
}

```

## Credits

* Created by [@rajoninternet](https://x.com/rajoninternet)


# Billing Settings
URL: /docs/components/billing-setting

The Billing Settings component provides a user-friendly interface for managing billing preferences, payment methods, invoices, and usage limits. This component features a tabbed navigation system, form controls, and an interactive payment card management section.

***

title: Billing Settings
description: The Billing Settings component provides a user-friendly interface for managing billing preferences, payment methods, invoices, and usage limits. This component features a tabbed navigation system, form controls, and an interactive payment card management section.
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

import BillingSettingsDemo from "src/components/billing-settings-demo.tsx"

<Tabs items={['Preview', 'Code']} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="billing-settings">
      <BillingSettingsDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/billing-settings-demo.tsx"
    "use client";

    import { useState } from "react";
    import {
      Dialog,
      DialogContent,
      DialogDescription,
      DialogFooter,
      DialogHeader,
      DialogTitle,
    } from "@/components/ui/dialog";
    import { Button } from "@/components/ui/button";
    import { Input } from "@/components/ui/input";
    import { Label } from "@/components/ui/label";
    import { Toaster, toast } from "sonner";
    import { BillingSettings } from "@/components/billingsdk/billing-settings";
    import { CreditCard } from "lucide-react";

    type InvoiceFormat = "PDF" | "HTML";

    interface Card {
      id: string;
      last4: string;
      brand: "Visa" | "MasterCard" | "Amex" | "Other";
      expiry: string;
      primary: boolean;
    }

    interface NewCardForm {
      number: string;
      expiry: string;
      cvc: string;
    }

    export default function BillingSettingsDemo() {
      const [activeTab, setActiveTab] = useState<
        "general" | "payment" | "invoices" | "limits"
      >("general");
      const [emailNotifications, setEmailNotifications] = useState<boolean>(true);
      const [usageAlerts, setUsageAlerts] = useState<boolean>(true);
      const [invoiceReminders, setInvoiceReminders] = useState<boolean>(false);
      const [cards, setCards] = useState<Card[]>([
        { id: "1", last4: "4242", brand: "Visa", expiry: "12/25", primary: true },
      ]);
      const [invoiceFormat, setInvoiceFormat] = useState<InvoiceFormat>("PDF");
      const [overageProtection, setOverageProtection] = useState<boolean>(true);
      const [usageLimitAlerts, setUsageLimitAlerts] = useState<boolean>(true);
      const [newCard, setNewCard] = useState<NewCardForm>({
        number: "",
        expiry: "",
        cvc: "",
      });
      const [open, setOpen] = useState<boolean>(false);

      const handleToggleEmailNotifications = (checked: boolean) => {
        console.log(`Email notifications toggled to: ${checked}`);
        setEmailNotifications(checked);
      };

      const handleToggleUsageAlerts = (checked: boolean) => {
        console.log(`Usage alerts toggled to: ${checked}`);
        setUsageAlerts(checked);
      };

      const handleToggleInvoiceReminders = (checked: boolean) => {
        console.log(`Invoice reminders toggled to: ${checked}`);
        setInvoiceReminders(checked);
      };

      const handleChangeInvoiceFormat = (format: InvoiceFormat) => {
        console.log(`Invoice format changed to: ${format}`);
        setInvoiceFormat(format);
      };

      const handleEditBillingAddress = () => {
        console.log("Edit billing address button clicked");
        toast.info("Edit billing address clicked!");
      };

      const handleToggleOverageProtection = (checked: boolean) => {
        console.log(`Overage protection toggled to: ${checked}`);
        setOverageProtection(checked);
      };

      const handleToggleUsageLimitAlerts = (checked: boolean) => {
        console.log(`Usage limit alerts toggled to: ${checked}`);
        setUsageLimitAlerts(checked);
      };

      const isValidCardNumber = (number: string): boolean => {
        const normalized = number.replace(/\s/g, "");
        return (
          normalized.length >= 13 &&
          normalized.length <= 19 &&
          /^\d+$/.test(normalized)
        );
      };

      const isValidExpiry = (expiry: string): boolean => {
        if (!/^(0[1-9]|1[0-2])\/?([0-9]{2})$/.test(expiry)) {
          return false;
        }
        const [month, year] = expiry.split("/").map(Number);
        const currentYear = Number(String(new Date().getFullYear()).slice(-2));
        const currentMonth = new Date().getMonth() + 1;
        if (year < currentYear || (year === currentYear && month < currentMonth)) {
          return false;
        }
        return true;
      };

      const isValidCvc = (cvc: string): boolean => {
        return /^\d{3,4}$/.test(cvc);
      };

      const detectCardBrand = (number: string): Card["brand"] => {
        if (number.startsWith("4")) return "Visa";
        if (/^5[1-5]/.test(number)) return "MasterCard";
        if (/^3[47]/.test(number)) return "Amex";
        return "Other";
      };

      const handleAddCard = (): void => {
        if (!isValidCardNumber(newCard.number)) {
          toast.error("Please enter a valid card number.");
          return;
        }
        if (!isValidExpiry(newCard.expiry)) {
          toast.error(
            "Please enter a valid expiry date (MM/YY) that's not in the past.",
          );
          return;
        }
        if (!isValidCvc(newCard.cvc)) {
          toast.error("Please enter a valid CVC.");
          return;
        }
        const last4 = newCard.number.slice(-4);
        const brand = detectCardBrand(newCard.number);
        const newCardData: Card = {
          id: String(cards.length + 1),
          last4,
          brand,
          expiry: newCard.expiry,
          primary: cards.length === 0,
        };
        setCards([...cards, newCardData]);
        setNewCard({ number: "", expiry: "", cvc: "" });
        setOpen(false);
        toast.success("Card added successfully!");
      };

      const formatCardNumber = (value: string): string => {
        const rawValue = value.replace(/\D/g, "");
        const formattedValue = rawValue.match(/.{1,4}/g)?.join(" ") || "";
        return formattedValue;
      };

      return (
        <div className="p-6">
          <BillingSettings
            activeTab={activeTab}
            onTabChange={(tab: string) =>
              setActiveTab(tab as "general" | "payment" | "invoices" | "limits")
            }
            emailNotifications={emailNotifications}
            onEmailNotificationsChange={handleToggleEmailNotifications}
            usageAlerts={usageAlerts}
            onUsageAlertsChange={handleToggleUsageAlerts}
            invoiceReminders={invoiceReminders}
            onInvoiceRemindersChange={handleToggleInvoiceReminders}
            cards={cards}
            onAddCard={() => setOpen(true)}
            invoiceFormat={invoiceFormat}
            onInvoiceFormatChange={handleChangeInvoiceFormat}
            onEditBillingAddress={handleEditBillingAddress}
            overageProtection={overageProtection}
            onOverageProtectionChange={handleToggleOverageProtection}
            usageLimitAlerts={usageLimitAlerts}
            onUsageLimitAlertsChange={handleToggleUsageLimitAlerts}
          />
          <Dialog open={open} onOpenChange={setOpen}>
            <DialogContent className="sm:max-w-md">
              <DialogHeader>
                <DialogTitle>Add Payment Card</DialogTitle>
                <DialogDescription>
                  Enter your card details to add a new payment method
                </DialogDescription>
              </DialogHeader>
              <div className="space-y-4 py-4">
                <div className="space-y-2">
                  <Label htmlFor="number">Card Number</Label>
                  <div className="relative">
                    <Input
                      id="number"
                      value={formatCardNumber(newCard.number)}
                      onChange={(e) => {
                        const rawValue = e.target.value.replace(/\s/g, "");
                        if (rawValue.length <= 19) {
                          setNewCard({ ...newCard, number: rawValue });
                        }
                      }}
                      placeholder="1234 5678 9012 3456"
                      className="pr-10"
                      maxLength={19}
                    />
                    <CreditCard className="text-muted-foreground absolute top-1/2 right-3 h-4 w-4 -translate-y-1/2" />
                  </div>
                </div>
                <div className="grid grid-cols-2 gap-4">
                  <div className="space-y-2">
                    <Label htmlFor="expiry">Expiry Date</Label>
                    <Input
                      id="expiry"
                      value={newCard.expiry}
                      onChange={(e) => {
                        let value = e.target.value.replace(/\D/g, "");
                        if (value.length >= 2) {
                          value = value.slice(0, 2) + "/" + value.slice(2, 4);
                        }
                        if (value.length <= 5) {
                          setNewCard({ ...newCard, expiry: value });
                        }
                      }}
                      placeholder="MM/YY"
                      maxLength={5}
                    />
                  </div>
                  <div className="space-y-2">
                    <Label htmlFor="cvc">CVC</Label>
                    <Input
                      id="cvc"
                      type="password"
                      value={newCard.cvc}
                      onChange={(e) => {
                        const value = e.target.value.replace(/\D/g, "");
                        if (value.length <= 4) {
                          setNewCard({ ...newCard, cvc: value });
                        }
                      }}
                      placeholder="123"
                      maxLength={4}
                    />
                  </div>
                </div>
              </div>
              <DialogFooter className="gap-2 sm:gap-0">
                <Button variant="outline" onClick={() => setOpen(false)}>
                  Cancel
                </Button>
                <Button onClick={handleAddCard}>Add Card</Button>
              </DialogFooter>
            </DialogContent>
          </Dialog>
          <Toaster />
        </div>
      );
    }

    ```
  </Tab>
</Tabs>

### Installation

<Tabs items={['shadcn', 'billingSDK']} defaultValue="shadcn" className="bg-transparent border-none">
  <Tab value="shadcn" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="installation-tabs">
      <Tab value="npx">
        ```bash
        npx shadcn@latest add @billingsdk/billing-settings
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @billingsdk/billing-settings
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @billingsdk/billing-settings
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx shadcn@latest add @billingsdk/billing-settings
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab value="billingSDK" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="billingsdk-cli-tabs">
      <Tab value="npx">
        ```bash
        npx @billingsdk/cli add billing-settings
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx @billingsdk/cli add billing-settings
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx @billingsdk/cli add billing-settings
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx @billingsdk/cli add billing-settings
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## Usage

```tsx
import { BillingSettings } from "@/components/billingsdk/billing-settings";
```

```tsx
const [activeTab, setActiveTab] = useState("general")
const [emailNotifications, setEmailNotifications] = useState(true)
const [usageAlerts, setUsageAlerts] = useState(true)
const [invoiceReminders, setInvoiceReminders] = useState(false)
const [cards, setCards] = useState([{ id: "1", last4: "4242", brand: "Visa", expiry: "12/25", primary: true }])
const [invoiceFormat, setInvoiceFormat] = useState("PDF")
const [overageProtection, setOverageProtection] = useState(true)
const [usageLimitAlerts, setUsageLimitAlerts] = useState(true)
```

```tsx
<BillingSettings
  activeTab={activeTab}
  onTabChange={setActiveTab}
  emailNotifications={emailNotifications}
  onEmailNotificationsChange={setEmailNotifications}
  usageAlerts={usageAlerts}
  onUsageAlertsChange={setUsageAlerts}
  invoiceReminders={invoiceReminders}
  onInvoiceRemindersChange={setInvoiceReminders}
  cards={cards}
  onAddCard={() => console.log("Add card clicked")}
  invoiceFormat={invoiceFormat}
  onInvoiceFormatChange={setInvoiceFormat}
  onEditBillingAddress={() => console.log("Edit billing address clicked")}
  overageProtection={overageProtection}
  onOverageProtectionChange={setOverageProtection}
  usageLimitAlerts={usageLimitAlerts}
  onUsageLimitAlertsChange={setUsageLimitAlerts}
/>
```

## Props

| Prop                         | Type                                | Description                                                                   |
| ---------------------------- | ----------------------------------- | ----------------------------------------------------------------------------- |
| `activeTab`                  | `String`                            | The currently active tab (`"general"`, `"payment"`, `"invoices"`, `"limits"`) |
| `onTabChange`                | `(tab: string) => void`             | Callback function for when a tab is changed                                   |
| `emailNotifications`         | `boolean`                           | State for email notifications switch                                          |
| `onEmailNotificationsChange` | `(value: boolean) => void`          | Callback for email notifications switch change                                |
| `usageAlerts`                | `boolean`                           | State for usage alerts switch                                                 |
| `onUsageAlertsChange`        | `(value: boolean) => void`          | Callback for usage alerts switch change                                       |
| `invoiceReminders`           | `boolean`                           | State for invoice reminders switch                                            |
| `onInvoiceRemindersChange`   | `(value: boolean) => void`          | Callback for invoice reminders switch change                                  |
| `cards`                      | `CardInfo[]`                        | An array of payment card objects                                              |
| `onAddCard`                  | `() => void`                        | Callback for the "Add new card" button                                        |
| `invoiceFormat`              | `"PDF" \| "HTML"`                   | The current invoice format                                                    |
| `onInvoiceFormatChange`      | `(format: "PDF" \| "HTML") => void` | Callback for invoice format change                                            |
| `onEditBillingAddress`       | `() => void`                        | Callback for the "Edit billing address" button                                |
| `overageProtection`          | `boolean`                           | State for overage protection switch                                           |
| `onOverageProtectionChange`  | `(value: boolean) => void`          | Callback for overage protection switch change                                 |
| `usageLimitAlerts`           | `boolean`                           | State for usage limit alerts switch                                           |
| `onUsageLimitAlertsChange`   | `(value: boolean) => void`          | Callback for usage limit alerts switch change                                 |

## Features

* **Tabbed Navigation**: Easily switch between different billing sections.
* **Payment Method Management**: View and add credit cards with basic validation.
* **Toggle Settings**: Control various notification and protection settings with switches.
* **Customizable Invoices**: Option to choose between PDF and HTML invoice formats.
* **Responsive Design**: Adapts to different screen sizes for a seamless user experience.

## Theming

The pricing table component is styled using the `shadcn/ui` library. You can customize the colors and fonts by overriding the CSS variables. You can also get the theme from the [Theming](/docs/theming) page.

## Example

```tsx title="src/components/billing-settings-demo.tsx"
"use client";

import { useState } from "react";
import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
} from "@/components/ui/dialog";
import { Button } from "@/components/ui/button";
import { Input } from "@/components/ui/input";
import { Label } from "@/components/ui/label";
import { Toaster, toast } from "sonner";
import { BillingSettings } from "@/components/billingsdk/billing-settings";
import { CreditCard } from "lucide-react";

type InvoiceFormat = "PDF" | "HTML";

interface Card {
  id: string;
  last4: string;
  brand: "Visa" | "MasterCard" | "Amex" | "Other";
  expiry: string;
  primary: boolean;
}

interface NewCardForm {
  number: string;
  expiry: string;
  cvc: string;
}

export default function BillingSettingsDemo() {
  const [activeTab, setActiveTab] = useState<
    "general" | "payment" | "invoices" | "limits"
  >("general");
  const [emailNotifications, setEmailNotifications] = useState<boolean>(true);
  const [usageAlerts, setUsageAlerts] = useState<boolean>(true);
  const [invoiceReminders, setInvoiceReminders] = useState<boolean>(false);
  const [cards, setCards] = useState<Card[]>([
    { id: "1", last4: "4242", brand: "Visa", expiry: "12/25", primary: true },
  ]);
  const [invoiceFormat, setInvoiceFormat] = useState<InvoiceFormat>("PDF");
  const [overageProtection, setOverageProtection] = useState<boolean>(true);
  const [usageLimitAlerts, setUsageLimitAlerts] = useState<boolean>(true);
  const [newCard, setNewCard] = useState<NewCardForm>({
    number: "",
    expiry: "",
    cvc: "",
  });
  const [open, setOpen] = useState<boolean>(false);

  const handleToggleEmailNotifications = (checked: boolean) => {
    console.log(`Email notifications toggled to: ${checked}`);
    setEmailNotifications(checked);
  };

  const handleToggleUsageAlerts = (checked: boolean) => {
    console.log(`Usage alerts toggled to: ${checked}`);
    setUsageAlerts(checked);
  };

  const handleToggleInvoiceReminders = (checked: boolean) => {
    console.log(`Invoice reminders toggled to: ${checked}`);
    setInvoiceReminders(checked);
  };

  const handleChangeInvoiceFormat = (format: InvoiceFormat) => {
    console.log(`Invoice format changed to: ${format}`);
    setInvoiceFormat(format);
  };

  const handleEditBillingAddress = () => {
    console.log("Edit billing address button clicked");
    toast.info("Edit billing address clicked!");
  };

  const handleToggleOverageProtection = (checked: boolean) => {
    console.log(`Overage protection toggled to: ${checked}`);
    setOverageProtection(checked);
  };

  const handleToggleUsageLimitAlerts = (checked: boolean) => {
    console.log(`Usage limit alerts toggled to: ${checked}`);
    setUsageLimitAlerts(checked);
  };

  const isValidCardNumber = (number: string): boolean => {
    const normalized = number.replace(/\s/g, "");
    return (
      normalized.length >= 13 &&
      normalized.length <= 19 &&
      /^\d+$/.test(normalized)
    );
  };

  const isValidExpiry = (expiry: string): boolean => {
    if (!/^(0[1-9]|1[0-2])\/?([0-9]{2})$/.test(expiry)) {
      return false;
    }
    const [month, year] = expiry.split("/").map(Number);
    const currentYear = Number(String(new Date().getFullYear()).slice(-2));
    const currentMonth = new Date().getMonth() + 1;
    if (year < currentYear || (year === currentYear && month < currentMonth)) {
      return false;
    }
    return true;
  };

  const isValidCvc = (cvc: string): boolean => {
    return /^\d{3,4}$/.test(cvc);
  };

  const detectCardBrand = (number: string): Card["brand"] => {
    if (number.startsWith("4")) return "Visa";
    if (/^5[1-5]/.test(number)) return "MasterCard";
    if (/^3[47]/.test(number)) return "Amex";
    return "Other";
  };

  const handleAddCard = (): void => {
    if (!isValidCardNumber(newCard.number)) {
      toast.error("Please enter a valid card number.");
      return;
    }
    if (!isValidExpiry(newCard.expiry)) {
      toast.error(
        "Please enter a valid expiry date (MM/YY) that's not in the past.",
      );
      return;
    }
    if (!isValidCvc(newCard.cvc)) {
      toast.error("Please enter a valid CVC.");
      return;
    }
    const last4 = newCard.number.slice(-4);
    const brand = detectCardBrand(newCard.number);
    const newCardData: Card = {
      id: String(cards.length + 1),
      last4,
      brand,
      expiry: newCard.expiry,
      primary: cards.length === 0,
    };
    setCards([...cards, newCardData]);
    setNewCard({ number: "", expiry: "", cvc: "" });
    setOpen(false);
    toast.success("Card added successfully!");
  };

  const formatCardNumber = (value: string): string => {
    const rawValue = value.replace(/\D/g, "");
    const formattedValue = rawValue.match(/.{1,4}/g)?.join(" ") || "";
    return formattedValue;
  };

  return (
    <div className="p-6">
      <BillingSettings
        activeTab={activeTab}
        onTabChange={(tab: string) =>
          setActiveTab(tab as "general" | "payment" | "invoices" | "limits")
        }
        emailNotifications={emailNotifications}
        onEmailNotificationsChange={handleToggleEmailNotifications}
        usageAlerts={usageAlerts}
        onUsageAlertsChange={handleToggleUsageAlerts}
        invoiceReminders={invoiceReminders}
        onInvoiceRemindersChange={handleToggleInvoiceReminders}
        cards={cards}
        onAddCard={() => setOpen(true)}
        invoiceFormat={invoiceFormat}
        onInvoiceFormatChange={handleChangeInvoiceFormat}
        onEditBillingAddress={handleEditBillingAddress}
        overageProtection={overageProtection}
        onOverageProtectionChange={handleToggleOverageProtection}
        usageLimitAlerts={usageLimitAlerts}
        onUsageLimitAlertsChange={handleToggleUsageLimitAlerts}
      />
      <Dialog open={open} onOpenChange={setOpen}>
        <DialogContent className="sm:max-w-md">
          <DialogHeader>
            <DialogTitle>Add Payment Card</DialogTitle>
            <DialogDescription>
              Enter your card details to add a new payment method
            </DialogDescription>
          </DialogHeader>
          <div className="space-y-4 py-4">
            <div className="space-y-2">
              <Label htmlFor="number">Card Number</Label>
              <div className="relative">
                <Input
                  id="number"
                  value={formatCardNumber(newCard.number)}
                  onChange={(e) => {
                    const rawValue = e.target.value.replace(/\s/g, "");
                    if (rawValue.length <= 19) {
                      setNewCard({ ...newCard, number: rawValue });
                    }
                  }}
                  placeholder="1234 5678 9012 3456"
                  className="pr-10"
                  maxLength={19}
                />
                <CreditCard className="text-muted-foreground absolute top-1/2 right-3 h-4 w-4 -translate-y-1/2" />
              </div>
            </div>
            <div className="grid grid-cols-2 gap-4">
              <div className="space-y-2">
                <Label htmlFor="expiry">Expiry Date</Label>
                <Input
                  id="expiry"
                  value={newCard.expiry}
                  onChange={(e) => {
                    let value = e.target.value.replace(/\D/g, "");
                    if (value.length >= 2) {
                      value = value.slice(0, 2) + "/" + value.slice(2, 4);
                    }
                    if (value.length <= 5) {
                      setNewCard({ ...newCard, expiry: value });
                    }
                  }}
                  placeholder="MM/YY"
                  maxLength={5}
                />
              </div>
              <div className="space-y-2">
                <Label htmlFor="cvc">CVC</Label>
                <Input
                  id="cvc"
                  type="password"
                  value={newCard.cvc}
                  onChange={(e) => {
                    const value = e.target.value.replace(/\D/g, "");
                    if (value.length <= 4) {
                      setNewCard({ ...newCard, cvc: value });
                    }
                  }}
                  placeholder="123"
                  maxLength={4}
                />
              </div>
            </div>
          </div>
          <DialogFooter className="gap-2 sm:gap-0">
            <Button variant="outline" onClick={() => setOpen(false)}>
              Cancel
            </Button>
            <Button onClick={handleAddCard}>Add Card</Button>
          </DialogFooter>
        </DialogContent>
      </Dialog>
      <Toaster />
    </div>
  );
}

```

### Credits

* Created by [@shashwat558](https://github.com/shashwat558)


# Billing Settings 2
URL: /docs/components/billing-settings-2

A comprehensive billing settings component with customizable input fields, feature toggles, currency selection, and built-in validation. Supports 180+ currencies and custom validation rules.

***

title: Billing Settings 2
description: A comprehensive billing settings component with customizable input fields, feature toggles, currency selection, and built-in validation. Supports 180+ currencies and custom validation rules.
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

<Tabs items={["Preview", "Code"]} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="billingsdk">
      <BillingSettings2Demo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/billing-settings-2-demo.tsx"
    "use client";

    import { BillingSettings2 } from "@/components/billingsdk/billing-settings-2";
    import { useState } from "react";

    export function BillingSettings2Demo() {
      const [inputValues, setInputValues] = useState({
        fullName: "",
        billingEmail: "",
        taxId: "",
      });

      const [featureToggles, setFeatureToggles] = useState({
        autoRenewal: true,
        invoiceEmails: true,
        promotionalEmails: false,
      });

      const [selectedCurrency, setSelectedCurrency] = useState("usd");

      const handleInputChange = (field: string, value: string) => {
        setInputValues((prev) => ({
          ...prev,
          [field]: value,
        }));
      };

      // Handler wrappers
      const createInputChangeHandler = (field: string) => (value: string) => {
        handleInputChange(field, value);
      };

      const createCurrencyChangeHandler =
        (setCurrency: (value: string) => void) => (value: string) => {
          console.log("Currency changed to:", value);
          setCurrency(value);
          // Add: updatePricing(value), savePreference(value), etc.
        };

      const handleFeatureToggle = (feature: string, enabled: boolean) => {
        setFeatureToggles((prev) => ({
          ...prev,
          [feature]: enabled,
        }));
      };

      const handleSave = () => {
        // Validation passed if we reach here
        alert("Settings saved successfully!");
        console.log("Input values:", inputValues);
        console.log("Feature toggles:", featureToggles);
        console.log("Selected currency:", selectedCurrency);
      };

      const handleCancel = () => {
        alert("Changes cancelled!");
      };

      return (
        <div className="p-6">
          <BillingSettings2
            title="Custom Billing Settings"
            inputFields={[
              {
                id: "fullName",
                name: "fullName",
                value: inputValues.fullName,
                placeholder: "Enter your full name",
                onChange: createInputChangeHandler("fullName"),
                label: "Full Name",
                type: "text",
                required: true,
                validation: {
                  minLength: 2,
                  maxLength: 50,
                },
              },
              {
                id: "billingEmail",
                name: "billingEmail",
                value: inputValues.billingEmail,
                placeholder: "user@example.com",
                onChange: createInputChangeHandler("billingEmail"),
                label: "Billing Email",
                helperText: "Invoices will be sent to this email address",
                type: "email",
                required: true,
              },
              {
                id: "taxId",
                name: "taxId",
                value: inputValues.taxId,
                placeholder: "EU123456789",
                onChange: createInputChangeHandler("taxId"),
                label: "Tax ID (Optional)",
                helperText: "For VAT or other tax purposes",
                type: "text",
                validation: {
                  pattern: /^[A-Z]{2}\d{8,12}$/,
                  customValidator: (value: string) => {
                    if (value && !/^[A-Z]{2}\d{8,12}$/.test(value)) {
                      return "Tax ID should be in format: XX followed by 8-12 digits (e.g., EU123456789)";
                    }
                    return null;
                  },
                },
              },
            ]}
            features={[
              {
                id: "auto-renewal",
                label: "Auto-Renewal",
                description: "Automatically renew your subscription",
                enabled: featureToggles.autoRenewal,
                onToggle: (enabled) => handleFeatureToggle("autoRenewal", enabled),
              },
              {
                id: "invoice-emails",
                label: "Invoice Emails",
                description: "Receive emails when invoices are generated",
                enabled: featureToggles.invoiceEmails,
                onToggle: (enabled) =>
                  handleFeatureToggle("invoiceEmails", enabled),
              },
              {
                id: "promotional-emails",
                label: "Promotional Emails",
                description:
                  "Receive occasional updates about new features and offers",
                enabled: featureToggles.promotionalEmails,
                onToggle: (enabled) =>
                  handleFeatureToggle("promotionalEmails", enabled),
              },
            ]}
            // CURRENCY: Shows all 180+ currencies by default
            // currencies={['USD', 'EUR', 'GBP']} // Specific currencies
            // currencyOptions={[{value: 'btc', label: 'Bitcoin'}]} // Custom

            defaultCurrency={selectedCurrency}
            onCurrencyChange={createCurrencyChangeHandler(setSelectedCurrency)}
            onSave={handleSave}
            onCancel={handleCancel}
            saveButtonText="Save Preferences"
            cancelButtonText="Discard Changes"
          />

          {/* 
    			USAGE EXAMPLES:
    			- Specific: currencies={['USD', 'EUR']}
    			- Custom: currencyOptions={[{value: 'btc', label: 'Bitcoin'}]}
    			- All: (no currency props) = 180+ currencies
    			- Handler: onCurrencyChange={(c) => updatePricing(c)}
    			*/}
        </div>
      );
    }

    ```
  </Tab>
</Tabs>

### Installation

<Tabs items={['shadcn', 'billingSDK']} defaultValue="shadcn" className="bg-transparent border-none">
  <Tab value="shadcn" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="installation-tabs">
      <Tab value="npx">
        ```bash
        npx shadcn@latest add @billingsdk/billing-settings-2 
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @billingsdk/billing-settings-2 
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @billingsdk/billing-settings-2 
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx shadcn@latest add @billingsdk/billing-settings-2 
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab value="billingSDK" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="billingsdk-cli-tabs">
      <Tab value="npx">
        ```bash
        npx @billingsdk/cli add billing-settings-2 
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx @billingsdk/cli add billing-settings-2 
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx @billingsdk/cli add billing-settings-2 
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx @billingsdk/cli add billing-settings-2 
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## Usage

```tsx
import { BillingSettings2 } from '@/components/billingsdk/billing-settings-2';
```

```tsx
<BillingSettings2
	title="Custom Billing Settings"
	enableValidation
	currencyRequired
	inputFields={[
		{
			id: "fullName",
			name: "fullName",
			value: inputValues.fullName,
			placeholder: "Enter your full name",
			onChange: (value) => handleInputChange('fullName', value),
			label: "Full Name",
			type: "text",
			required: true,
			validation: { 
				minLength: 2, 
				maxLength: 50,
				customValidator: (value) => {
					if (value && value.trim().length < 2) {
						return "Name must be at least 2 characters";
					}
					return null;
				}
			},
		},
		{
			id: "billingEmail",
			name: "billingEmail",
			value: inputValues.billingEmail,
			placeholder: "user@example.com",
			onChange: (value) => handleInputChange('billingEmail', value),
			label: "Billing Email",
			helperText: "Invoices will be sent to this email address",
			type: "email",
			required: true,
		},
		{
			id: "taxId",
			name: "taxId",
			value: inputValues.taxId,
			placeholder: "EU123456789",
			onChange: (value) => handleInputChange('taxId', value),
			label: "Tax ID (Optional)",
			helperText: "For VAT or other tax purposes",
			type: "text",
			validation: { 
				pattern: /^[A-Z]{2}\d{8,12}$/,
				customValidator: (value) => {
					if (value && !/^[A-Z]{2}\d{8,12}$/.test(value)) {
						return "Tax ID format: XX followed by 8-12 digits";
					}
					return null;
				}
			},
		},
	]}
	features={[
		{
			id: "auto-renewal",
			label: "Auto-Renewal",
			description: "Automatically renew your subscription",
			enabled: featureToggles.autoRenewal,
			onToggle: (enabled) => handleFeatureToggle('autoRenewal', enabled),
		},
		{
			id: "invoice-emails",
			label: "Invoice Emails",
			description: "Receive emails when invoices are generated",
			enabled: featureToggles.invoiceEmails,
			onToggle: (enabled) => handleFeatureToggle('invoiceEmails', enabled),
		},
		{
			id: "promotional-emails",
			label: "Promotional Emails",
			description: "Receive occasional updates about new features and offers",
			enabled: featureToggles.promotionalEmails,
			onToggle: (enabled) => handleFeatureToggle('promotionalEmails', enabled),
		},
	]}
	// Option 1: Use specific currencies (string array)
	currencies={['USD', 'EUR', 'GBP', 'CAD', 'AUD']}
	// Option 2: Use custom currency options (overrides currencies prop)
	// currencyOptions={[
	// 	{ value: "usd", label: "USD - US Dollar" },
	// 	{ value: "eur", label: "EUR - Euro" },
	// 	{ value: "btc", label: "BTC - Bitcoin" },
	// ]}
	// Option 3: Leave both undefined for all 180+ currencies
	defaultCurrency="usd"
	onCurrencyChange={(value) => {
		setSelectedCurrency(value);
		// Additional logic: updatePricing(value), savePreference(value), etc.
	}}
	onSave={handleSave}
	onCancel={handleCancel}
	saveButtonText="Save Preferences"
	cancelButtonText="Discard Changes"
/>
```

### Props

| Prop               | Type                                          | Default              | Description                                                                                             |
| ------------------ | --------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------- |
| `title`            | `string`                                      | `"Billing Settings"` | The title displayed at the top of the component                                                         |
| `features`         | `FeatureToggle[]`                             | See below            | Array of feature toggle configurations                                                                  |
| `inputFields`      | `InputField[]`                                | See below            | Array of input field configurations                                                                     |
| `onSave`           | `() => void`                                  | `() => {}`           | Function called when save button is clicked                                                             |
| `onCancel`         | `() => void`                                  | `() => {}`           | Function called when cancel button is clicked                                                           |
| `saveButtonText`   | `string`                                      | `"Save Changes"`     | Text for the save button                                                                                |
| `cancelButtonText` | `string`                                      | `"Cancel"`           | Text for the cancel button                                                                              |
| `currencies`       | `string[]` (optional)                         | `undefined`          | Array of currency codes to show (e.g., `['USD', 'EUR', 'GBP']`). Shows all 180+ currencies if undefined |
| `currencyOptions`  | `{value: string, label: string}[]` (optional) | `undefined`          | Custom currency options. Overrides `currencies` prop when provided                                      |
| `defaultCurrency`  | `string` (optional)                           | `"USD"`              | Default selected currency (case-insensitive)                                                            |
| `onCurrencyChange` | `(value: string) => void` (optional)          | `() => {}`           | Function called when currency is changed                                                                |
| `enableValidation` | `boolean` (optional)                          | `true`               | Enables built-in validation and error display                                                           |
| `currencyRequired` | `boolean` (optional)                          | `true`               | Requires a currency selection when saving                                                               |
| `className`        | `string`                                      | `undefined`          | Additional CSS classes to apply                                                                         |

### FeatureToggle Object

| Property      | Type                         | Description                             |
| ------------- | ---------------------------- | --------------------------------------- |
| `id`          | `string`                     | Unique identifier for the feature       |
| `label`       | `string`                     | Display label for the feature           |
| `description` | `string`                     | Description of what the feature does    |
| `enabled`     | `boolean`                    | Current state of the feature toggle     |
| `onToggle`    | `(enabled: boolean) => void` | Function called when toggle is switched |

### InputField Object

| Property       | Type                                              | Description                                   |
| -------------- | ------------------------------------------------- | --------------------------------------------- |
| `id`           | `string`                                          | Unique identifier for the input field         |
| `name`         | `string`                                          | Name attribute for the input field            |
| `value`        | `string` (optional)                               | Current value of the input field (controlled) |
| `defaultValue` | `string` (optional)                               | Default value for uncontrolled input          |
| `placeholder`  | `string`                                          | Placeholder text for the input field          |
| `onChange`     | `(value: string) => void`                         | Function called when input value changes      |
| `label`        | `string`                                          | Label displayed above the input field         |
| `helperText`   | `string` (optional)                               | Helper text displayed below the input field   |
| `type`         | `'text' \| 'email' \| 'tel' \| 'url' \| 'number'` | Type of input field                           |
| `required`     | `boolean` (optional)                              | Whether the field is required                 |
| `validation`   | `ValidationRules` (optional)                      | Optional validation rules object              |

### ValidationRules Object

| Property          | Type                                           | Description                                                   |
| ----------------- | ---------------------------------------------- | ------------------------------------------------------------- |
| `minLength`       | `number` (optional)                            | Minimum character length                                      |
| `maxLength`       | `number` (optional)                            | Maximum character length                                      |
| `pattern`         | `RegExp` (optional)                            | Regular expression pattern to match                           |
| `customValidator` | `(value: string) => string \| null` (optional) | Custom validation function that returns error message or null |

### Currency Configuration

**All currency props are optional!** The component supports three different currency configuration modes:

#### 1. All Currencies (Default)

```tsx
// Shows all 180+ currencies from currency-codes package
<BillingSettings2 />
```

#### 2. Specific Currencies

```tsx
// Shows only specified currency codes
<BillingSettings2 
	currencies={['USD', 'EUR', 'GBP', 'CAD', 'AUD']}
/>
```

#### 3. Custom Currency Options

```tsx
// Fully custom currency list (overrides currencies prop)
<BillingSettings2 
	currencyOptions={[
		{ value: "usd", label: "USD - US Dollar" },
		{ value: "eur", label: "EUR - Euro" },
		{ value: "btc", label: "BTC - Bitcoin" },
		{ value: "custom", label: "Custom Token" },
	]}
/>
```

> **Note:** When validation fails, the save button is disabled. It re-enables automatically as users correct invalid fields. Error messages are shown inline beneath each field.

## Examples

### Basic Setup

```tsx
import { BillingSettings2 } from '@/components/billingsdk/billing-settings-2';

export function BasicBillingSettings() {
  return (
    <BillingSettings2
      title="Account Settings"
      onSave={() => console.log('Settings saved')}
      onCancel={() => console.log('Changes cancelled')}
    />
  );
}
```

### With Custom Validation

```tsx
const customValidator = (value: string) => {
  if (value.includes('test')) {
    return "Test values are not allowed";
  }
  return null;
};

<BillingSettings2
  inputFields={[
    {
      id: "companyName",
      name: "companyName", 
      value: companyName,
      onChange: setCompanyName,
      label: "Company Name",
      validation: {
        minLength: 3,
        customValidator
      }
    }
  ]}
/>
```

### Specific Currencies Only

```tsx
<BillingSettings2
  currencies={['USD', 'EUR', 'GBP', 'JPY']}
  defaultCurrency="usd"
  onCurrencyChange={(currency) => {
    // Update pricing, save preference, etc.
    updatePricing(currency);
  }}
/>
```

### Disable Validation

```tsx
<BillingSettings2
  enableValidation={false}
  currencyRequired={false}
  // Save button will always be enabled
/>
```

## Features

* **Built-in Validation**: Email validation, pattern matching, custom validators
* **Currency Support**: 180+ currencies via currency-codes package
* **Flexible Configuration**: Custom input fields and feature toggles
* **Accessibility**: ARIA labels, keyboard navigation, screen reader support
* **TypeScript**: Full type safety with TypeScript interfaces
* **Responsive Design**: Works on mobile and desktop

## Dependencies

This component depends on:

* `currency-codes`: For comprehensive currency data
* `shadcn/ui`: Button, Card, Input, Label, Select, Switch components

### Credits

* Created by [@sapatmohit](https://github.com/sapatmohit) [@tsahil01](https://github.com/tsahil01) [@tejasnasre](https://github.com/tejasnasre)


# Cancel Subscription Card
URL: /docs/components/cancel-subscription/cancel-subscription-card

The Cancel Subscription Card component provides a comprehensive and user-friendly interface for handling subscription cancellations. It features a two-step confirmation process, loading states, error handling, and full customization options.

***

title: Cancel Subscription Card
description: The Cancel Subscription Card component provides a comprehensive and user-friendly interface for handling subscription cancellations. It features a two-step confirmation process, loading states, error handling, and full customization options.
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

<Tabs items={['Preview', 'Code']} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="cancel-subscription-card">
      <CancelSubscriptionCardDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/cancel-subscription-card-demo.tsx"
    "use client";

    import { CancelSubscriptionCard } from "@/components/billingsdk/cancel-subscription-card";
    import { plans } from "@/lib/billingsdk-config";

    export function CancelSubscriptionCardDemo() {
      return (
        <div className="flex w-full flex-col">
          <CancelSubscriptionCard
            title="We're sorry to see you go..."
            description={`Before you cancel, we hope you'll consider upgrading to a ${plans[1].title} plan again.`}
            plan={plans[1]}
            leftPanelImageUrl="https://framerusercontent.com/images/GWE8vop9hubsuh3uWWn0vyuxEg.webp"
            warningTitle="You will lose access to your account"
            warningText="If you cancel your subscription, you will lose access to your account and all your data will be deleted."
            keepButtonText={`Keep My ${plans[1].title} Plan`}
            continueButtonText="Continue with Cancellation"
            finalTitle="Final Step - Confirm Cancellation"
            finalSubtitle="This action will immediately cancel your subscription"
            finalWarningText="You'll lose access to all Pro features and your data will be permanently deleted after 30 days."
            goBackButtonText="Wait, Go Back"
            confirmButtonText="Yes, Cancel My Subscription"
            onCancel={async (planId) => {
              console.log("Cancelling subscription for plan:", planId);
              return new Promise((resolve) => {
                setTimeout(() => {
                  resolve(void 0);
                }, 1000);
              });
            }}
            onKeepSubscription={async (planId) => {
              console.log("Keeping subscription for plan:", planId);
            }}
            className="max-w-4xl"
          />
        </div>
      );
    }

    ```
  </Tab>
</Tabs>

## Installation

<Tabs items={['shadcn', 'billingSDK']} defaultValue="shadcn" className="bg-transparent border-none">
  <Tab value="shadcn" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="installation-tabs">
      <Tab value="npx">
        ```bash
        npx shadcn@latest add @billingsdk/cancel-subscription-card
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @billingsdk/cancel-subscription-card
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @billingsdk/cancel-subscription-card
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx shadcn@latest add @billingsdk/cancel-subscription-card
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab value="billingSDK" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="billingsdk-cli-tabs">
      <Tab value="npx">
        ```bash
        npx @billingsdk/cli add cancel-subscription-card
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx @billingsdk/cli add cancel-subscription-card
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx @billingsdk/cli add cancel-subscription-card
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx @billingsdk/cli add cancel-subscription-card
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## Usage

```tsx
import { CancelSubscriptionCard } from "@/components/billingsdk/cancel-subscription-card";
import { plans } from "@/lib/billingsdk-config";
```

```tsx
<CancelSubscriptionCard
  title="We're sorry to see you go..."
  description="Before you cancel, let us know what we could do better."
  plan={plans[1]}
  onCancel={async (planId) => {
    // Handle cancellation
    await cancelSubscription(planId);
  }}
/>
```

## Props

| Prop                 | Type                                        | Required | Description                                                                                            |
| -------------------- | ------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------ |
| `title`              | `string`                                    | ✅        | Main card title                                                                                        |
| `description`        | `string`                                    | ✅        | Card description text                                                                                  |
| `plan`               | `Plan`                                      | ✅        | Plan object containing subscription details. The `plans` array in the `lib/billingsdk-config.ts` file. |
| `onCancel`           | `(planId: string) => Promise<void> \| void` | ✅        | Callback when subscription is cancelled                                                                |
| `leftPanelImageUrl`  | `string`                                    | ❌        | Background image URL for left panel                                                                    |
| `warningTitle`       | `string`                                    | ❌        | Title for warning section                                                                              |
| `warningText`        | `string`                                    | ❌        | Warning message text                                                                                   |
| `keepButtonText`     | `string`                                    | ❌        | Text for keep subscription button                                                                      |
| `continueButtonText` | `string`                                    | ❌        | Text for continue cancellation button                                                                  |
| `finalTitle`         | `string`                                    | ❌        | Title for final confirmation step                                                                      |
| `finalSubtitle`      | `string`                                    | ❌        | Subtitle for final confirmation step                                                                   |
| `finalWarningText`   | `string`                                    | ❌        | Final warning message                                                                                  |
| `goBackButtonText`   | `string`                                    | ❌        | Text for go back button                                                                                |
| `confirmButtonText`  | `string`                                    | ❌        | Text for final confirm button                                                                          |
| `onKeepSubscription` | `(planId: string) => Promise<void> \| void` | ❌        | Callback when user keeps subscription                                                                  |
| `className`          | `string`                                    | ❌        | Additional CSS classes                                                                                 |

## Theming

The cancel subscription card component is styled using the `shadcn/ui` library. You can customize the colors and fonts by overriding the CSS variables. You can also get the theme from the [Theming](/docs/theming) page.

## Example

```tsx title="src/components/cancel-subscription-card-demo.tsx"
"use client";

import { CancelSubscriptionCard } from "@/components/billingsdk/cancel-subscription-card";
import { plans } from "@/lib/billingsdk-config";

export function CancelSubscriptionCardDemo() {
  return (
    <div className="flex w-full flex-col">
      <CancelSubscriptionCard
        title="We're sorry to see you go..."
        description={`Before you cancel, we hope you'll consider upgrading to a ${plans[1].title} plan again.`}
        plan={plans[1]}
        leftPanelImageUrl="https://framerusercontent.com/images/GWE8vop9hubsuh3uWWn0vyuxEg.webp"
        warningTitle="You will lose access to your account"
        warningText="If you cancel your subscription, you will lose access to your account and all your data will be deleted."
        keepButtonText={`Keep My ${plans[1].title} Plan`}
        continueButtonText="Continue with Cancellation"
        finalTitle="Final Step - Confirm Cancellation"
        finalSubtitle="This action will immediately cancel your subscription"
        finalWarningText="You'll lose access to all Pro features and your data will be permanently deleted after 30 days."
        goBackButtonText="Wait, Go Back"
        confirmButtonText="Yes, Cancel My Subscription"
        onCancel={async (planId) => {
          console.log("Cancelling subscription for plan:", planId);
          return new Promise((resolve) => {
            setTimeout(() => {
              resolve(void 0);
            }, 1000);
          });
        }}
        onKeepSubscription={async (planId) => {
          console.log("Keeping subscription for plan:", planId);
        }}
        className="max-w-4xl"
      />
    </div>
  );
}

```


# Cancel Subscription Dialog
URL: /docs/components/cancel-subscription/cancel-subscription-dialog

The Cancel Subscription Dialog component provides a comprehensive and user-friendly interface for handling subscription cancellations. It features a two-step confirmation process, loading states, error handling, and full customization options.

***

title: Cancel Subscription Dialog
description: The Cancel Subscription Dialog component provides a comprehensive and user-friendly interface for handling subscription cancellations. It features a two-step confirmation process, loading states, error handling, and full customization options.
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

<Tabs items={['Preview', 'Code']} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="cancel-subscription-dialog">
      <CancelSubscriptionDialogDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/cancel-subscription-dialog-demo.tsx"
    "use client";

    import { CancelSubscriptionDialog } from "@/components/billingsdk/cancel-subscription-dialog";
    import { plans } from "@/lib/billingsdk-config";

    export function CancelSubscriptionDialogDemo() {
      return (
        <div className="mx-auto flex min-h-[300px] flex-1 flex-col justify-center p-4 text-center">
          <CancelSubscriptionDialog
            title="We're sorry to see you go..."
            description={`Before you cancel, we hope you'll consider upgrading to a ${plans[1].title} plan again.`}
            plan={plans[1]}
            triggerButtonText="Cancel Subscription"
            leftPanelImageUrl="https://framerusercontent.com/images/GWE8vop9hubsuh3uWWn0vyuxEg.webp"
            warningTitle="You will lose access to your account"
            warningText="If you cancel your subscription, you will lose access to your account and all your data will be deleted."
            keepButtonText={`Keep My ${plans[1].title} Plan`}
            continueButtonText="Continue with Cancellation"
            finalTitle="Final Step - Confirm Cancellation"
            finalSubtitle="This action will immediately cancel your subscription"
            finalWarningText="You'll lose access to all Pro features and your data will be permanently deleted after 30 days."
            goBackButtonText="Wait, Go Back"
            confirmButtonText="Yes, Cancel My Subscription"
            onCancel={async (planId) => {
              console.log("Cancelling subscription for plan:", planId);
              return new Promise((resolve) => {
                setTimeout(() => {
                  resolve(void 0);
                }, 1000);
              });
            }}
            onKeepSubscription={async (planId) => {
              console.log("Keeping subscription for plan:", planId);
            }}
            onDialogClose={() => {
              console.log("Dialog closed");
            }}
            className="max-w-4xl"
          />
        </div>
      );
    }

    ```
  </Tab>
</Tabs>

## Installation

<Tabs items={['shadcn', 'billingSDK']} defaultValue="shadcn" className="bg-transparent border-none">
  <Tab value="shadcn" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="installation-tabs">
      <Tab value="npx">
        ```bash
        npx shadcn@latest add @billingsdk/cancel-subscription-dialog
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @billingsdk/cancel-subscription-dialog
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @billingsdk/cancel-subscription-dialog
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx shadcn@latest add @billingsdk/cancel-subscription-dialog
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab value="billingSDK" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="billingsdk-cli-tabs">
      <Tab value="npx">
        ```bash
        npx @billingsdk/cli add cancel-subscription-dialog
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx @billingsdk/cli add cancel-subscription-dialog
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx @billingsdk/cli add cancel-subscription-dialog
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx @billingsdk/cli add cancel-subscription-dialog
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## Usage

```tsx
import { CancelSubscriptionDialog } from "@/components/billingsdk/cancel-subscription-dialog";
import { plans } from "@/lib/billingsdk-config";
```

```tsx
<CancelSubscriptionDialog
  title="We're sorry to see you go..."
  description="Before you cancel, let us know what we could do better."
  plan={plans[1]}
  onCancel={async (planId) => {
    // Handle cancellation
    await cancelSubscription(planId);
  }}
/>
```

## Props

| Prop                 | Type                                        | Required | Description                                                                                            |
| -------------------- | ------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------ |
| `title`              | `string`                                    | ✅        | Main dialog title                                                                                      |
| `description`        | `string`                                    | ✅        | Dialog description text                                                                                |
| `plan`               | `Plan`                                      | ✅        | Plan object containing subscription details. The `plans` array in the `lib/billingsdk-config.ts` file. |
| `onCancel`           | `(planId: string) => Promise<void> \| void` | ✅        | Callback when subscription is cancelled                                                                |
| `triggerButtonText`  | `string`                                    | ❌        | Text for the trigger button (default: "Cancel Subscription")                                           |
| `leftPanelImageUrl`  | `string`                                    | ❌        | Background image URL for left panel                                                                    |
| `warningTitle`       | `string`                                    | ❌        | Title for warning section                                                                              |
| `warningText`        | `string`                                    | ❌        | Warning message text                                                                                   |
| `keepButtonText`     | `string`                                    | ❌        | Text for keep subscription button                                                                      |
| `continueButtonText` | `string`                                    | ❌        | Text for continue cancellation button                                                                  |
| `finalTitle`         | `string`                                    | ❌        | Title for final confirmation step                                                                      |
| `finalSubtitle`      | `string`                                    | ❌        | Subtitle for final confirmation step                                                                   |
| `finalWarningText`   | `string`                                    | ❌        | Final warning message                                                                                  |
| `goBackButtonText`   | `string`                                    | ❌        | Text for go back button                                                                                |
| `confirmButtonText`  | `string`                                    | ❌        | Text for final confirm button                                                                          |
| `onKeepSubscription` | `(planId: string) => Promise<void> \| void` | ❌        | Callback when user keeps subscription                                                                  |
| `onDialogClose`      | `() => void`                                | ❌        | Callback when dialog is closed                                                                         |
| `className`          | `string`                                    | ❌        | Additional CSS classes                                                                                 |

## Theming

The cancel subscription dialog component is styled using the `shadcn/ui` library. You can customize the colors and fonts by overriding the CSS variables. You can also get the theme from the [Theming](/docs/theming) page.

## Example

```tsx title="src/components/cancel-subscription-dialog-demo.tsx"
"use client";

import { CancelSubscriptionDialog } from "@/components/billingsdk/cancel-subscription-dialog";
import { plans } from "@/lib/billingsdk-config";

export function CancelSubscriptionDialogDemo() {
  return (
    <div className="mx-auto flex min-h-[300px] flex-1 flex-col justify-center p-4 text-center">
      <CancelSubscriptionDialog
        title="We're sorry to see you go..."
        description={`Before you cancel, we hope you'll consider upgrading to a ${plans[1].title} plan again.`}
        plan={plans[1]}
        triggerButtonText="Cancel Subscription"
        leftPanelImageUrl="https://framerusercontent.com/images/GWE8vop9hubsuh3uWWn0vyuxEg.webp"
        warningTitle="You will lose access to your account"
        warningText="If you cancel your subscription, you will lose access to your account and all your data will be deleted."
        keepButtonText={`Keep My ${plans[1].title} Plan`}
        continueButtonText="Continue with Cancellation"
        finalTitle="Final Step - Confirm Cancellation"
        finalSubtitle="This action will immediately cancel your subscription"
        finalWarningText="You'll lose access to all Pro features and your data will be permanently deleted after 30 days."
        goBackButtonText="Wait, Go Back"
        confirmButtonText="Yes, Cancel My Subscription"
        onCancel={async (planId) => {
          console.log("Cancelling subscription for plan:", planId);
          return new Promise((resolve) => {
            setTimeout(() => {
              resolve(void 0);
            }, 1000);
          });
        }}
        onKeepSubscription={async (planId) => {
          console.log("Keeping subscription for plan:", planId);
        }}
        onDialogClose={() => {
          console.log("Dialog closed");
        }}
        className="max-w-4xl"
      />
    </div>
  );
}

```


# Detailed Usage Table
URL: /docs/components/detailed-usage-table

The Detailed Usage Table component provides a comprehensive breakdown of resource consumption with columns for resource name, used amount, limit, and percentage utilization. The percentage field is now optional and will be automatically calculated if not provided.

***

title: Detailed Usage Table
description: The Detailed Usage Table component provides a comprehensive breakdown of resource consumption with columns for resource name, used amount, limit, and percentage utilization. The percentage field is now optional and will be automatically calculated if not provided.
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

<Tabs items={["Preview", "Code"]} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="billingsdk">
      <DetailedUsageTableDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/detailed-usage-table-demo.tsx"
    "use client";

    import { DetailedUsageTable } from "@/components/billingsdk/detailed-usage-table";

    export function DetailedUsageTableDemo() {
      return (
        <DetailedUsageTable
          title="Resource Usage"
          description="Detailed breakdown of your resource consumption"
          resources={[
            {
              name: "API Calls",
              used: 12300,
              limit: 20000,
              // percentage will be automatically calculated as 61.5%
              unit: "calls",
            },
            { name: "Storage", used: 850, limit: 1000, percentage: 85, unit: "GB" },
            {
              name: "Team Members",
              used: 4,
              limit: 5,
              // percentage will be automatically calculated as 80%
              unit: "users",
            },
            {
              name: "Bandwidth",
              used: 1500,
              limit: 2000,
              percentage: 75,
              unit: "GB",
            },
            {
              name: "Emails",
              used: 8500,
              limit: 10000,
              // percentage will be automatically calculated as 85%
              unit: "emails",
            },
          ]}
        />
      );
    }

    ```
  </Tab>
</Tabs>

## Installation

<Tabs items={['shadcn', 'billingSDK']} defaultValue="shadcn" className="bg-transparent border-none">
  <Tab value="shadcn" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="installation-tabs">
      <Tab value="npx">
        ```bash
        npx shadcn@latest add @billingsdk/detailed-usage-table
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @billingsdk/detailed-usage-table
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @billingsdk/detailed-usage-table
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx shadcn@latest add @billingsdk/detailed-usage-table
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab value="billingSDK" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="billingsdk-cli-tabs">
      <Tab value="npx">
        ```bash
        npx @billingsdk/cli add detailed-usage-table
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx @billingsdk/cli add detailed-usage-table
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx @billingsdk/cli add detailed-usage-table
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx @billingsdk/cli add detailed-usage-table
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## Usage

```tsx
import { DetailedUsageTable } from '@/components/billingsdk/detailed-usage-table';
```

```tsx
<DetailedUsageTable
	title="Resource Usage"
	description="Detailed breakdown of your resource consumption"
	resources={[
		{
			name: 'API Calls',
			used: 12300,
			limit: 20000,
			// percentage will be automatically calculated as 61.5%
			unit: 'calls',
		},
		{ name: 'Storage', used: 850, limit: 1000, percentage: 85, unit: 'GB' },
		{ name: 'Team Members', used: 4, limit: 5, unit: 'users' }, // percentage will be automatically calculated as 80%
	]}
/>;
```

## Props

| Prop        | Type              | Description                                      |
| ----------- | ----------------- | ------------------------------------------------ |
| className   | `string`          | Additional CSS classes to apply to the component |
| title       | `string`          | Title for the usage table section                |
| description | `string`          | Description for the usage table section          |
| resources   | `UsageResource[]` | Array of resource usage data                     |

### UsageResource Object

| Property   | Type                | Description                                                            |
| ---------- | ------------------- | ---------------------------------------------------------------------- |
| name       | `string`            | Name of the resource                                                   |
| used       | `number`            | Amount of the resource used                                            |
| limit      | `number`            | Total limit for the resource                                           |
| percentage | `number` *optional* | Percentage of resource used (automatically calculated if not provided) |
| unit       | `string`            | Unit of measurement (optional)                                         |

```tsx
<DetailedUsageTable
	title="Monthly Resource Consumption"
	description="Track your usage across all plan resources"
	resources={[
		{
			name: 'API Requests',
			used: 45210,
			limit: 50000,
			// percentage will be automatically calculated as 90.4%
			unit: 'requests',
		},
		{
			name: 'File Storage',
			used: 750,
			limit: 1000,
			percentage: 75,
			unit: 'GB',
		},
		{ name: 'Team Seats', used: 8, limit: 5, unit: 'seats' }, // percentage will be automatically calculated as 160%
		{
			name: 'Bandwidth',
			used: 1850,
			limit: 2000,
			// percentage will be automatically calculated as 92.5%
			unit: 'GB',
		},
	]}
/>
```

### Credits

* Created by [@sapatmohit](https://github.com/sapatmohit)


# Invoice History
URL: /docs/components/invoice-history

Read-only table for displaying past invoices and receipts with status and download actions.

***

title: Invoice History
description: Read-only table for displaying past invoices and receipts with status and download actions.
--------------------------------------------------------------------------------------------------------

<Tabs items={['Preview', 'Code']} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="invoice-history">
      <InvoiceHistoryDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/invoice-history-demo.tsx"
    "use client";

    import {
      InvoiceHistory,
      type InvoiceItem,
    } from "@/components/billingsdk/invoice-history";

    export default function InvoiceHistoryDemo() {
      const invoices: InvoiceItem[] = [
        {
          id: "inv_001",
          date: "2025-06-01",
          amount: "$49.00",
          status: "paid",
          description: "Pro plan — May 2025",
          invoiceUrl: "https://example.com/invoices/inv_001.pdf",
        },
        {
          id: "inv_002",
          date: "2025-05-01",
          amount: "$49.00",
          status: "paid",
          description: "Pro plan — April 2025",
          invoiceUrl: "https://example.com/invoices/inv_002.pdf",
        },
        {
          id: "inv_003",
          date: "2025-04-01",
          amount: "$49.00",
          status: "refunded",
          description: "Pro plan — March 2025",
        },
        {
          id: "inv_004",
          date: "2025-03-01",
          amount: "$49.00",
          status: "open",
          description: "Pro plan — February 2025",
        },
      ];

      return (
        <div className="w-full">
          <InvoiceHistory invoices={invoices} />
        </div>
      );
    }

    ```
  </Tab>
</Tabs>

## Installation

<Tabs items={['shadcn', 'billingSDK']} defaultValue="shadcn" className="bg-transparent border-none">
  <Tab value="shadcn" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="installation-tabs">
      <Tab value="npx">
        ```bash
        npx shadcn@latest add @billingsdk/invoice-history
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @billingsdk/invoice-history
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @billingsdk/invoice-history
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx shadcn@latest add @billingsdk/invoice-history
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab value="billingSDK" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="billingsdk-cli-tabs">
      <Tab value="npx">
        ```bash
        npx @billingsdk/cli add invoice-history
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx @billingsdk/cli add invoice-history
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx @billingsdk/cli add invoice-history
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx @billingsdk/cli add invoice-history
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## Usage

```tsx
import { InvoiceHistory, type InvoiceItem } from "@/components/billingsdk/invoice-history";
```

```tsx
const invoices: InvoiceItem[] = [
  { id: 'inv_001', date: '2025-06-01', amount: '$49.00', status: 'paid' },
  { id: 'inv_002', date: '2025-05-01', amount: '$49.00', status: 'paid' },
];
```

```tsx
<InvoiceHistory invoices={invoices} />
```

## Props

| Prop          | Type                          | Required | Description                             |
| ------------- | ----------------------------- | -------- | --------------------------------------- |
| `invoices`    | `InvoiceItem[]`               | ✅        | List of invoices to display             |
| `className`   | `string`                      | ❌        | Additional CSS classes for styling      |
| `title`       | `string`                      | ❌        | Optional heading text                   |
| `description` | `string`                      | ❌        | Optional description text               |
| `onDownload`  | `(invoiceId: string) => void` | ❌        | Callback if no `invoiceUrl` is provided |

## InvoiceItem

```ts
interface InvoiceItem {
  id: string;
  date: string;
  amount: string;
  status: 'paid' | 'refunded' | 'open' | 'void';
  invoiceUrl?: string;
  description?: string;
}
```

### Credits

* Created by [@ritiksahni22](https://x.com/ritiksahni22)


# Limited Offer Dialog
URL: /docs/components/limited-offer-dialog

The Limited Offer Dialog component provides a compelling interface for displaying time-sensitive offers and promotions. It features customizable content, loading states, error handling, and smooth animations to maximize conversion rates.

***

title: Limited Offer Dialog
description: The Limited Offer Dialog component provides a compelling interface for displaying time-sensitive offers and promotions. It features customizable content, loading states, error handling, and smooth animations to maximize conversion rates.
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

<Tabs items={['Preview', 'Code']} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="limited-offer-dialog">
      <LimitedOfferDialogDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/limited-offer-dialog-demo.tsx"
    "use client";

    import { LimitedOfferDialog } from "@/components/billingsdk/limited-offer-dialog";

    // Sample offer data
    const sampleOffer = {
      id: "limited-offer-dialog",
      title: "Special Offer",
      description: "Limited time deal",
      discount: "50% OFF",
      features: [
        { name: "50% off your first month" },
        { name: "Valid until December 31, 2024" },
        { name: "First 100 users only" },
      ],
    };

    export function LimitedOfferDialogDemo() {
      const handleClaimOffer = async (offerId: string) => {
        console.log("Claiming offer:", offerId);
        // Simulate API call
        await new Promise((resolve) => setTimeout(resolve, 1000));
        alert("Offer claimed successfully!");
      };

      const handleDeclineOffer = async (offerId: string) => {
        console.log("Declining offer:", offerId);
        // Simulate API call
        await new Promise((resolve) => setTimeout(resolve, 500));
        alert("Offer declined. You can always come back later!");
      };

      const handleDialogClose = () => {
        console.log("Dialog closed");
      };

      return (
        <div className="mx-auto flex min-h-[300px] flex-1 flex-col justify-center p-4 text-center">
          <LimitedOfferDialog
            title="🔥 Limited Time Offer!"
            description="Grab this deal before it's gone"
            offer={sampleOffer}
            triggerButtonText="Open Offer Dialog"
            warningTitle="Don't miss out!"
            warningText="This exclusive offer won't last long. Claim it now before it's gone forever."
            claimButtonText="👉 Claim Offer Now"
            declineButtonText="No thanks, I'll pay full price"
            onClaimOffer={handleClaimOffer}
            onDeclineOffer={handleDeclineOffer}
            onDialogClose={handleDialogClose}
            className="w-auto"
          />
        </div>
      );
    }

    ```
  </Tab>
</Tabs>

## Installation

<Tabs items={['shadcn', 'billingSDK']} defaultValue="shadcn" className="bg-transparent border-none">
  <Tab value="shadcn" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="installation-tabs">
      <Tab value="npx">
        ```bash
        npx shadcn@latest add @billingsdk/limited-offer-dialog
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @billingsdk/limited-offer-dialog
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @billingsdk/limited-offer-dialog
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx shadcn@latest add @billingsdk/limited-offer-dialog
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab value="billingSDK" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="billingsdk-cli-tabs">
      <Tab value="npx">
        ```bash
        npx @billingsdk/cli add limited-offer-dialog
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx @billingsdk/cli add limited-offer-dialog
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx @billingsdk/cli add limited-offer-dialog
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx @billingsdk/cli add limited-offer-dialog
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## Usage

```tsx
import { LimitedOfferDialog } from "@/components/billingsdk/limited-offer-dialog";
```

```tsx
<LimitedOfferDialog
  title="🔥 Limited Time Offer!"
  description="Grab this deal before it's gone"
  offer={{
    id: "limited-offer-dialog",
    title: "Special Offer",
    description: "Limited time deal",
    discount: "50% OFF",
    features: [
      { name: "50% off your first month" },
      { name: "Valid until December 31, 2024" },
      { name: "First 100 users only" }
    ]
  }}
  triggerButtonText="Open Offer Dialog"
  warningTitle="Don't miss out!"
  warningText="This exclusive offer won't last long. Claim it now before it's gone forever."
  claimButtonText="👉 Claim Offer Now"
  declineButtonText="No thanks, I'll pay full price"
  onClaimOffer={async (offerId) => {
    console.log("Claiming offer:", offerId);
    // Simulate API call
    await new Promise(resolve => setTimeout(resolve, 1000));
    alert("Offer claimed successfully!");
  }}
  onDeclineOffer={async (offerId) => {
    console.log("Declining offer:", offerId);
    // Simulate API call
    await new Promise(resolve => setTimeout(resolve, 500));
    alert("Offer declined. You can always come back later!");
  }}
  onDialogClose={() => {
    // Handle dialog close
    console.log("Dialog closed");
  }}
/>
```

## Props

| Prop                | Type                                         | Required | Description                                                                                                    |
| ------------------- | -------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------- |
| `title`             | `string`                                     | ❌        | Main dialog title (default: "🔥 Limited Time Offer!")                                                          |
| `description`       | `string`                                     | ❌        | Dialog description text (default: "Grab this deal before it's gone")                                           |
| `offer`             | `Offer`                                      | ❌        | Offer object containing offer details (uses defaultOffer if not provided)                                      |
| `triggerButtonText` | `string`                                     | ❌        | Text for the trigger button (default: "Open Offer Dialog")                                                     |
| `warningTitle`      | `string`                                     | ❌        | Title for warning section (default: "Don't miss out!")                                                         |
| `warningText`       | `string`                                     | ❌        | Warning message text (default: "This exclusive offer won't last long. Claim it now before it's gone forever.") |
| `claimButtonText`   | `string`                                     | ❌        | Text for claim offer button (default: "👉 Claim Offer Now")                                                    |
| `declineButtonText` | `string`                                     | ❌        | Text for decline button (default: "No thanks, I'll pay full price")                                            |
| `onClaimOffer`      | `(offerId: string) => Promise<void> \| void` | ❌        | Callback when offer is claimed                                                                                 |
| `onDeclineOffer`    | `(offerId: string) => Promise<void> \| void` | ❌        | Callback when offer is declined                                                                                |
| `onDialogClose`     | `() => void`                                 | ❌        | Callback when dialog is closed                                                                                 |
| `className`         | `string`                                     | ❌        | Additional CSS classes                                                                                         |

## Offer Interface

```tsx
interface Offer {
  id: string;
  title: string;
  description: string;
  discount: string;
  features: Array<{
    name: string;
    icon?: string;
    iconColor?: string;
  }>;
}
```

## Theming

The limited offer dialog component is styled using the `shadcn/ui` library. You can customize the colors and fonts by overriding the CSS variables. You can also get the theme from the [Theming](/docs/theming) page.

## Example

```tsx title="src/components/limited-offer-dialog-demo.tsx"
"use client";

import { LimitedOfferDialog } from "@/components/billingsdk/limited-offer-dialog";

// Sample offer data
const sampleOffer = {
  id: "limited-offer-dialog",
  title: "Special Offer",
  description: "Limited time deal",
  discount: "50% OFF",
  features: [
    { name: "50% off your first month" },
    { name: "Valid until December 31, 2024" },
    { name: "First 100 users only" },
  ],
};

export function LimitedOfferDialogDemo() {
  const handleClaimOffer = async (offerId: string) => {
    console.log("Claiming offer:", offerId);
    // Simulate API call
    await new Promise((resolve) => setTimeout(resolve, 1000));
    alert("Offer claimed successfully!");
  };

  const handleDeclineOffer = async (offerId: string) => {
    console.log("Declining offer:", offerId);
    // Simulate API call
    await new Promise((resolve) => setTimeout(resolve, 500));
    alert("Offer declined. You can always come back later!");
  };

  const handleDialogClose = () => {
    console.log("Dialog closed");
  };

  return (
    <div className="mx-auto flex min-h-[300px] flex-1 flex-col justify-center p-4 text-center">
      <LimitedOfferDialog
        title="🔥 Limited Time Offer!"
        description="Grab this deal before it's gone"
        offer={sampleOffer}
        triggerButtonText="Open Offer Dialog"
        warningTitle="Don't miss out!"
        warningText="This exclusive offer won't last long. Claim it now before it's gone forever."
        claimButtonText="👉 Claim Offer Now"
        declineButtonText="No thanks, I'll pay full price"
        onClaimOffer={handleClaimOffer}
        onDeclineOffer={handleDeclineOffer}
        onDialogClose={handleDialogClose}
        className="w-auto"
      />
    </div>
  );
}

```

### Credits

* Created by [@rajoninternet](https://x.com/rajoninternet)


# Manage Subscription
URL: /docs/components/manage-subscription

The Manage Subscription component provides a comprehensive interface for users to view and manage their current subscription details, including plan information, billing details, and actions to update or cancel their subscription.

***

title: Manage Subscription
description: The Manage Subscription component provides a comprehensive interface for users to view and manage their current subscription details, including plan information, billing details, and actions to update or cancel their subscription.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

<Tabs items={['Preview', 'Code']} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="subscription-management">
      <SubscriptionManagementDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/subscription-management-demo.tsx"
    "use client";

    import { SubscriptionManagement } from "@/components/billingsdk/subscription-management";
    import { type CurrentPlan, plans } from "@/lib/billingsdk-config";

    export function SubscriptionManagementDemo() {
      const currentPlan: CurrentPlan = {
        plan: plans[1],
        type: "monthly",
        price: "$121",
        nextBillingDate: "January 15, 2025",
        paymentMethod: "Credit Card",
        status: "active",
      };
      return (
        <div className="flex flex-1 flex-col justify-center text-center">
          <SubscriptionManagement
            className="mx-auto max-w-2xl"
            currentPlan={currentPlan}
            updatePlan={{
              currentPlan: currentPlan.plan,
              plans: plans,
              onPlanChange: (planId) => {
                console.log("update plan", planId);
              },
              triggerText: "Update Plan",
            }}
            cancelSubscription={{
              title: "Cancel Subscription",
              description: "Are you sure you want to cancel your subscription?",
              leftPanelImageUrl:
                "https://img.freepik.com/free-vector/abstract-paper-cut-shape-wave-background_474888-4649.jpg?semt=ais_hybrid&w=740&q=80",
              plan: currentPlan.plan,
              warningTitle: "You will lose access to your account",
              warningText:
                "If you cancel your subscription, you will lose access to your account and all your data will be deleted.",
              onCancel: async (planId) => {
                console.log("cancel subscription", planId);
                return new Promise((resolve) => {
                  setTimeout(() => {
                    resolve(void 0);
                  }, 1000);
                });
              },
              onKeepSubscription: async (planId) => {
                console.log("keep subscription", planId);
              },
            }}
          />
        </div>
      );
    }

    ```
  </Tab>
</Tabs>

### Related

* See also: [Invoice History](/docs/components/invoice-history)
* See also: [Payment Success Dialog](/docs/components/payment-success-dialog)

## Installation

<Tabs items={["shadcn", "billingSDK"]} defaultValue="shadcn" className="border-none bg-transparent">
  <Tab value="shadcn" className="mt-3 border-none bg-transparent p-0">
    <Tabs items={["npx", "pnpm", "yarn", "bun"]} defaultValue="npx" groupId="installation-tabs">
      <Tab value="npx">
        ```bash
        npx shadcn@latest add @billingsdk/subscription-management
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @billingsdk/subscription-management
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @billingsdk/subscription-management
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx shadcn@latest add @billingsdk/subscription-management
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab value="billingSDK" className="mt-3 border-none bg-transparent p-0">
    <Tabs items={["npx", "pnpm", "yarn", "bun"]} defaultValue="npx" groupId="billingsdk-cli-tabs">
      <Tab value="npx">
        ```bash
        npx @billingsdk/cli add subscription-management
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx @billingsdk/cli add subscription-management
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx @billingsdk/cli add subscription-management
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx @billingsdk/cli add subscription-management
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## Usage

```tsx
import { SubscriptionManagement } from "@/components/billingsdk/subscription-management";
import { type CurrentPlan, plans } from "@/lib/billingsdk-config";

const currentPlan: CurrentPlan = {
  plan: plans[1],
  type: "monthly",
  price: "$121",
  nextBillingDate: "January 15, 2025",
  paymentMethod: "Credit Card",
  status: "active",
};
```

```tsx
<SubscriptionManagement
  className="mx-auto max-w-2xl"
  currentPlan={currentPlan}
  updatePlan={{
    currentPlan: currentPlan.plan,
    plans: plans,
    onPlanChange: (planId) => {
      console.log("update plan", planId);
    },
    triggerText: "Update Plan",
  }}
  cancelSubscription={{
    title: "Cancel Subscription",
    description: "Are you sure you want to cancel your subscription?",
    plan: currentPlan.plan,
    onCancel: async (planId) => {
      // Handle cancellation
      await cancelSubscription(planId);
    },
  }}
/>
```

## Props

| Prop                 | Type                            | Required | Description                                    |
| -------------------- | ------------------------------- | -------- | ---------------------------------------------- |
| `className`          | `string`                        | ❌        | Additional CSS classes for styling             |
| `currentPlan`        | `CurrentPlan`                   | ✅        | Object containing current subscription details |
| `cancelSubscription` | `CancelSubscriptionDialogProps` | ✅        | Props for the cancel subscription dialog       |
| `updatePlan`         | `UpdatePlanDialogProps`         | ✅        | Props for the update plan dialog               |

## CurrentPlan Interface

Refer to the [CurrentPlan Interface](/docs/interfaces#currentplan-interface) for more details.

```tsx
interface CurrentPlan {
  plan: Plan;
  type: "monthly" | "yearly" | "custom";
  price: string;
  nextBillingDate: string;
  paymentMethod: string;
  status: "active" | "inactive" | "cancelled" | "past_due";
}
```

## Theming

The subscription management component is styled using the `shadcn/ui` library. You can customize the colors and fonts by overriding the CSS variables. You can also get the theme from the [Theming](/docs/theming) page.

## Example

```tsx title="src/components/subscription-management-demo.tsx"
"use client";

import { SubscriptionManagement } from "@/components/billingsdk/subscription-management";
import { type CurrentPlan, plans } from "@/lib/billingsdk-config";

export function SubscriptionManagementDemo() {
  const currentPlan: CurrentPlan = {
    plan: plans[1],
    type: "monthly",
    price: "$121",
    nextBillingDate: "January 15, 2025",
    paymentMethod: "Credit Card",
    status: "active",
  };
  return (
    <div className="flex flex-1 flex-col justify-center text-center">
      <SubscriptionManagement
        className="mx-auto max-w-2xl"
        currentPlan={currentPlan}
        updatePlan={{
          currentPlan: currentPlan.plan,
          plans: plans,
          onPlanChange: (planId) => {
            console.log("update plan", planId);
          },
          triggerText: "Update Plan",
        }}
        cancelSubscription={{
          title: "Cancel Subscription",
          description: "Are you sure you want to cancel your subscription?",
          leftPanelImageUrl:
            "https://img.freepik.com/free-vector/abstract-paper-cut-shape-wave-background_474888-4649.jpg?semt=ais_hybrid&w=740&q=80",
          plan: currentPlan.plan,
          warningTitle: "You will lose access to your account",
          warningText:
            "If you cancel your subscription, you will lose access to your account and all your data will be deleted.",
          onCancel: async (planId) => {
            console.log("cancel subscription", planId);
            return new Promise((resolve) => {
              setTimeout(() => {
                resolve(void 0);
              }, 1000);
            });
          },
          onKeepSubscription: async (planId) => {
            console.log("keep subscription", planId);
          },
        }}
      />
    </div>
  );
}

```


# Usage-based Pricing
URL: /docs/components/manage-subscription/usage-based-pricing

Interactive usage-based pricing with a ruler slider, 100-step grid, clickable 1,000-credit markers, and smooth animations.

***

title: Usage-based Pricing
description: Interactive usage-based pricing with a ruler slider, 100-step grid, clickable 1,000-credit markers, and smooth animations.
---------------------------------------------------------------------------------------------------------------------------------------

<Tabs items={['Preview', 'Code']} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="usage-based-pricing">
      <UsageBasedPricingDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/usage-based-pricing-demo.tsx"
    "use client";

    import { UsageBasedPricing } from "@/components/billingsdk/usage-based-pricing";

    export function UsageBasedPricingDemo() {
      return (
        <div className="flex flex-1 flex-col justify-center text-center">
          <UsageBasedPricing className="mx-auto max-w-5xl" />
        </div>
      );
    }

    ```
  </Tab>
</Tabs>

## Installation

<Tabs items={['shadcn', 'billingSDK']} defaultValue="shadcn" className="bg-transparent border-none">
  <Tab value="shadcn" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="installation-tabs">
      <Tab value="npx">
        ```bash
        npx shadcn@latest add @billingsdk/usage-based-pricing
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @billingsdk/usage-based-pricing
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @billingsdk/usage-based-pricing
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx shadcn@latest add @billingsdk/usage-based-pricing
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab value="billingSDK" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="billingsdk-cli-tabs">
      <Tab value="npx">
        ```bash
        npx @billingsdk/cli add usage-based-pricing
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx @billingsdk/cli add usage-based-pricing
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx @billingsdk/cli add usage-based-pricing
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx @billingsdk/cli add usage-based-pricing
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## Usage

```tsx
import { useState } from "react";
import { UsageBasedPricing } from "@/components/billingsdk/usage-based-pricing";

export default function Page() {
  const [credits, setCredits] = useState(4000);
  return (
    <div className="flex flex-1 flex-col items-center justify-center text-center space-y-6">
      <UsageBasedPricing
        className="w-full max-w-5xl"
        min={4000}
        max={25001}
        snapTo={100}
        currency="$"
        basePrice={39.99}
        includedCredits={4000}
        value={credits}
        onChange={setCredits}
        onChangeEnd={(v) => console.log("Committed:", v)}
        title="Pay as you use pricing"
        subtitle="Start with a flat monthly rate that includes 4,000 credits."
      />
      <div className="text-xs text-muted-foreground">Current value: {credits.toLocaleString()} credits</div>
    </div>
  );
}
```

## Features

* Smooth, lag-free slider with animated tick heights and precise pointer tracking.
* 100-credit live increments (configurable via `snapTo`).
* Clickable 1,000-credit dots that animate to the target instead of teleporting.
* Start/end labels centered beneath the first and last dots.
* Keyboard accessible: Arrow keys move by base step (default 100), Shift+Arrow moves faster, Home/End jump to edges.
* Price model example included: base price plus $10 per 1,000 credits above the included amount.

## Props

| Prop                 | Type                      | Default                                                         | Description                                                                                                     |
| -------------------- | ------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `min`                | `number`                  | `4000`                                                          | Minimum credits.                                                                                                |
| `max`                | `number`                  | `25001`                                                         | Maximum credits.                                                                                                |
| `value`              | `number`                  | —                                                               | Controlled value (credits).                                                                                     |
| `defaultValue`       | `number`                  | `4000`                                                          | Uncontrolled initial credits.                                                                                   |
| `onChange`           | `(value: number) => void` | —                                                               | Called on value change during drag/animation.                                                                   |
| `onChangeEnd`        | `(value: number) => void` | —                                                               | Called when interaction completes.                                                                              |
| `step`               | `number`                  | `1`                                                             | Fine step (used for keyboard when `snapTo` not provided).                                                       |
| `snapTo`             | `number`                  | —                                                               | Live quantization step. If omitted, drag uses 100; release snaps to `snapTo`, else to `step` (>1), else to 100. |
| `currency`           | `string`                  | `"$"`                                                           | Currency symbol.                                                                                                |
| `basePrice`          | `number`                  | `39.99`                                                         | Base price covering included credits.                                                                           |
| `includedCredits`    | `number`                  | `4000`                                                          | Credits included in base price.                                                                                 |
| `unitPricePerCredit` | `number`                  | `0.01`                                                          | Unit price (not used in the $10/1000 example model).                                                            |
| `title`              | `string`                  | `"Pay as you use pricing"`                                      | Heading text.                                                                                                   |
| `subtitle`           | `string`                  | `"Start with a flat monthly rate that includes 4,000 credits."` | Subheading text.                                                                                                |


# Payment Card
URL: /docs/components/payment-card

A comprehensive payment interface for processing final transactions with card details, billing information, and visual card preview.

***

title: Payment Card
description: A comprehensive payment interface for processing final transactions with card details, billing information, and visual card preview.
-------------------------------------------------------------------------------------------------------------------------------------------------

<Tabs items={['Preview', 'Code']} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="payment-card">
      <PaymentCardDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/payment-card-demo.tsx"
    "use client";
    import { PaymentCard } from "@/components/billingsdk/payment-card";

    export function PaymentCardDemo() {
      return (
        <PaymentCard
          title="Final step, make the payment."
          description="To finalize your subscription, kindly complete your payment using a valid credit card."
          price="100"
          finalText={[
            { text: "Automated billing & invoices" },
            { text: "Priority support" },
            { text: "Exclusive member benefits" },
          ]}
          feature="Payment & Invoice"
          featuredescription="Automated billing and invoicing with detailed transaction records. Professional receipts delivered instantly to your email."
          feature2="Priority Support"
          feature2description="Get dedicated customer support with faster response times and direct access to our technical team for any issues."
          onPay={async ({ cardNumber, expiry, cvc }) => {
            console.log(
              `Payment Processed! ${cardNumber}, exp ${expiry}, cvc ${cvc}`,
            );
          }}
        />
      );
    }

    export default PaymentCardDemo;

    ```
  </Tab>
</Tabs>

## Installation

<Tabs items={['shadcn', 'billingSDK']} defaultValue="shadcn" className="bg-transparent border-none">
  <Tab value="shadcn" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="installation-tabs">
      <Tab value="npx">
        ```bash
        npx shadcn@latest add @billingsdk/payment-card
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @billingsdk/payment-card
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @billingsdk/payment-card
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx shadcn@latest add @billingsdk/payment-card
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab value="billingSDK" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="billingsdk-cli-tabs">
      <Tab value="npx">
        ```bash
        npx @billingsdk/cli add payment-card
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx @billingsdk/cli add payment-card
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx @billingsdk/cli add payment-card
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx @billingsdk/cli add payment-card
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## Usage

```tsx
import { PaymentCard, type PaymentCardProps } from "@/components/billingsdk/payment-card";
```

```tsx
<PaymentCard
    title="Final step, make the payment."
    description="To finalize your subscription, kindly complete your payment using a valid credit card."
    price="320"
    finalText={[
    { text: "Automated billing & invoices" },
    { text: "Priority support" },
    { text: "Exclusive member benefits" },
    ]}
    onPay={async ({ cardNumber, expiry, cvc }) => {
    alert(`Payment Processed! ${cardNumber}, exp ${expiry}, cvc ${cvc}`);
    }}
/>
```

## Props

| Prop                  | Type                                                                                   | Required | Description                                         |
| --------------------- | -------------------------------------------------------------------------------------- | -------- | --------------------------------------------------- |
| `title`               | `string`                                                                               | ✅        | Main heading shown above the form                   |
| `description`         | `string`                                                                               | ✅        | Short description under the title                   |
| `price`               | `string`                                                                               | ✅        | Amount displayed on the summary card (e.g. `"100"`) |
| `onPay`               | `(data: { cardNumber: string; expiry: string; cvc: string }) => Promise<void> \| void` | ✅        | Callback function called when payment is submitted  |
| `finalText`           | `{ text: string }[]`                                                                   | ❌        | Rotating footer messages shown in the summary       |
| `feature`             | `string`                                                                               | ❌        | Title for the first feature section                 |
| `featuredescription`  | `string`                                                                               | ❌        | Description for the first feature                   |
| `feature2`            | `string`                                                                               | ❌        | Title for the second feature section                |
| `feature2description` | `string`                                                                               | ❌        | Description for the second feature                  |
| `className`           | `string`                                                                               | ❌        | Additional classes to style the root `Card`         |

## Features

* **Animated Interface**: Enhanced user experience with smooth animations powered by Motion for the summary panel and interactive elements
* **Form Validation**: Built-in validation for credit card inputs with real-time feedback and error handling
* **Responsive Design**: Optimized for all screen sizes with mobile-first approach

## Theming

The Payment card component is styled using the `shadcn/ui` library. You can customize the colors and fonts by overriding the CSS variables. You can also get the theme from the [Theming](/docs/theming) page.

### Credits

* Created by [@Turf](https://x.com/PotatoTurf)


# Payment Details
URL: /docs/components/payment-details

A comprehensive payment details form component with card details, billing information, and country selection for secure payment processing.

***

title: Payment Details
description: A comprehensive payment details form component with card details, billing information, and country selection for secure payment processing.
--------------------------------------------------------------------------------------------------------------------------------------------------------

<Tabs items={['Preview', 'Code']} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="payment-details">
      <PaymentDetailsDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/payment-details-demo.tsx"
    "use client";

    import { useState } from "react";
    import {
      PaymentDetails,
      type PaymentFormData,
    } from "@/components/billingsdk/payment-details";

    export function PaymentDetailsDemo() {
      const [showConfirmation, setShowConfirmation] = useState(false);

      const handleSubmit = async (_data: PaymentFormData) => {
        // Simulate API call
        await new Promise((resolve) => setTimeout(resolve, 1500));
        setShowConfirmation(true);

        // Auto-hide confirmation after 3 seconds
        setTimeout(() => {
          setShowConfirmation(false);
        }, 3000);
      };

      const handleDiscard = () => {
        console.log("Form discarded");
      };

      return (
        <div className="flex w-full justify-center">
          <PaymentDetails
            title="Payment Details"
            description="Enter your payment information to complete the transaction."
            onSubmit={handleSubmit}
            onDiscard={handleDiscard}
            showConfirmation={showConfirmation}
            onConfirmationClose={() => setShowConfirmation(false)}
          />
        </div>
      );
    }

    ```
  </Tab>
</Tabs>

## Installation

Choose your preferred installation method:

<Tabs items={['shadcn', 'billingSDK']} defaultValue="shadcn" className="bg-transparent border-none">
  <Tab value="shadcn" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="installation-tabs">
      <Tab value="npx">
        ```bash
        npx shadcn@latest add @billingsdk/payment-details
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @billingsdk/payment-details
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @billingsdk/payment-details
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx shadcn@latest add @billingsdk/payment-details
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab value="billingSDK" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="billingsdk-cli-tabs">
      <Tab value="npx">
        ```bash
        npx @billingsdk/cli add payment-details
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx @billingsdk/cli add payment-details
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx @billingsdk/cli add payment-details
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx @billingsdk/cli add payment-details
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## Usage

### Basic Import

```tsx
import { PaymentDetails, type PaymentFormData } from "@/components/billingsdk/payment-details";
```

### Basic Implementation

```tsx
import { useState } from "react";

function PaymentForm() {
  const [showConfirmation, setShowConfirmation] = useState(false);
  
  const handleSubmit = async (data: PaymentFormData) => {
    // Process payment data
    console.log('Payment data:', data);
    setShowConfirmation(true);
  };

  return (
    <PaymentDetails
      title="Payment Details"
      description="Enter your payment information to complete the transaction."
      onSubmit={handleSubmit}
      onDiscard={() => console.log('Form discarded')}
      showConfirmation={showConfirmation}
      onConfirmationClose={() => setShowConfirmation(false)}
      countries={["India", "United States", "United Kingdom", "Canada", "Australia"]}
      states={["Bihar", "Karnataka", "Maharashtra"]}
      cities={["Patna", "Bangalore", "Mumbai"]}
    />
  );
}
```

## Props

The PaymentDetails component accepts the following props:

| Prop                  | Type                                               | Required | Description                                      |
| --------------------- | -------------------------------------------------- | -------- | ------------------------------------------------ |
| `className`           | `string`                                           | ❌        | Additional CSS classes for styling               |
| `title`               | `string`                                           | ❌        | Main title for the payment form                  |
| `description`         | `string`                                           | ❌        | Description text below the title                 |
| `initialData`         | `Partial<PaymentFormData>`                         | ❌        | Initial form data                                |
| `onSubmit`            | `(data: PaymentFormData) => void \| Promise<void>` | ❌        | Callback when form is submitted                  |
| `onDiscard`           | `() => void`                                       | ❌        | Callback when discard button is clicked          |
| `submitButtonText`    | `string`                                           | ❌        | Text for submit button (default: "Save Changes") |
| `discardButtonText`   | `string`                                           | ❌        | Text for discard button (default: "Discard")     |
| `isLoading`           | `boolean`                                          | ❌        | External loading state                           |
| `showConfirmation`    | `boolean`                                          | ❌        | Show success confirmation modal                  |
| `confirmationTitle`   | `string`                                           | ❌        | Title for confirmation modal                     |
| `confirmationMessage` | `string`                                           | ❌        | Message for confirmation modal                   |
| `onConfirmationClose` | `() => void`                                       | ❌        | Callback when confirmation is closed             |
| `countries`           | `string[]`                                         | ❌        | List of countries for dropdown                   |
| `states`              | `string[]`                                         | ❌        | List of states for dropdown                      |
| `cities`              | `string[]`                                         | ❌        | List of cities for dropdown                      |

## PaymentFormData Interface

The form data structure for the PaymentDetails component:

```ts
interface PaymentFormData {
  nameOnCard?: string;
  cardNumber?: string;
  validTill?: string;
  cvv?: string;
  firstName?: string;
  middleLastName?: string;
  country?: string;
  state?: string;
  city?: string;
  billingAddress?: string;
  pinCode?: string;
  contactNumber?: string;
}
```

## Features

The PaymentDetails component comes with a comprehensive set of features:

### Core Functionality

* **Card Type Detection**: Automatically detects and displays card type (Visa, Mastercard, Amex, RuPay, Diners)
* **Input Formatting**: Automatically formats card numbers, expiry dates, and other fields
* **Validation**: Built-in form validation with error messages
* **Country Selection**: Dropdown for country selection with customizable options

### Design & UX

* **Responsive Design**: Mobile-friendly layout with responsive grid
* **Dark Mode Support**: Full dark mode compatibility with theme-aware styling
* **Hover Animations**: Smooth hover effects and transitions for better UX
* **Accessibility**: Proper labels, ARIA attributes, and keyboard navigation

### Customization

* **Customizable**: Extensive props for customization and theming
* **Confirmation Modal**: Optional success confirmation with customizable messages

## Supported Card Types

The component automatically detects and displays the appropriate card type:

| Card Type            | Pattern                     | Description                     |
| -------------------- | --------------------------- | ------------------------------- |
| **Visa**             | Starting with 4             | Most common international card  |
| **Mastercard**       | Starting with 5 or 2        | Global payment network          |
| **American Express** | Starting with 34 or 37      | Premium card with unique format |
| **RuPay**            | Starting with 6             | Indian domestic payment system  |
| **Diners Club**      | Starting with 30, 36, or 38 | International charge card       |

## Validation Rules

The component includes comprehensive client-side validation:

### Field Requirements

* **Card Number**: Minimum 13 digits, maximum 16 digits
* **Expiry Date**: MM/YY format (e.g., 12/25)
* **CVV**: 3-4 digits depending on card type
* **PIN Code**: Exactly 6 digits
* **Contact Number**: Exactly 10 digits

### Required vs Optional Fields

* **Required**: All fields except country, state, and city
* **Optional**: Country, state, and city selections

## Theming & Customization

The PaymentDetails component supports comprehensive theming and customization options.

### Dark Mode Support

The component automatically adapts to dark mode using theme-aware CSS classes:

* **Background**: Uses `bg-background` and `bg-card` for proper dark mode support
* **Text Colors**: Uses `text-foreground` and `text-muted-foreground` for theme-aware text
* **Borders**: Uses `border-border` for consistent theming
* **Focus States**: Uses `focus:ring-ring` for theme-aware focus indicators
* **Error States**: Uses `text-destructive` and `border-destructive` for consistent error styling

### Theme Integration

The component integrates seamlessly with the BillingSDK theme system:

```tsx
import { useTheme } from '@/contexts/theme-context'
import { getThemeStyles } from '@/lib/themes'

// The component automatically applies theme styles
<PaymentDetails 
  // Theme styles are applied automatically
  // ... other props
/>
```

### Custom Styling

You can customize the appearance by passing custom className:

```tsx
<PaymentDetails 
  className="max-w-2xl mx-auto" 
  // ... other props
/>
```

### Interactive Animations

The component includes smooth hover animations for enhanced user experience:

* **Save Changes Button**: Scale animation (`hover:scale-105`) with enhanced shadow
* **Discard Button**: Subtle hover effects with background color changes
* **Form Inputs**: Smooth focus transitions with ring effects

## Example Implementation

Here's a complete example of how to implement the PaymentDetails component:

```tsx title="src/components/payment-details-demo.tsx"
"use client";

import { useState } from "react";
import {
  PaymentDetails,
  type PaymentFormData,
} from "@/components/billingsdk/payment-details";

export function PaymentDetailsDemo() {
  const [showConfirmation, setShowConfirmation] = useState(false);

  const handleSubmit = async (_data: PaymentFormData) => {
    // Simulate API call
    await new Promise((resolve) => setTimeout(resolve, 1500));
    setShowConfirmation(true);

    // Auto-hide confirmation after 3 seconds
    setTimeout(() => {
      setShowConfirmation(false);
    }, 3000);
  };

  const handleDiscard = () => {
    console.log("Form discarded");
  };

  return (
    <div className="flex w-full justify-center">
      <PaymentDetails
        title="Payment Details"
        description="Enter your payment information to complete the transaction."
        onSubmit={handleSubmit}
        onDiscard={handleDiscard}
        showConfirmation={showConfirmation}
        onConfirmationClose={() => setShowConfirmation(false)}
      />
    </div>
  );
}

```

## Credits

* Created by [@saishankar404](https://github.com/saishankar404)


# Payment Details Two
URL: /docs/components/payment-details-two

A comprehensive payment details form component with card details, billing information, and country selection for secure payment processing.

***

title: Payment Details Two
description: A comprehensive payment details form component with card details, billing information, and country selection for secure payment processing.
--------------------------------------------------------------------------------------------------------------------------------------------------------

<Tabs items={['Preview', 'Code']} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="payment-details-two">
      <PaymentDetailsTwoDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/payment-details-two-demo.tsx"
    "use client";

    import {
      PaymentDetailsTwo,
      type PaymentFormData,
    } from "@/components/billingsdk/payment-details-two";

    export function PaymentDetailsTwoDemo() {
      //Function that handles onSubmit in the Form
      const handleSubmit = async (_data: PaymentFormData) => {
        // _data contains all the form values entered by the user:
        // e.g., _data.cardNumber, _data.nameOnCard, _data.validTill, _data.cvv, _data.firstName, etc.
        // You can use this object to make an API call to your backend, for example:
        // await fetch('/api/payment', { method: 'POST', body: JSON.stringify(_data) })

        return await new Promise((resolve) => {
          setTimeout(() => {
            console.log("Handle Submit Function");
            resolve("The promise is resolved");
          }, 3000);
        });
      };

      //Function that handles onCancel in the Form
      const handleDiscard = () => {
        console.log("The Discard Function");
      };

      return (
        <PaymentDetailsTwo onSubmit={handleSubmit} onDiscard={handleDiscard} />
      );
    }

    ```
  </Tab>
</Tabs>

## Installation

Choose your preferred installation method:

<Tabs items={['shadcn', 'billingSDK']} defaultValue="shadcn" className="bg-transparent border-none">
  <Tab value="shadcn" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn']} defaultValue="npx" groupId="installation-tabs">
      <Tab value="npx">
        ```bash
        npx shadcn@latest add @billingsdk/payment-details-two
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @billingsdk/payment-details-two
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @billingsdk/payment-details-two
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab value="billingSDK" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn']} defaultValue="npx" groupId="billingsdk-cli-tabs">
      <Tab value="npx">
        ```bash
        npx @billingsdk/cli add payment-details-two
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx @billingsdk/cli add payment-details-two
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx @billingsdk/cli add payment-details-two
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## Usage

### Basic Import

```tsx
import { PaymentDetailsTwo , type PaymentFormData} from "@/components/billingsdk/payment-details-two";
```

### Basic Implementation

```tsx
"use client"

import { PaymentDetailsTwo , type PaymentFormData} from "@/components/billingsdk/payment-details-two";


export function PaymentDetailsTwoDemo() {

//Function that handles onSubmit in the Form
const handleSubmit = async (_data: PaymentFormData) => {
  // _data contains all the form values entered by the user:
  // e.g., _data.cardNumber, _data.nameOnCard, _data.validTill, _data.cvv, _data.firstName, etc.
  // You can use this object to make an API call to your backend, for example:
  // await fetch('/api/payment', { method: 'POST', body: JSON.stringify(_data) })
  
  return await new Promise((resolve) => {
    setTimeout(() => {
      console.log("Handle Submit Function")
      resolve('The promise is resolved')
    }, 3000)
  })
}


//Function that handles onCancel in the Form
  const handleDiscard = ()=>{
    console.log("The Discard Function")
  }

  return (
    <PaymentDetailsTwo
      onSubmit={handleSubmit}
      onDiscard={handleDiscard}
    />
  )
}
```

## Props

The PaymentDetails component accepts the following props:

| Prop        | Type                                               | Required | Description                             |
| ----------- | -------------------------------------------------- | -------- | --------------------------------------- |
| `className` | `string`                                           | ❌        | Additional CSS classes for styling      |
| `onSubmit`  | `(data: PaymentFormData) => void \| Promise<void>` | ❌        | Callback when form is submitted         |
| `onDiscard` | `() => void`                                       | ❌        | Callback when discard button is clicked |
| `countries` | `{name: string, isoCode: string}[]`                | ❌        | List of countries for dropdown          |
| `states`    | `{name: string, isoCode: string}[]`                | ❌        | List of states for dropdown             |
| `cities`    | `{name: string}[]`                                 | ❌        | List of cities for dropdown             |

## Pass custom countries, states and cities

You can provide custom countries, states, and cities by passing them as arrays of objects in the following format:

```tsx
<PaymentDetailsTwo
  onSubmit={handleSubmit}
  onDiscard={handleDiscard}
  countries={[
  { name: "India", isoCode: "IN" },
  { name: "United States", isoCode: "US" },
  { name: "United Kingdom", isoCode: "GB" },
  { name: "Canada", isoCode: "CA" },
  { name: "Australia", isoCode: "AU" },
  ]}
  states={[
    { name: "Bihar", isoCode: "BR" },
    { name: "Karnataka", isoCode: "KA" },
    { name: "Maharashtra", isoCode: "MH" },
  ]}
  cities={[
    { name: "Patna", },
    { name: "Bangalore",},
    { name: "Mumbai",},
  ]}
/>
```

**Important**: If you choose to override with custom data, you must provide all three props (countries, states, and cities) together to ensure the dropdowns work correctly. If not provided, the component will fall back to the default data from country-state-city.

## PaymentFormData Interface

The form data structure for the PaymentDetails component:

```ts
interface PaymentFormData {
  nameOnCard?: string;
  cardNumber?: string;
  validTill?: string;
  cvv?: string;
  firstName?: string;
  middleLastName?: string;
  country?: string;
  state?: string;
  city?: string;
  billingAddress?: string;
  pinCode?: string;
  contactNumber?: string;
  general? : string

}
```

## Features

The PaymentDetails component comes with a comprehensive set of features:

### Core Functionality

* **Card Type Detection**: Automatically detects and displays card type (Visa, Mastercard, Amex, RuPay, Diners)
* **Input Formatting**: Automatically formats card numbers, expiry dates, and other fields
* **Validation**: Built-in form validation with error messages
* **Country Selection**: Dropdown for country selection with customizable options

### Design & UX

* **Responsive Design**: Mobile-friendly layout with responsive grid
* **Dark Mode Support**: Full dark mode compatibility with theme-aware styling
* **Hover Animations**: Smooth hover effects and transitions for better UX
* **Accessibility**: Proper labels, ARIA attributes, and keyboard navigation

### Customization

* **Customizable**: Extensive props for customization and theming
* **Confirmation Modal**: Optional success confirmation with customizable messages

## Supported Card Types

The component automatically detects and displays the appropriate card type:

| Card Type            | Pattern                     | Description                     |
| -------------------- | --------------------------- | ------------------------------- |
| **Visa**             | Starting with 4             | Most common international card  |
| **Mastercard**       | Starting with 5 or 2        | Global payment network          |
| **American Express** | Starting with 34 or 37      | Premium card with unique format |
| **RuPay**            | Starting with 6             | Indian domestic payment system  |
| **Diners Club**      | Starting with 30, 36, or 38 | International charge card       |

## Validation Rules

The component includes comprehensive client-side validation:

### Field Requirements

* **Card Number**: Maximum 16 digits
* **Expiry Date**: MM/YY format (e.g., 12/25)
* **CVV**: 3-4 digits depending on card type
* **PIN Code**: Exactly 6 digits
* **Contact Number**: Exactly 10 digits

### Required vs Optional Fields

* **Required**: All fields except country, state, and city
* **Optional**: Country, state, and city selections

## Theming & Customization

The PaymentDetails component supports comprehensive theming and customization options.

### Dark Mode Support

The component automatically adapts to dark mode using theme-aware CSS classes:

* **Background**: Uses `bg-background` and `bg-card` for proper dark mode support
* **Text Colors**: Uses `text-foreground` and `text-muted-foreground` for theme-aware text
* **Borders**: Uses `border-border` for consistent theming
* **Focus States**: Uses `focus:ring-ring` for theme-aware focus indicators
* **Error States**: Uses `text-destructive` and `border-destructive` for consistent error styling

### Theme Integration

The component integrates seamlessly with the BillingSDK theme system:

```tsx
import { useTheme } from '@/contexts/theme-context'
import { getThemeStyles } from '@/lib/themes'

// The component automatically applies theme styles
<PaymentDetails 
  // Theme styles are applied automatically
  // ... other props
/>
```

### Custom Styling

You can customize the appearance by passing custom className:

```tsx
<PaymentDetails 
  className="max-w-2xl mx-auto" 
  // ... other props
/>
```

## Example Implementation

Here's a complete example of how to implement the PaymentDetails component:

```tsx title="src/components/payment-details-two-demo.tsx"
"use client";

import {
  PaymentDetailsTwo,
  type PaymentFormData,
} from "@/components/billingsdk/payment-details-two";

export function PaymentDetailsTwoDemo() {
  //Function that handles onSubmit in the Form
  const handleSubmit = async (_data: PaymentFormData) => {
    // _data contains all the form values entered by the user:
    // e.g., _data.cardNumber, _data.nameOnCard, _data.validTill, _data.cvv, _data.firstName, etc.
    // You can use this object to make an API call to your backend, for example:
    // await fetch('/api/payment', { method: 'POST', body: JSON.stringify(_data) })

    return await new Promise((resolve) => {
      setTimeout(() => {
        console.log("Handle Submit Function");
        resolve("The promise is resolved");
      }, 3000);
    });
  };

  //Function that handles onCancel in the Form
  const handleDiscard = () => {
    console.log("The Discard Function");
  };

  return (
    <PaymentDetailsTwo onSubmit={handleSubmit} onDiscard={handleDiscard} />
  );
}

```


# Payment Failure
URL: /docs/components/payment-failure

A payment failure card that explains why a payment could not be processed, with actions to retry, go home, or contact support.

***

title: Payment Failure
description: A payment failure card that explains why a payment could not be processed, with actions to retry, go home, or contact support.
-------------------------------------------------------------------------------------------------------------------------------------------

<Tabs items={['Preview', 'Code']} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="payment-failure">
      <PaymentFailureDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/payment-failure-demo.tsx"
    "use client";

    import React, { useState } from "react";
    import { useRouter } from "next/navigation";
    import { PaymentFailure } from "@/registry/billingsdk/payment-failure";

    export function PaymentFailureDemo() {
      const [isRetrying, setIsRetrying] = useState(false);
      const router = useRouter();

      const handleRetry = async () => {
        setIsRetrying(true);

        try {
          // TODO: your actual retry logic (redirect to payment, call API, etc.)
          await new Promise((resolve) => setTimeout(resolve, 1500));
          // e.g. router.push("/checkout");
        } finally {
          setIsRetrying(false);
        }
      };

      return (
        <div className="bg-background flex min-h-screen items-center justify-center p-4">
          <PaymentFailure
            isRetrying={isRetrying}
            onRetry={handleRetry}
            onSecondary={() => router.push("/")}
            onTertiary={() => router.push("/support")}
            reasons={[
              "Insufficient funds in your account",
              "Incorrect card details or expired card",
              "Card declined by your bank",
              "Network connection issues",
            ]}
            // Optional overrides:
            // title="Payment declined"
            // subtitle="Your bank declined the transaction."
            // retryButtonText="Retry Payment"
            // secondaryButtonText="Go Home"
            // tertiaryButtonText="Contact Support"
          />
        </div>
      );
    }

    ```
  </Tab>
</Tabs>

## Installation

<Tabs items={["shadcn", "billingSDK"]} defaultValue="shadcn" className="border-none bg-transparent">
  <Tab value="shadcn" className="mt-3 border-none bg-transparent p-0">
    <Tabs items={["npx", "pnpm", "yarn", "bun"]} defaultValue="npx" groupId="installation-tabs">
      <Tab value="npx">
        `bash npx shadcn@latest add @billingsdk/payment-failure `
      </Tab>

      <Tab value="pnpm">
        `bash pnpm dlx shadcn@latest add @billingsdk/payment-failure `
      </Tab>

      <Tab value="yarn">
        `bash yarn dlx shadcn@latest add @billingsdk/payment-failure `
      </Tab>

      <Tab value="bun">
        `bash bunx shadcn@latest add @billingsdk/payment-failure `
      </Tab>
    </Tabs>
  </Tab>

  <Tab value="billingSDK" className="mt-3 border-none bg-transparent p-0">
    <Tabs items={["npx", "pnpm", "yarn", "bun"]} defaultValue="npx" groupId="billingsdk-cli-tabs">
      <Tab value="npx">`bash npx @billingsdk/cli add payment-failure `</Tab>

      <Tab value="pnpm">
        `bash pnpm dlx @billingsdk/cli add payment-failure `
      </Tab>

      <Tab value="yarn">
        `bash yarn dlx @billingsdk/cli add payment-failure `
      </Tab>

      <Tab value="bun">
        `bash bunx @billingsdk/cli add payment-failure `
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## Usage

```tsx
import { PaymentFailure } from "@/components/billingsdk/payment-failure";
```

```tsx
// Controlled usage (recommended)
const [isRetrying, setIsRetrying] = useState(false);

async function handleRetry() {
  setIsRetrying(true);

  // Add your retry logic here (e.g., redirect to checkout or re-initiate payment)
  await new Promise((resolve) => setTimeout(resolve, 1500));

  setIsRetrying(false);
}

<PaymentFailure
  isRetrying={isRetrying}
  onRetry={handleRetry}
  onSecondary={() => router.push("/")}
  onTertiary={() => router.push("/support")}
/>;
```

## Customizing text

```tsx
<PaymentFailure
  title="Transaction Declined"
  subtitle="Your bank rejected the payment."
  message="Please try again or use a different payment method."
  retryButtonText="Retry Payment"
  secondaryButtonText="Go Home"
  tertiaryButtonText="Contact Support"
  onRetry={() => console.log("retry")}
  onSecondary={() => router.push("/")}
  onTertiary={() => router.push("/support")}
/>
```

## Props

| Prop                  | Type         | Required | Description                                                                  |
| --------------------- | ------------ | -------- | ---------------------------------------------------------------------------- |
| `title`               | `string`     | ❌        | Optional heading (default: `"Payment Failed"`)                               |
| `subtitle`            | `string`     | ❌        | Optional subtext (default: `"We couldn't process your payment."`)            |
| `message`             | `string`     | ❌        | Additional explanatory message displayed under the reasons list              |
| `reasons`             | `string[]`   | ❌        | List of possible failure reasons (defaults to common payment failure causes) |
| `isRetrying`          | `boolean`    | ❌        | Shows loading state and disables retry button                                |
| `retryButtonText`     | `string`     | ❌        | Primary action label (default: `"Try Again"`)                                |
| `secondaryButtonText` | `string`     | ❌        | Secondary button label (default: `"Home"`)                                   |
| `tertiaryButtonText`  | `string`     | ❌        | Tertiary button label (default: `"Support"`)                                 |
| `onRetry`             | `() => void` | ❌        | Callback fired when user presses retry                                       |
| `onSecondary`         | `() => void` | ❌        | Callback fired when user presses the secondary action                        |
| `onTertiary`          | `() => void` | ❌        | Callback fired when user presses tertiary action                             |
| `className`           | `string`     | ❌        | Additional classes for styling / layout                                      |

## Theming

This dialog inherits BillingSDK theme tokens via `getThemeStyles`, remaining consistent with other components. Colors adapt to light/dark modes and active theme.

## Example

```tsx title="src/components/payment-failure-demo.tsx"
"use client";

import React, { useState } from "react";
import { useRouter } from "next/navigation";
import { PaymentFailure } from "@/registry/billingsdk/payment-failure";

export function PaymentFailureDemo() {
  const [isRetrying, setIsRetrying] = useState(false);
  const router = useRouter();

  const handleRetry = async () => {
    setIsRetrying(true);

    try {
      // TODO: your actual retry logic (redirect to payment, call API, etc.)
      await new Promise((resolve) => setTimeout(resolve, 1500));
      // e.g. router.push("/checkout");
    } finally {
      setIsRetrying(false);
    }
  };

  return (
    <div className="bg-background flex min-h-screen items-center justify-center p-4">
      <PaymentFailure
        isRetrying={isRetrying}
        onRetry={handleRetry}
        onSecondary={() => router.push("/")}
        onTertiary={() => router.push("/support")}
        reasons={[
          "Insufficient funds in your account",
          "Incorrect card details or expired card",
          "Card declined by your bank",
          "Network connection issues",
        ]}
        // Optional overrides:
        // title="Payment declined"
        // subtitle="Your bank declined the transaction."
        // retryButtonText="Retry Payment"
        // secondaryButtonText="Go Home"
        // tertiaryButtonText="Contact Support"
      />
    </div>
  );
}

```


# Payment Method Selector
URL: /docs/components/payment-method-selector

Interactive selector for Cards, Digital Wallets, UPI (India), and BNPL services with inline forms and smooth motion.

***

title: Payment Method Selector
description: Interactive selector for Cards, Digital Wallets, UPI (India), and BNPL services with inline forms and smooth motion.
---------------------------------------------------------------------------------------------------------------------------------

## Preview

<Tabs items={['Preview', 'Code']} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="payment-method-selector">
      <PaymentMethodSelectorDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/payment-method-selector-demo.tsx"
    "use client";

    import { PaymentMethodSelector } from "@/components/billingsdk/payment-method-selector";

    export function PaymentMethodSelectorDemo() {
      return (
        <div className="mx-auto flex min-h-[600px] w-full max-w-md items-center justify-center">
          <PaymentMethodSelector
            onProceed={(method, data) => {
              console.log("Demo: Proceed with:", method, data);
            }}
          />
        </div>
      );
    }

    ```
  </Tab>
</Tabs>

## Installation

<Tabs items={['shadcn', 'billingSDK']} defaultValue="shadcn" className="bg-transparent border-none">
  <Tab value="shadcn" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="installation-tabs">
      <Tab value="npx">
        ```bash
        npx shadcn@latest add @billingsdk/payment-method-selector
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @billingsdk/payment-method-selector
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @billingsdk/payment-method-selector
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx shadcn@latest add @billingsdk/payment-method-selector
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab value="billingSDK" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="billingsdk-cli-tabs">
      <Tab value="npx">
        ```bash
        npx @billingsdk/cli add payment-method-selector
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx @billingsdk/cli add payment-method-selector
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx @billingsdk/cli add payment-method-selector
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx @billingsdk/cli add payment-method-selector
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## Usage

```tsx
import { PaymentMethodSelector } from "@/components/billingsdk/payment-method-selector"
```

```tsx
<PaymentMethodSelector
  onProceed={(method, data) => {
    console.log("Selected method:", method)
    console.log("Form data:", data)
  }}
/>
```

## Props

| Prop        | Type                                              | Description                                                                        |
| ----------- | ------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `onProceed` | `(method: PaymentMethod, data: FormData) => void` | Fired on “Proceed with Payment”. Receives selected method and collected form data. |
| `className` | `string`                                          | Optional class names for the root container.                                       |

### Types

```ts
type PaymentMethod = "cards" | "digital-wallets" | "upi" | "bnpl-services"

type FormData = {
  // Cards
  cardNumber?: string
  expiryDate?: string
  cvv?: string
  cardholderName?: string
  // Wallets
  email?: string
  phone?: string
  // UPI
  upiId?: string
  // BNPL
  income?: string
}
```

## Payment Methods

* **Cards**
  * Form: card number, expiry, CVV, name
  * Notes: secure card payments with fraud protection
* **Digital Wallets** (Apple Pay, Google Pay, Cash App, Venmo)
  * Form: email, phone
  * Notes: quick checkout, biometric auth
* **UPI (India)** (PhonePe, Google Pay, Paytm, BHIM)
  * Form: UPI ID
  * Notes: real‑time bank transfers
* **BNPL Services** (Klarna, Affirm, Afterpay, Sezzle)
  * Form: email, phone, income (optional)
  * Notes: split payments, flexible terms

## Theming

Styled with `shadcn/ui`. Customize via CSS variables or switch themes in the preview header. See [Theming](/docs/theming).

## Example

```tsx title="src/components/payment-method-selector-demo.tsx"
"use client";

import { PaymentMethodSelector } from "@/components/billingsdk/payment-method-selector";

export function PaymentMethodSelectorDemo() {
  return (
    <div className="mx-auto flex min-h-[600px] w-full max-w-md items-center justify-center">
      <PaymentMethodSelector
        onProceed={(method, data) => {
          console.log("Demo: Proceed with:", method, data);
        }}
      />
    </div>
  );
}

```

### Credits

* Created by [@rajoninternet](https://x.com/rajoninternet)


# Payment Success Dialog
URL: /docs/components/payment-success-dialog

A confirmation dialog that celebrates a successful payment with the paid amount and product name, plus actions to proceed or go back.

***

title: Payment Success Dialog
description: A confirmation dialog that celebrates a successful payment with the paid amount and product name, plus actions to proceed or go back.
--------------------------------------------------------------------------------------------------------------------------------------------------

<Tabs items={['Preview', 'Code']} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="payment-success-dialog">
      <PaymentSuccessDialogDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/payment-success-dialog-demo.tsx"
    "use client";

    import { useState } from "react";
    import { PaymentSuccessDialog } from "@/components/billingsdk/payment-success-dialog";
    import { Card, CardContent } from "@/components/ui/card";

    export function PaymentSuccessDialogDemo() {
      const [, setLastAction] = useState<string>("");
      const [open, setOpen] = useState(false);

      return (
        <Card className="border-muted/40">
          <CardContent className="flex flex-col gap-4 p-6">
            <div className="text-muted-foreground text-sm">
              Click the button to preview the success dialog.
            </div>
            <button
              className="rounded-md border px-3 py-2 text-sm"
              onClick={() => setOpen(true)}
            >
              Simulate Payment Success
            </button>
            <PaymentSuccessDialog
              open={open}
              onOpenChange={setOpen}
              price="99"
              currencySymbol="$"
              productName="Pro Plan (Monthly)"
              proceedButtonText="Go to Dashboard"
              backButtonText="Back to Pricing"
              onProceed={() => setLastAction("proceed")}
              onBack={() => setLastAction("back")}
            />
          </CardContent>
        </Card>
      );
    }

    ```
  </Tab>
</Tabs>

## Installation

<Tabs items={['shadcn', 'billingSDK']} defaultValue="shadcn" className="bg-transparent border-none">
  <Tab value="shadcn" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="installation-tabs">
      <Tab value="npx">
        ```bash
        npx shadcn@latest add @billingsdk/payment-success-dialog
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @billingsdk/payment-success-dialog
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @billingsdk/payment-success-dialog
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx shadcn@latest add @billingsdk/payment-success-dialog
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab value="billingSDK" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="billingsdk-cli-tabs">
      <Tab value="npx">
        ```bash
        npx @billingsdk/cli add payment-success-dialog
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx @billingsdk/cli add payment-success-dialog
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx @billingsdk/cli add payment-success-dialog
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx @billingsdk/cli add payment-success-dialog
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## Usage

```tsx
import { PaymentSuccessDialog, type PaymentSuccessDialogRef } from "@/components/billingsdk/payment-success-dialog";
```

```tsx
// Controlled usage (recommended)
const [open, setOpen] = useState(false);

// Show on demand, e.g. after successful payment
setOpen(true);

<PaymentSuccessDialog
  open={open}
  onOpenChange={setOpen}
  price="29"
  currencySymbol="$"
  productName="Pro Plan (Monthly)"
  proceedButtonText="Go to Dashboard"
  backButtonText="Back to Pricing"
/>
```

```tsx
// Imperative ref (optional)
const ref = useRef<PaymentSuccessDialogRef>(null);
ref.current?.open();
```

## Props

| Prop                | Type                      | Required | Description                                                |
| ------------------- | ------------------------- | -------- | ---------------------------------------------------------- |
| `title`             | `string`                  | ❌        | Optional heading (default: "Congratulations!")             |
| `subtitle`          | `string`                  | ❌        | Optional subtext (default: "Your payment was successful.") |
| `currencySymbol`    | `string`                  | ❌        | Currency symbol prefix (default: `$`)                      |
| `price`             | `string`                  | ✅        | Amount paid                                                |
| `productName`       | `string`                  | ✅        | Product Name                                               |
| `proceedButtonText` | `string`                  | ❌        | Primary action label                                       |
| `backButtonText`    | `string`                  | ❌        | Secondary action label                                     |
| `onProceed`         | `() => void`              | ❌        | Callback for proceed action                                |
| `onBack`            | `() => void`              | ❌        | Callback for back action                                   |
| `className`         | `string`                  | ❌        | Additional class names                                     |
| `open`              | `boolean`                 | ❌        | Controlled open state                                      |
| `onOpenChange`      | `(open: boolean) => void` | ❌        | Controlled state handler                                   |

## Theming

This dialog inherits BillingSDK theme tokens via `getThemeStyles`, remaining consistent with other components. Colors adapt to light/dark modes and active theme.

## Example

```tsx title="src/components/payment-success-dialog-demo.tsx"
"use client";

import { useState } from "react";
import { PaymentSuccessDialog } from "@/components/billingsdk/payment-success-dialog";
import { Card, CardContent } from "@/components/ui/card";

export function PaymentSuccessDialogDemo() {
  const [, setLastAction] = useState<string>("");
  const [open, setOpen] = useState(false);

  return (
    <Card className="border-muted/40">
      <CardContent className="flex flex-col gap-4 p-6">
        <div className="text-muted-foreground text-sm">
          Click the button to preview the success dialog.
        </div>
        <button
          className="rounded-md border px-3 py-2 text-sm"
          onClick={() => setOpen(true)}
        >
          Simulate Payment Success
        </button>
        <PaymentSuccessDialog
          open={open}
          onOpenChange={setOpen}
          price="99"
          currencySymbol="$"
          productName="Pro Plan (Monthly)"
          proceedButtonText="Go to Dashboard"
          backButtonText="Back to Pricing"
          onProceed={() => setLastAction("proceed")}
          onBack={() => setLastAction("back")}
        />
      </CardContent>
    </Card>
  );
}

```

### Credits

* Created by [@ritiksahni22](https://github.com/ritiksahni)


# Pricing Table Eight
URL: /docs/components/pricing-table/pricing-table-eight

A pricing table component with hover-to-reveal pricing and features.

***

title: Pricing Table Eight
description: A pricing table component with hover-to-reveal pricing and features.
---------------------------------------------------------------------------------

## Preview

<Tabs items={['Preview', 'Code']} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents>
      <PricingTableEightDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/registry/billingsdk/demo/pricing-table-eight-demo.tsx"
    "use client";

    import { PricingTableEight } from "@/components/billingsdk/pricing-table-eight";
    import { plans as basePlans } from "@/lib/billingsdk-config";

    const plans = basePlans.map((plan) => {
      if (plan.id === "starter") {
        return { ...plan, description: "Do you just want to start testing?" };
      }
      if (plan.id === "pro") {
        return {
          ...plan,
          description: "Do you want to unlock full production features?",
        };
      }
      if (plan.id === "enterprise") {
        return {
          ...plan,
          description: "Do you want dedicated security and scale?",
        };
      }
      return plan;
    });
    export function PricingTableEightDemo() {
      return (
        <PricingTableEight
          plans={plans}
          title="Choose Your Perfect Plan"
          theme="classic"
          description="Transform your project with our comprehensive pricing options designed for every need."
          subtitle="Simple Pricing"
          onPlanSelect={(planId: string) => console.log("Selected plan:", planId)}
          size="medium"
          className="w-full"
          showBillingToggle={true}
          billingToggleLabels={{
            monthly: "Monthly",
            yearly: "Yearly",
          }}
        />
      );
    }

    ```
  </Tab>
</Tabs>

## Installation

<Tabs items={['shadcn', 'billingSDK']} defaultValue="shadcn" className="bg-transparent border-none">
  <Tab value="shadcn" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="installation-tabs">
      <Tab value="npx">
        ```bash
        npx shadcn@latest add @billingsdk/pricing-table-eight
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @billingsdk/pricing-table-eight
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @billingsdk/pricing-table-eight
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx shadcn@latest add @billingsdk/pricing-table-eight
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab value="billingSDK" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="billingsdk-cli-tabs">
      <Tab value="npx">
        ```bash
        npx @billingsdk/cli add pricing-table-eight
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx @billingsdk/cli add pricing-table-eight
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx @billingsdk/cli add pricing-table-eight
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx @billingsdk/cli add pricing-table-eight
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## Usage

```tsx
import { PricingTableEight } from "@/components/billingsdk/pricing-table-eight"
import { plans as basePlans} from "@/lib/billingsdk-config"

const plans = basePlans.map(plan => {
  if (plan.id === 'starter') {
    return { ...plan, description: 'Do you just want to start testing?' };
  }
  if (plan.id === 'pro') {
    return { ...plan, description: 'Do you want to unlock full production features?' };
  }
  if (plan.id === 'enterprise') {
    return { ...plan, description: 'Do you want dedicated security and scale?' };
  }
  return plan;
});
export function PricingTableEightDemo() {
  return (
    <PricingTableEight
      plans={plans}
      title="Choose Your Perfect Plan"
      theme="classic"
      description="Transform your project with our comprehensive pricing options designed for every need."
      subtitle="Simple Pricing"
      onPlanSelect={(planId: string) => console.log('Selected plan:', planId)}
      size="medium"
      className="w-full"
      showBillingToggle={true}
      billingToggleLabels={{
        monthly: "Monthly",
        yearly: "Yearly",
      }}
    />
  )
}
```

## Props

| Prop                  | Type                                  | Description                                                                    |
| --------------------- | ------------------------------------- | ------------------------------------------------------------------------------ |
| `plans`               | `Plan[]`                              | Array of pricing plans (see [Plan interface](/docs/interfaces#plan-interface)) |
| `title`               | `string`                              | Main title for the pricing section                                             |
| `description`         | `string`                              | Subtitle description                                                           |
| `subtitle`            | `string`                              | Optional small subtitle above title                                            |
| `onPlanSelect`        | `(planId: string) => void`            | Callback when a plan is selected                                               |
| `showBillingToggle`   | `boolean`                             | Show monthly/yearly billing toggle (default: true)                             |
| `billingToggleLabels` | `{ monthly: string; yearly: string }` | Custom labels for billing toggle                                               |
| `size`                | `"small" \| "medium" \| "large"`      | Component size variant                                                         |
| `theme`               | `"minimal" \| "classic"`              | Theme variant of the pricing table                                             |
| `className`           | `string`                              | Additional CSS classes                                                         |

## Features

* **Hover-to-Reveal Design**: Prices and features elegantly reveal on hover for a clean, minimal initial state
* **Mobile-Optimized**: Shows full content by default on mobile, hover-reveal only on desktop
* **Dual Theme Support**: Choose between minimal and classic themes with distinct visual styles
* **Billing Toggle**: Monthly/yearly pricing with automatic discount calculation
* **Plan Highlights**: Mark popular plans with badges and special styling
* **Smooth Animations**: Framer Motion animations for price transitions and feature list reveals
* **Responsive Layout**: Adapts seamlessly from mobile to large screens
* **Accessibility**: Comprehensive ARIA labels for screen readers
* **Plan Icons**: Automatic or custom icons for different plan types

## Theming

The pricing table component is styled using the `shadcn/ui` library. You can customize the colors and fonts by overriding the CSS variables. You can also get the theme from the [Theming](/docs/theming) page.

## Example

```tsx title="src/registry/billingsdk/demo/pricing-table-eight-demo.tsx"
"use client";

import { PricingTableEight } from "@/components/billingsdk/pricing-table-eight";
import { plans as basePlans } from "@/lib/billingsdk-config";

const plans = basePlans.map((plan) => {
  if (plan.id === "starter") {
    return { ...plan, description: "Do you just want to start testing?" };
  }
  if (plan.id === "pro") {
    return {
      ...plan,
      description: "Do you want to unlock full production features?",
    };
  }
  if (plan.id === "enterprise") {
    return {
      ...plan,
      description: "Do you want dedicated security and scale?",
    };
  }
  return plan;
});
export function PricingTableEightDemo() {
  return (
    <PricingTableEight
      plans={plans}
      title="Choose Your Perfect Plan"
      theme="classic"
      description="Transform your project with our comprehensive pricing options designed for every need."
      subtitle="Simple Pricing"
      onPlanSelect={(planId: string) => console.log("Selected plan:", planId)}
      size="medium"
      className="w-full"
      showBillingToggle={true}
      billingToggleLabels={{
        monthly: "Monthly",
        yearly: "Yearly",
      }}
    />
  );
}

```


# Pricing Table Five
URL: /docs/components/pricing-table/pricing-table-five

The Pricing Table Five component provides a horizontal layout design for pricing displays. Features a 2-column layout with regular plans on the left and a contact card on the right, perfect for showcasing enterprise options.

***

title: Pricing Table Five
description: The Pricing Table Five component provides a horizontal layout design for pricing displays. Features a 2-column layout with regular plans on the left and a contact card on the right, perfect for showcasing enterprise options.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

## Classic Theme

<Tabs items={['Preview', 'Code']} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="pricing-table-five">
      <PricingTableFiveDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/pricing-table-five-demo.tsx"
    "use client";

    import { PricingTableFive } from "@/components/billingsdk/pricing-table-five";
    import { plans } from "@/lib/billingsdk-config";

    export function PricingTableFiveDemo() {
      return (
        <PricingTableFive
          plans={plans}
          theme="classic"
          onPlanSelect={(planId: string) => console.log("Selected plan:", planId)}
          title="Budget-friendly pricing alternatives"
          description="Get started free or upgrade to share your impact for all completed tasks with multiple people"
        />
      );
    }

    ```
  </Tab>
</Tabs>

## Minimal Theme

<Tabs items={['Preview', 'Code']} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="pricing-table-five">
      <PricingTableFiveMinimalDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/pricing-table-five-minimal-demo.tsx"
    "use client";

    import { PricingTableFive } from "@/components/billingsdk/pricing-table-five";
    import { plans } from "@/lib/billingsdk-config";

    export function PricingTableFiveMinimalDemo() {
      return (
        <PricingTableFive
          plans={plans}
          theme="minimal"
          onPlanSelect={(planId: string) => console.log("Selected plan:", planId)}
          title="Budget-friendly pricing alternatives"
          description="Get started free or upgrade to share your impact for all completed tasks with multiple people"
        />
      );
    }

    ```
  </Tab>
</Tabs>

## Installation

<Tabs items={['shadcn', 'billingSDK']} defaultValue="shadcn" className="bg-transparent border-none">
  <Tab value="shadcn" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="installation-tabs">
      <Tab value="npx">
        ```bash
        npx shadcn@latest add @billingsdk/pricing-table-five
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @billingsdk/pricing-table-five
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @billingsdk/pricing-table-five
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx shadcn@latest add @billingsdk/pricing-table-five
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab value="billingSDK" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="billingsdk-cli-tabs">
      <Tab value="npx">
        ```bash
        npx @billingsdk/cli add pricing-table-five
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx @billingsdk/cli add pricing-table-five
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx @billingsdk/cli add pricing-table-five
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx @billingsdk/cli add pricing-table-five
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## Usage

```tsx
import { PricingTableFive } from "@/components/billingsdk/pricing-table-five";
import { plans } from "@/lib/billingsdk-config";
```

```tsx
<PricingTableFive 
  plans={plans}
  title="Budget-friendly pricing alternatives"
  description="Get started free or upgrade to share your impact for all completed tasks with multiple people"
  onPlanSelect={(planId) => console.log('Selected plan:', planId)}
  size="medium" // small, medium, large
  theme="classic" // minimal or classic
/>
```

## Props

| Prop           | Type                              | Description                                                                    |
| -------------- | --------------------------------- | ------------------------------------------------------------------------------ |
| `plans`        | `Plan[]`                          | Array of pricing plans (see [Plan interface](/docs/interfaces#plan-interface)) |
| `title`        | `string`                          | Main title for the pricing section                                             |
| `description`  | `string`                          | Subtitle description                                                           |
| `onPlanSelect` | `(planId: string) => void`        | Callback when a plan is selected                                               |
| `size`         | `"small" \| "medium" \|  "large"` | Size variant of the pricing table                                              |
| `theme`        | `"minimal" \| "classic"`          | Theme variant of the pricing table                                             |

## Features

* **Dual Theme Support**: Choose between minimal and classic themes
* **Horizontal Layout**: Regular plans displayed horizontally with features in a grid
* **Contact Card**: Dedicated section for enterprise/custom plans
* **Responsive Layout**: Adapts beautifully from desktop to mobile
* **Billing Toggle**: Monthly/yearly billing toggle with discount display
* **Highlight Support**: Special styling for featured/popular plans with badges
* **Customizable Sizing**: Small, medium, and large size variants
* **Smooth Animations**: Animated price transitions and feature list reveals

## Theming

The pricing table component is styled using the `shadcn/ui` library. You can customize the colors and fonts by overriding the CSS variables. You can also get the theme from the [Theming](/docs/theming) page.

## Example

```tsx title="src/components/pricing-table-five-demo.tsx"
"use client";

import { PricingTableFive } from "@/components/billingsdk/pricing-table-five";
import { plans } from "@/lib/billingsdk-config";

export function PricingTableFiveDemo() {
  return (
    <PricingTableFive
      plans={plans}
      theme="classic"
      onPlanSelect={(planId: string) => console.log("Selected plan:", planId)}
      title="Budget-friendly pricing alternatives"
      description="Get started free or upgrade to share your impact for all completed tasks with multiple people"
    />
  );
}

```


# Pricing Table Four
URL: /docs/components/pricing-table/pricing-table-four

The Pricing Table Four component provides a modern icon-based design for displaying pricing plans. This component features clean layouts, smooth animations, and support for both minimal and classic themes.

***

title: Pricing Table Four
description: The Pricing Table Four component provides a modern icon-based design for displaying pricing plans. This component features clean layouts, smooth animations, and support for both minimal and classic themes.
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

## Classic Theme

<Tabs items={['Preview', 'Code']} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="pricing-table-four">
      <PricingTableFourDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/pricing-table-four-demo.tsx"
    "use client";

    import { PricingTableFour } from "@/components/billingsdk/pricing-table-four";
    import { plans } from "@/lib/billingsdk-config";

    export function PricingTableFourDemo() {
      return (
        <PricingTableFour
          plans={plans}
          title="Choose Your Perfect Plan"
          theme="classic"
          description="Transform your project with our comprehensive pricing options designed for every need."
          subtitle="Simple Pricing"
          onPlanSelect={(planId: string) => console.log("Selected plan:", planId)}
          size="medium"
          className="w-full"
          showBillingToggle={true}
          billingToggleLabels={{
            monthly: "Monthly",
            yearly: "Yearly",
          }}
        />
      );
    }

    ```
  </Tab>
</Tabs>

## Minimal Theme

<Tabs items={['Preview', 'Code']} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="pricing-table-four">
      <PricingTableFourMinimalDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/pricing-table-four-minimal-demo.tsx"
    "use client";

    import { PricingTableFour } from "@/components/billingsdk/pricing-table-four";
    import { plans } from "@/lib/billingsdk-config";

    export function PricingTableFourMinimalDemo() {
      return (
        <PricingTableFour
          plans={plans}
          title="Choose Your Perfect Plan"
          theme="minimal"
          description="Transform your project with our comprehensive pricing options designed for every need."
          subtitle="Simple Pricing"
          onPlanSelect={(planId: string) => console.log("Selected plan:", planId)}
          size="medium"
          className="w-full"
          showBillingToggle={true}
          billingToggleLabels={{
            monthly: "Monthly",
            yearly: "Yearly",
          }}
        />
      );
    }

    ```
  </Tab>
</Tabs>

## Installation

<Tabs items={['shadcn', 'billingSDK']} defaultValue="shadcn" className="bg-transparent border-none">
  <Tab value="shadcn" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="installation-tabs">
      <Tab value="npx">
        ```bash
        npx shadcn@latest add @billingsdk/pricing-table-four
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @billingsdk/pricing-table-four
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @billingsdk/pricing-table-four
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx shadcn@latest add @billingsdk/pricing-table-four
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab value="billingSDK" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="billingsdk-cli-tabs">
      <Tab value="npx">
        ```bash
        npx @billingsdk/cli add pricing-table-four
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx @billingsdk/cli add pricing-table-four
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx @billingsdk/cli add pricing-table-four
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx @billingsdk/cli add pricing-table-four
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## Usage

```tsx
import { PricingTableFour } from "@/components/billingsdk/pricing-table-four";
import { plans } from "@/lib/billingsdk-config";
```

```tsx
<PricingTableFour 
  plans={plans}
  title="Choose Your Perfect Plan"
  description="Transform your project with our comprehensive pricing options designed for every need."
  subtitle="Simple Pricing"
  onPlanSelect={(planId) => console.log('Selected plan:', planId)}
  size="medium" // small, medium, large
  theme="classic" // minimal or classic
/>
```

## Props

| Prop                  | Type                                  | Description                                                                    |
| --------------------- | ------------------------------------- | ------------------------------------------------------------------------------ |
| `plans`               | `Plan[]`                              | Array of pricing plans (see [Plan interface](/docs/interfaces#plan-interface)) |
| `title`               | `string`                              | Main title for the pricing section                                             |
| `description`         | `string`                              | Subtitle description                                                           |
| `subtitle`            | `string`                              | Optional subtitle text (displayed above title)                                 |
| `onPlanSelect`        | `(planId: string) => void`            | Callback when a plan is selected                                               |
| `size`                | `"small" \| "medium" \|  "large"`     | Size variant of the pricing table                                              |
| `theme`               | `"minimal" \| "classic"`              | Theme variant of the pricing table                                             |
| `showBillingToggle`   | `boolean`                             | Show/hide the monthly/yearly toggle (default: true)                            |
| `billingToggleLabels` | `{ monthly: string; yearly: string }` | Custom labels for billing toggle                                               |

## Features

* **Dual Theme Support**: Choose between minimal and classic themes
* **Icon-Based Design**: Each plan includes customizable icons for visual distinction
* **Responsive Layout**: Grid-based layout that adapts to different screen sizes
* **Interactive Elements**: Hover effects and smooth transitions
* **Billing Toggle**: Monthly/yearly billing toggle with discount display
* **Highlight Support**: Special styling for featured/popular plans with badges
* **Customizable Sizing**: Small, medium, and large size variants
* **Smooth Animations**: Animated price transitions and feature list reveals

## Theming

The pricing table component is styled using the `shadcn/ui` library. You can customize the colors and fonts by overriding the CSS variables. You can also get the theme from the [Theming](/docs/theming) page.

## Example

```tsx title="src/components/pricing-table-four-demo.tsx"
"use client";

import { PricingTableFour } from "@/components/billingsdk/pricing-table-four";
import { plans } from "@/lib/billingsdk-config";

export function PricingTableFourDemo() {
  return (
    <PricingTableFour
      plans={plans}
      title="Choose Your Perfect Plan"
      theme="classic"
      description="Transform your project with our comprehensive pricing options designed for every need."
      subtitle="Simple Pricing"
      onPlanSelect={(planId: string) => console.log("Selected plan:", planId)}
      size="medium"
      className="w-full"
      showBillingToggle={true}
      billingToggleLabels={{
        monthly: "Monthly",
        yearly: "Yearly",
      }}
    />
  );
}

```


# Pricing Table One
URL: /docs/components/pricing-table/pricing-table-one

The Pricing Table One component provides a clean and modern design for displaying pricing plans. You can use this component to display your pricing plans in a clean and modern way.

***

title: Pricing Table One
description: The Pricing Table One component provides a clean and modern design for displaying pricing plans. You can use this component to display your pricing plans in a clean and modern way.
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

## Classic Theme

<Tabs items={['Preview', 'Code']} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="pricing-table-one">
      <PricingTableOneDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/pricing-table-one-demo.tsx"
    "use client";

    import { PricingTableOne } from "@/components/billingsdk/pricing-table-one";
    import { plans } from "@/lib/billingsdk-config";

    export function PricingTableOneDemo() {
      return (
        <PricingTableOne
          plans={plans}
          title="Pricing"
          description="Choose the plan that's right for you"
          onPlanSelect={(planId) => console.log("Selected plan:", planId)}
          size="medium" // small, medium, large
          theme="classic" // minimal or classic
          className="w-full"
        />
      );
    }

    ```
  </Tab>
</Tabs>

## Minimal Theme

<Tabs items={['Preview', 'Code']} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="pricing-table-one">
      <PricingTableOneMinimalDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/pricing-table-one-minimal-demo.tsx"
    "use client";

    import { PricingTableOne } from "@/components/billingsdk/pricing-table-one";
    import { plans } from "@/lib/billingsdk-config";

    export function PricingTableOneMinimalDemo() {
      return (
        <>
          <PricingTableOne
            plans={plans}
            title="Pricing"
            description="Choose the plan that's right for you"
            onPlanSelect={(planId) => console.log("Selected plan:", planId)}
            size="small" // small, medium, large
            theme="minimal" // minimal or classic
            className="w-full"
          />
        </>
      );
    }

    ```
  </Tab>
</Tabs>

## Installation

<Tabs items={['shadcn', 'billingSDK']} defaultValue="shadcn" className="bg-transparent border-none">
  <Tab value="shadcn" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="installation-tabs">
      <Tab value="npx">
        ```bash
        npx shadcn@latest add @billingsdk/pricing-table-one
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @billingsdk/pricing-table-one
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @billingsdk/pricing-table-one
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx shadcn@latest add @billingsdk/pricing-table-one
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab value="billingSDK" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="billingsdk-cli-tabs">
      <Tab value="npx">
        ```bash
        npx @billingsdk/cli add pricing-table-one
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx @billingsdk/cli add pricing-table-one
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx @billingsdk/cli add pricing-table-one
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx @billingsdk/cli add pricing-table-one
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## Usage

```tsx
import { PricingTableOne } from "@/components/billingsdk/pricing-table-one";
import { plans } from "@/lib/billingsdk-config";
```

```tsx
<PricingTableOne 
  plans={plans}
  title="Pricing"
  description="Choose the plan that's right for you"
  onPlanSelect={(planId) => console.log('Selected plan:', planId)}
  size="small" // small, medium, large
  theme="classic" // minimal or classic
/>
```

## Props

| Prop           | Type                              | Description                                                                    |
| -------------- | --------------------------------- | ------------------------------------------------------------------------------ |
| `plans`        | `Plan[]`                          | Array of pricing plans (see [Plan interface](/docs/interfaces#plan-interface)) |
| `title`        | `string`                          | Main title for the pricing section                                             |
| `description`  | `string`                          | Subtitle description                                                           |
| `onPlanSelect` | `(planId: string) => void`        | Callback when a plan is selected                                               |
| `size`         | `"small" \| "medium" \|  "large"` | Size variant of the pricing table                                              |
| `theme`        | `"minimal" \| "classic"`          | Theme variant of the pricing table                                             |

## Theming

The pricing table component is styled using the `shadcn/ui` library. You can customize the colors and fonts by overriding the CSS variables. You can also get the theme from the [Theming](/docs/theming) page.

## Example

```tsx title="src/components/pricing-table-one-demo.tsx"
"use client";

import { PricingTableOne } from "@/components/billingsdk/pricing-table-one";
import { plans } from "@/lib/billingsdk-config";

export function PricingTableOneDemo() {
  return (
    <PricingTableOne
      plans={plans}
      title="Pricing"
      description="Choose the plan that's right for you"
      onPlanSelect={(planId) => console.log("Selected plan:", planId)}
      size="medium" // small, medium, large
      theme="classic" // minimal or classic
      className="w-full"
    />
  );
}

```


# Pricing Table Seven
URL: /docs/components/pricing-table/pricing-table-seven

The Pricing Table Seven component provides a feature-comparison pricing table with aligned cards and user slider for comprehensive plan comparison.

***

title: Pricing Table Seven
description: The Pricing Table Seven component provides a feature-comparison pricing table with aligned cards and user slider for comprehensive plan comparison.
----------------------------------------------------------------------------------------------------------------------------------------------------------------

## Classic Theme

<Tabs items={['Preview', 'Code']} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="pricing-table-seven">
      <PricingTableSevenDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/pricing-table-seven-demo.tsx"
    "use client";

    import { PricingTableSeven } from "@/components/billingsdk/pricing-table-seven";

    const plans = [
      {
        id: "basic",
        name: "Basic plan",
        description: "Our most popular plan.",
        price: 10,
        popular: false,
        users: 5,
      },
      {
        id: "business",
        name: "Business plan",
        description: "Best for growing teams.",
        price: 20,
        popular: true,
        users: 15,
      },
      {
        id: "enterprise",
        name: "Enterprise plan",
        description: "Best for large teams.",
        price: 40,
        popular: false,
        users: 25,
      },
    ];

    const features = [
      {
        category: "Overview",
        items: [
          {
            name: "Basic features",
            tooltip: true,
            basic: true,
            business: true,
            enterprise: true,
          },
          {
            name: "Users",
            tooltip: true,
            basic: "10",
            business: "20",
            enterprise: "Unlimited",
          },
          {
            name: "Individual data",
            tooltip: true,
            basic: "20GB",
            business: "40GB",
            enterprise: "Unlimited",
          },
          {
            name: "Support",
            tooltip: true,
            basic: true,
            business: true,
            enterprise: true,
          },
          {
            name: "Automated workflows",
            tooltip: true,
            basic: false,
            business: true,
            enterprise: true,
          },
          {
            name: "200+ integrations",
            tooltip: true,
            basic: false,
            business: true,
            enterprise: true,
          },
        ],
      },
      {
        category: "Reporting and analytics",
        items: [
          {
            name: "Analytics",
            tooltip: true,
            basic: "Basic",
            business: "Advanced",
            enterprise: "Advanced",
          },
          {
            name: "Export reports",
            tooltip: true,
            basic: true,
            business: true,
            enterprise: true,
          },
          {
            name: "Scheduled reports",
            tooltip: true,
            basic: true,
            business: true,
            enterprise: true,
          },
          {
            name: "API access",
            tooltip: true,
            basic: false,
            business: true,
            enterprise: true,
          },
          {
            name: "Advanced reports",
            tooltip: true,
            basic: false,
            business: true,
            enterprise: true,
          },
          {
            name: "Saved reports",
            tooltip: true,
            basic: false,
            business: true,
            enterprise: true,
          },
          {
            name: "Customer properties",
            tooltip: true,
            basic: false,
            business: false,
            enterprise: true,
          },
          {
            name: "Custom fields",
            tooltip: true,
            basic: false,
            business: false,
            enterprise: true,
          },
        ],
      },
      {
        category: "User access",
        items: [
          {
            name: "SSO/SAML authentication",
            tooltip: true,
            basic: true,
            business: true,
            enterprise: true,
          },
          {
            name: "Advanced permissions",
            tooltip: true,
            basic: false,
            business: true,
            enterprise: true,
          },
          {
            name: "Audit log",
            tooltip: true,
            basic: false,
            business: false,
            enterprise: true,
          },
          {
            name: "Data history",
            tooltip: true,
            basic: false,
            business: false,
            enterprise: true,
          },
        ],
      },
    ];

    export function PricingTableSevenDemo() {
      return (
        <PricingTableSeven
          plans={plans}
          features={features}
          title="Choose a plan that's right for you"
          description="We believe Untitled should be accessible to all companies, no matter the size of your startup."
          onPlanSelect={(planId: string) => console.log("Selected plan:", planId)}
          size="medium"
          theme="classic"
          className="w-full"
        />
      );
    }

    ```
  </Tab>
</Tabs>

## Minimal Theme

<Tabs items={['Preview', 'Code']} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="pricing-table-seven">
      <PricingTableSevenMinimalDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/pricing-table-seven-minimal-demo.tsx"
    "use client";

    import { PricingTableSeven } from "@/components/billingsdk/pricing-table-seven";

    const plans = [
      {
        id: "basic",
        name: "Basic plan",
        description: "Our most popular plan.",
        price: 10,
        popular: false,
        users: 5,
      },
      {
        id: "business",
        name: "Business plan",
        description: "Best for growing teams.",
        price: 20,
        popular: true,
        users: 15,
      },
      {
        id: "enterprise",
        name: "Enterprise plan",
        description: "Best for large teams.",
        price: 40,
        popular: false,
        users: 25,
      },
    ];

    const features = [
      {
        category: "Overview",
        items: [
          {
            name: "Basic features",
            tooltip: true,
            basic: true,
            business: true,
            enterprise: true,
          },
          {
            name: "Users",
            tooltip: true,
            basic: "10",
            business: "20",
            enterprise: "Unlimited",
          },
          {
            name: "Individual data",
            tooltip: true,
            basic: "20GB",
            business: "40GB",
            enterprise: "Unlimited",
          },
          {
            name: "Support",
            tooltip: true,
            basic: true,
            business: true,
            enterprise: true,
          },
          {
            name: "Automated workflows",
            tooltip: true,
            basic: false,
            business: true,
            enterprise: true,
          },
          {
            name: "200+ integrations",
            tooltip: true,
            basic: false,
            business: true,
            enterprise: true,
          },
        ],
      },
      {
        category: "Reporting and analytics",
        items: [
          {
            name: "Analytics",
            tooltip: true,
            basic: "Basic",
            business: "Advanced",
            enterprise: "Advanced",
          },
          {
            name: "Export reports",
            tooltip: true,
            basic: true,
            business: true,
            enterprise: true,
          },
          {
            name: "Scheduled reports",
            tooltip: true,
            basic: true,
            business: true,
            enterprise: true,
          },
          {
            name: "API access",
            tooltip: true,
            basic: false,
            business: true,
            enterprise: true,
          },
          {
            name: "Advanced reports",
            tooltip: true,
            basic: false,
            business: true,
            enterprise: true,
          },
          {
            name: "Saved reports",
            tooltip: true,
            basic: false,
            business: true,
            enterprise: true,
          },
          {
            name: "Customer properties",
            tooltip: true,
            basic: false,
            business: false,
            enterprise: true,
          },
          {
            name: "Custom fields",
            tooltip: true,
            basic: false,
            business: false,
            enterprise: true,
          },
        ],
      },
      {
        category: "User access",
        items: [
          {
            name: "SSO/SAML authentication",
            tooltip: true,
            basic: true,
            business: true,
            enterprise: true,
          },
          {
            name: "Advanced permissions",
            tooltip: true,
            basic: false,
            business: true,
            enterprise: true,
          },
          {
            name: "Audit log",
            tooltip: true,
            basic: false,
            business: false,
            enterprise: true,
          },
          {
            name: "Data history",
            tooltip: true,
            basic: false,
            business: false,
            enterprise: true,
          },
        ],
      },
    ];

    export function PricingTableSevenMinimalDemo() {
      return (
        <PricingTableSeven
          plans={plans}
          features={features}
          title="Choose a plan that's right for you"
          description="We believe Untitled should be accessible to all companies, no matter the size of your startup."
          onPlanSelect={(planId: string) => console.log("Selected plan:", planId)}
          size="medium"
          theme="minimal"
          className="w-full"
        />
      );
    }

    ```
  </Tab>
</Tabs>

## Installation

<Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="installation-tabs">
  <Tab value="npx">
    ```bash
    npx shadcn@latest add @billingsdk/pricing-table-seven
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm dlx shadcn@latest add @billingsdk/pricing-table-seven
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn dlx shadcn@latest add @billingsdk/pricing-table-seven
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bunx shadcn@latest add @billingsdk/pricing-table-seven
    ```
  </Tab>
</Tabs>

## Usage

```tsx
import { PricingTableSeven } from "@/components/billingsdk/pricing-table-seven";

const plans = [
  {
    id: "basic",
    name: "Basic plan",
    description: "Our most popular plan.",
    price: 10,
    popular: false,
    users: 5,
  },
  {
    id: "business",
    name: "Business plan",
    description: "Best for growing teams.",
    price: 20,
    popular: true,
    users: 15,
  },
  {
    id: "enterprise",
    name: "Enterprise plan",
    description: "Best for large teams.",
    price: 40,
    popular: false,
    users: 25,
  },
];

const features = [
  {
    category: "Overview",
    items: [
      {
        name: "Basic features",
        tooltip: true,
        basic: true,
        business: true,
        enterprise: true,
      },
      {
        name: "Users",
        tooltip: true,
        basic: "10",
        business: "20",
        enterprise: "Unlimited",
      },
    ],
  },
];
```

```tsx
<PricingTableSeven
  plans={plans}
  features={features}
  title="Choose a plan that's right for you"
  description="We believe Untitled should be accessible to all companies, no matter the size of your startup."
  onPlanSelect={(planId) => console.log('Selected plan:', planId)}
  size="medium" // small, medium, large
  theme="classic" // minimal or classic
/>
```

## Props

| Prop           | Type                             | Description                                                |
| -------------- | -------------------------------- | ---------------------------------------------------------- |
| `plans`        | `PricingTableSevenPlan[]`        | Array of pricing plans                                     |
| `features`     | `FeatureCategory[]`              | Array of feature categories with items                     |
| `title`        | `string`                         | Page title (default: "Choose a plan that's right for you") |
| `description`  | `string`                         | Page description                                           |
| `onPlanSelect` | `(planId: string) => void`       | Callback when a plan is selected                           |
| `size`         | `"small" \| "medium" \| "large"` | Component size variant                                     |
| `theme`        | `"minimal" \| "classic"`         | Theme variant                                              |
| `className`    | `string`                         | Additional CSS classes                                     |

## Data Types

### PricingTableSevenPlan

```tsx
interface PricingTableSevenPlan {
  id: string;                    // Unique identifier for the plan
  name: string;                  // Display name of the plan
  description: string;           // Plan description
  price: number;                 // Price in dollars
  users: number | string;        // Number of users (can be "25+" for unlimited)
  popular?: boolean;             // Whether this plan is marked as popular
}
```

### FeatureCategory

```tsx
interface FeatureCategory {
  category: string;              // Category name (e.g., "Overview", "Reporting")
  items: FeatureItemRecord[];    // Array of features in this category
}
```

### FeatureItemRecord

```tsx
interface FeatureItemRecord {
  name: string;                  // Feature name
  tooltip?: boolean;             // Whether to show tooltip icon
  [planId: string]: boolean | string | undefined;  // Feature value per plan
}
```

## Features

* **Dual Theme Support**: Choose between minimal and classic themes
* **Interactive Plan Selection**: Users can click on pricing cards to select plans
* **Feature Comparison Table**: Detailed feature comparison across all plans
* **User Slider**: Interactive slider showing current plan's user count with real-time plan updates
* **Responsive Design**: Mobile-first approach with responsive grid layouts
* **Accessibility**: ARIA labels, keyboard navigation, and screen reader support
* **Customizable Sizing**: Small, medium, and large size variants
* **TypeScript Support**: Full type safety with comprehensive interfaces
* **Smooth Animations**: Transitions and hover effects using Framer Motion

## Theming

The pricing table component supports two themes:

* **Minimal**: Clean, simple design with subtle styling
* **Classic**: Enhanced design with gradients and visual effects

You can customize the colors and fonts by overriding the CSS variables. You can also get the theme from the [Theming](/docs/theming) page.

## Example

```tsx title="src/components/pricing-table-seven-demo.tsx"
"use client";

import { PricingTableSeven } from "@/components/billingsdk/pricing-table-seven";

const plans = [
  {
    id: "basic",
    name: "Basic plan",
    description: "Our most popular plan.",
    price: 10,
    popular: false,
    users: 5,
  },
  {
    id: "business",
    name: "Business plan",
    description: "Best for growing teams.",
    price: 20,
    popular: true,
    users: 15,
  },
  {
    id: "enterprise",
    name: "Enterprise plan",
    description: "Best for large teams.",
    price: 40,
    popular: false,
    users: 25,
  },
];

const features = [
  {
    category: "Overview",
    items: [
      {
        name: "Basic features",
        tooltip: true,
        basic: true,
        business: true,
        enterprise: true,
      },
      {
        name: "Users",
        tooltip: true,
        basic: "10",
        business: "20",
        enterprise: "Unlimited",
      },
      {
        name: "Individual data",
        tooltip: true,
        basic: "20GB",
        business: "40GB",
        enterprise: "Unlimited",
      },
      {
        name: "Support",
        tooltip: true,
        basic: true,
        business: true,
        enterprise: true,
      },
      {
        name: "Automated workflows",
        tooltip: true,
        basic: false,
        business: true,
        enterprise: true,
      },
      {
        name: "200+ integrations",
        tooltip: true,
        basic: false,
        business: true,
        enterprise: true,
      },
    ],
  },
  {
    category: "Reporting and analytics",
    items: [
      {
        name: "Analytics",
        tooltip: true,
        basic: "Basic",
        business: "Advanced",
        enterprise: "Advanced",
      },
      {
        name: "Export reports",
        tooltip: true,
        basic: true,
        business: true,
        enterprise: true,
      },
      {
        name: "Scheduled reports",
        tooltip: true,
        basic: true,
        business: true,
        enterprise: true,
      },
      {
        name: "API access",
        tooltip: true,
        basic: false,
        business: true,
        enterprise: true,
      },
      {
        name: "Advanced reports",
        tooltip: true,
        basic: false,
        business: true,
        enterprise: true,
      },
      {
        name: "Saved reports",
        tooltip: true,
        basic: false,
        business: true,
        enterprise: true,
      },
      {
        name: "Customer properties",
        tooltip: true,
        basic: false,
        business: false,
        enterprise: true,
      },
      {
        name: "Custom fields",
        tooltip: true,
        basic: false,
        business: false,
        enterprise: true,
      },
    ],
  },
  {
    category: "User access",
    items: [
      {
        name: "SSO/SAML authentication",
        tooltip: true,
        basic: true,
        business: true,
        enterprise: true,
      },
      {
        name: "Advanced permissions",
        tooltip: true,
        basic: false,
        business: true,
        enterprise: true,
      },
      {
        name: "Audit log",
        tooltip: true,
        basic: false,
        business: false,
        enterprise: true,
      },
      {
        name: "Data history",
        tooltip: true,
        basic: false,
        business: false,
        enterprise: true,
      },
    ],
  },
];

export function PricingTableSevenDemo() {
  return (
    <PricingTableSeven
      plans={plans}
      features={features}
      title="Choose a plan that's right for you"
      description="We believe Untitled should be accessible to all companies, no matter the size of your startup."
      onPlanSelect={(planId: string) => console.log("Selected plan:", planId)}
      size="medium"
      theme="classic"
      className="w-full"
    />
  );
}

```


# Pricing Table Six
URL: /docs/components/pricing-table/pricing-table-six

The Pricing Table Six component provides a modern gradient design for displaying pricing plans. This component features beautiful gradients, smooth animations, and a contemporary card-based layout.

***

title: Pricing Table Six
description: The Pricing Table Six component provides a modern gradient design for displaying pricing plans. This component features beautiful gradients, smooth animations, and a contemporary card-based layout.
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

<Tabs items={['Preview', 'Code']} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="pricing-table-six">
      <PricingTableSixDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/pricing-table-six-demo.tsx"
    "use client";

    import {
      PlanProps,
      PricingTableSix,
    } from "@/registry/billingsdk/pricing-table-six";

    export function PricingTableSixDemo() {
      const plans: PlanProps[] = [
        {
          id: "basic",
          title: "Starter",
          description: "Best for individuals and small teams",
          monthlyPrice: 0,
          yearlyPrice: 0,
          features: [
            "Core tools with modest usage allowances",
            "Getting-started guides to launch quickly",
            "Fundamental analytics and reports",
            "Standard email assistance",
          ],
        },
        {
          id: "premium",
          title: "Growth",
          description: "Built for expanding teams",
          monthlyPrice: 50,
          yearlyPrice: 500,
          isFeatured: true,
          features: [
            "Advanced tools with priority updates",
            "Onboarding guides to ramp fast",
            "Live chat support access",
            "Automation to streamline workflows",
            "Premium tutorials and webinars access",
          ],
        },
        {
          id: "custom",
          title: "Enterprise",
          description: "Tailored for specialized requirements",
          monthlyPrice: 99,
          yearlyPrice: 990,
          isCustom: true,
          features: [
            "Unlimited users, projects, and data",
            "Resources that scale with your needs",
            "24/7 priority support",
            "White-label reports, dashboards, and UIs",
            "Support for custom API integrations",
            "Works with advanced or proprietary systems",
          ],
        },
      ];

      return (
        <PricingTableSix
          plans={plans}
          onPlanSelect={(planId: string) => console.log("Selected plan:", planId)}
        />
      );
    }

    ```
  </Tab>
</Tabs>

## Installation

<Tabs items={['shadcn', 'billingSDK']} defaultValue="shadcn" className="bg-transparent border-none">
  <Tab value="shadcn" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="installation-tabs">
      <Tab value="npx">
        ```bash
        npx shadcn@latest add @billingsdk/pricing-table-six
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @billingsdk/pricing-table-six
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @billingsdk/pricing-table-six
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx shadcn@latest add @billingsdk/pricing-table-six
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab value="billingSDK" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="billingsdk-cli-tabs">
      <Tab value="npx">
        ```bash
        npx @billingsdk/cli add pricing-table-six
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx @billingsdk/cli add pricing-table-six
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx @billingsdk/cli add pricing-table-six
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx @billingsdk/cli add pricing-table-six
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## Usage

```tsx
import { PricingTableSix } from "@/components/billingsdk/pricing-table-six";
import { PlanProps } from "@/registry/billingsdk/pricing-table-six";
import { plans } from "@/lib/billingsdk-config";

const plans: PlanProps[] = [
        {
          id: "basic",
          title: "Starter",
          description: "Best for individuals and small teams",
          monthlyPrice: 0,
          yearlyPrice: 0,
          features: [
            "Core tools with modest usage allowances",
            "Getting-started guides to launch quickly",
            "Fundamental analytics and reports",
            "Standard email assistance",
          ]
        },
        {
          id: "premium",
          title: "Growth",
          description: "Built for expanding teams",
          monthlyPrice: 50,
          yearlyPrice: 500,
          isFeatured: true,
          features: [
            "Advanced tools with priority updates",
            "Onboarding guides to ramp fast",
            "Live chat support access",
            "Automation to streamline workflows",
            "Premium tutorials and webinars access",
          ]
        },
        {
          id: "custom",
          title: "Enterprise",
          description: "Tailored for specialized requirements",
          monthlyPrice: 99,
          yearlyPrice: 990,
          isCustom: true,
          features: [
            "Unlimited users, projects, and data",
            "Resources that scale with your needs",
            "24/7 priority support",
            "White-label reports, dashboards, and UIs",
            "Support for custom API integrations",
            "Works with advanced or proprietary systems",
          ]
        },
      ]

  <PricingTableSix 
    plans={plans}
    onPlanSelect={(planId) => console.log('Selected plan:', planId)}
  />
```

## Props

| Prop           | Type                       | Description                      |
| -------------- | -------------------------- | -------------------------------- |
| `plans`        | `PlanProps[]`              | Array of pricing plans           |
| `onPlanSelect` | `(planId: string) => void` | Callback when a plan is selected |

## Features

* **Responsive Layout**: Grid layout that adapts cleanly across breakpoints
* **Interactive Elements**: Subtle hover effects and smooth transitions
* **Billing Toggle**: Monthly/yearly switch with animated price changes
* **Highlight Support**: Distinct styling for featured or popular plans
* **Theming & Tokens**: Easily themeable with Tailwind and `shadcn/ui` primitives

## Theming

The pricing table component is styled using the `shadcn/ui` library. You can customize the colors and fonts by overriding the CSS variables. You can also get the theme from the [Theming](/docs/theming) page.

## Example

```tsx title="src/components/pricing-table-six-demo.tsx"
"use client";

import {
  PlanProps,
  PricingTableSix,
} from "@/registry/billingsdk/pricing-table-six";

export function PricingTableSixDemo() {
  const plans: PlanProps[] = [
    {
      id: "basic",
      title: "Starter",
      description: "Best for individuals and small teams",
      monthlyPrice: 0,
      yearlyPrice: 0,
      features: [
        "Core tools with modest usage allowances",
        "Getting-started guides to launch quickly",
        "Fundamental analytics and reports",
        "Standard email assistance",
      ],
    },
    {
      id: "premium",
      title: "Growth",
      description: "Built for expanding teams",
      monthlyPrice: 50,
      yearlyPrice: 500,
      isFeatured: true,
      features: [
        "Advanced tools with priority updates",
        "Onboarding guides to ramp fast",
        "Live chat support access",
        "Automation to streamline workflows",
        "Premium tutorials and webinars access",
      ],
    },
    {
      id: "custom",
      title: "Enterprise",
      description: "Tailored for specialized requirements",
      monthlyPrice: 99,
      yearlyPrice: 990,
      isCustom: true,
      features: [
        "Unlimited users, projects, and data",
        "Resources that scale with your needs",
        "24/7 priority support",
        "White-label reports, dashboards, and UIs",
        "Support for custom API integrations",
        "Works with advanced or proprietary systems",
      ],
    },
  ];

  return (
    <PricingTableSix
      plans={plans}
      onPlanSelect={(planId: string) => console.log("Selected plan:", planId)}
    />
  );
}

```

### Credits

* Created by [@vamsisai696](https://x.com/vamsisai696)


# Pricing Table Three
URL: /docs/components/pricing-table/pricing-table-three

The Pricing Table Three component provides a third design option for pricing displays. You can use this component to display your pricing plans in a third way.

***

title: Pricing Table Three
description: The Pricing Table Three component provides a third design option for pricing displays. You can use this component to display your pricing plans in a third way.
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------

<Tabs items={['Preview', 'Code']} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="pricing-table-three">
      <PricingTableThreeDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/pricing-table-three-demo.tsx"
    "use client";

    import { PricingTableThree } from "@/components/billingsdk/pricing-table-three";
    import { plans } from "@/lib/billingsdk-config";

    export function PricingTableThreeDemo() {
      return (
        <PricingTableThree
          plans={plans}
          onPlanSelect={(planId) => console.log("Selected plan:", planId)}
          className={"mx-auto w-full max-w-4xl"}
          variant="small"
          showFooter={true}
          footerText="Pre-negotiated discounts are available to early-stage startups and nonprofits."
          footerButtonText="Apply now"
          onFooterButtonClick={() => console.log("Footer button clicked")}
        />
      );
    }

    ```
  </Tab>
</Tabs>

## Installation

<Tabs items={['shadcn', 'billingSDK']} defaultValue="shadcn" className="bg-transparent border-none">
  <Tab value="shadcn" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="installation-tabs">
      <Tab value="npx">
        ```bash
        npx shadcn@latest add @billingsdk/pricing-table-three
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @billingsdk/pricing-table-three
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @billingsdk/pricing-table-three
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx shadcn@latest add @billingsdk/pricing-table-three
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab value="billingSDK" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="billingsdk-cli-tabs">
      <Tab value="npx">
        ```bash
        npx @billingsdk/cli add pricing-table-three
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx @billingsdk/cli add pricing-table-three
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx @billingsdk/cli add pricing-table-three
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx @billingsdk/cli add pricing-table-three
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## Usage

```tsx
import { PricingTableThree } from "@/components/billingsdk/pricing-table-three";
import { plans } from "@/lib/billingsdk-config";

<PricingTableThree 
  plans={plans}
  title="Pricing Plans"
  description="Find the right plan for your business"
  onPlanSelect={(planId) => console.log('Selected plan:', planId)}
/>
```

## Props

| Prop           | Type                              | Description                                                                    |
| -------------- | --------------------------------- | ------------------------------------------------------------------------------ |
| `plans`        | `Plan[]`                          | Array of pricing plans (see [Plan interface](/docs/interfaces#plan-interface)) |
| `title`        | `string`                          | Main title for the pricing section                                             |
| `description`  | `string`                          | Subtitle description                                                           |
| `onPlanSelect` | `(planId: string) => void`        | Callback when a plan is selected                                               |
| `variant`      | `"small" \| "medium" \|  "large"` | Size variant of the pricing table                                              |

## Theming

The pricing table component is styled using the `shadcn/ui` library. You can customize the colors and fonts by overriding the CSS variables. You can also get the theme from the [Theming](/docs/theming) page.

## Example

```tsx title="src/components/pricing-table-three-demo.tsx"
"use client";

import { PricingTableThree } from "@/components/billingsdk/pricing-table-three";
import { plans } from "@/lib/billingsdk-config";

export function PricingTableThreeDemo() {
  return (
    <PricingTableThree
      plans={plans}
      onPlanSelect={(planId) => console.log("Selected plan:", planId)}
      className={"mx-auto w-full max-w-4xl"}
      variant="small"
      showFooter={true}
      footerText="Pre-negotiated discounts are available to early-stage startups and nonprofits."
      footerButtonText="Apply now"
      onFooterButtonClick={() => console.log("Footer button clicked")}
    />
  );
}

```


# Pricing Table Two
URL: /docs/components/pricing-table/pricing-table-two

The Pricing Table Two component offers an alternative design approach for pricing displays. You can use this component to display your pricing plans in an alternative way.

***

title: Pricing Table Two
description: The Pricing Table Two component offers an alternative design approach for pricing displays. You can use this component to display your pricing plans in an alternative way.

***

## Classic Theme

<Tabs items={['Preview', 'Code']} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="pricing-table-two">
      <PricingTableTwoDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/pricing-table-two-demo.tsx"
    "use client";

    import { plans } from "@/lib/billingsdk-config";
    import { PricingTableTwo } from "@/components/billingsdk/pricing-table-two";

    export function PricingTableTwoDemo() {
      return (
        <PricingTableTwo
          plans={plans}
          className="mx-auto w-full max-w-4xl"
          title={`We offer ${plans.length} plans`}
          description="Choose the plan that's right for you"
          onPlanSelect={(planId) => console.log("Selected plan:", planId)}
          size="small" // small, medium, large
          theme="classic" // minimal or classic
        />
      );
    }

    ```
  </Tab>
</Tabs>

## Minimal Theme

<Tabs items={['Preview', 'Code']} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="pricing-table-two">
      <PricingTableTwoMinimalDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/pricing-table-two-minimal-demo.tsx"
    "use client";

    import { plans } from "@/lib/billingsdk-config";
    import { PricingTableTwo } from "@/components/billingsdk/pricing-table-two";

    export function PricingTableTwoMinimalDemo() {
      return (
        <>
          <PricingTableTwo
            plans={plans}
            className="mx-auto w-full max-w-4xl"
            title={`We offer ${plans.length} plans`}
            description="Choose the plan that's right for you"
            onPlanSelect={(planId) => console.log("Selected plan:", planId)}
            size="small" // small, medium, large
            theme="minimal" // minimal or classic
          />
        </>
      );
    }

    ```
  </Tab>
</Tabs>

## Installation

<Tabs items={['shadcn', 'billingSDK']} defaultValue="shadcn" className="bg-transparent border-none">
  <Tab value="shadcn" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="installation-tabs">
      <Tab value="npx">
        ```bash
        npx shadcn@latest add @billingsdk/pricing-table-two
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @billingsdk/pricing-table-two
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @billingsdk/pricing-table-two
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx shadcn@latest add @billingsdk/pricing-table-two
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab value="billingSDK" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="billingsdk-cli-tabs">
      <Tab value="npx">
        ```bash
        npx @billingsdk/cli add pricing-table-two
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx @billingsdk/cli add pricing-table-two
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx @billingsdk/cli add pricing-table-two
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx @billingsdk/cli add pricing-table-two
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## Usage

```tsx
import { PricingTableTwo } from "@/components/billingsdk/pricing-table-two";
import { plans } from "@/lib/billingsdk-config";
```

```tsx
<PricingTableTwo 
  plans={plans}
  title="Choose Your Plan"
  description="Select the perfect plan for your needs"
  onPlanSelect={(planId) => console.log('Selected plan:', planId)}
  size="small" // small, medium, large
  theme="classic" // minimal or classic
/>
```

## Props

| Prop           | Type                              | Description                                                                    |
| -------------- | --------------------------------- | ------------------------------------------------------------------------------ |
| `plans`        | `Plan[]`                          | Array of pricing plans (see [Plan interface](/docs/interfaces#plan-interface)) |
| `title`        | `string`                          | Main title for the pricing section                                             |
| `description`  | `string`                          | Subtitle description                                                           |
| `onPlanSelect` | `(planId: string) => void`        | Callback when a plan is selected                                               |
| `variant`      | `"small" \| "medium" \|  "large"` | Size variant of the pricing table                                              |

## Theming

The pricing table component is styled using the `shadcn/ui` library. You can customize the colors and fonts by overriding the CSS variables. You can also get the theme from the [Theming](/docs/theming) page.

## Example

```tsx title="src/components/pricing-table-two-demo.tsx"
"use client";

import { plans } from "@/lib/billingsdk-config";
import { PricingTableTwo } from "@/components/billingsdk/pricing-table-two";

export function PricingTableTwoDemo() {
  return (
    <PricingTableTwo
      plans={plans}
      className="mx-auto w-full max-w-4xl"
      title={`We offer ${plans.length} plans`}
      description="Choose the plan that's right for you"
      onPlanSelect={(planId) => console.log("Selected plan:", planId)}
      size="small" // small, medium, large
      theme="classic" // minimal or classic
    />
  );
}

```


# Proration Preview
URL: /docs/components/proration-preview

Interactive component that shows billing adjustments when users change subscription plans, featuring cost breakdowns, credits, and prorated charges with immediate or next-cycle options.

***

title: Proration Preview
description: Interactive component that shows billing adjustments when users change subscription plans, featuring cost breakdowns, credits, and prorated charges with immediate or next-cycle options.
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

## Default

<Tabs items={['Preview', 'Code']} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="proration-preview">
      <ProrationPreviewDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/proration-preview-demo.tsx"
    "use client";

    import { ProrationPreview } from "@/components/billingsdk/proration-preview";
    import {
      Card,
      CardContent,
      CardDescription,
      CardHeader,
      CardTitle,
    } from "@/components/ui/card";
    import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";

    const currentPlan = {
      plan: {
        id: "pro",
        title: "Pro",
        description: "Best for small teams",
        monthlyPrice: "29.99",
        yearlyPrice: "299.99",
        currency: "$",
        buttonText: "Current Plan",
        features: [
          { name: "Advanced features", icon: "check" },
          { name: "Priority support", icon: "check" },
        ],
      },
      type: "monthly" as const,
      price: "29.99",
      nextBillingDate: "2024-01-15",
      paymentMethod: "•••• 4242",
      status: "active" as const,
    };

    const yearlyCurrentPlan = {
      plan: {
        id: "pro-yearly",
        title: "Pro",
        description: "Best for small teams",
        monthlyPrice: "29.99",
        yearlyPrice: "299.99",
        currency: "$",
        buttonText: "Current Plan",
        features: [
          { name: "Advanced features", icon: "check" },
          { name: "Priority support", icon: "check" },
        ],
      },
      type: "yearly" as const,
      price: "299.99",
      nextBillingDate: "2024-12-15",
      paymentMethod: "•••• 4242",
      status: "active" as const,
    };

    const basicPlan = {
      id: "basic",
      title: "Basic",
      description: "Perfect for getting started",
      monthlyPrice: "9.99",
      yearlyPrice: "99.99",
      currency: "$",
      buttonText: "Downgrade",
      features: [
        { name: "Basic features", icon: "check" },
        { name: "Email support", icon: "check" },
      ],
    };

    const enterprisePlan = {
      id: "enterprise",
      title: "Enterprise",
      description: "For large organizations",
      monthlyPrice: "99.99",
      yearlyPrice: "999.99",
      currency: "$",
      buttonText: "Upgrade",
      features: [
        { name: "All features", icon: "check" },
        { name: "Priority support", icon: "check" },
        { name: "Custom integrations", icon: "check" },
      ],
    };

    const customPlan = {
      id: "custom",
      title: "Custom",
      description: "Tailored for your needs",
      monthlyPrice: "Custom",
      yearlyPrice: "Custom",
      currency: "$",
      buttonText: "Contact Sales",
      features: [
        { name: "Custom features", icon: "check" },
        { name: "Dedicated support", icon: "check" },
      ],
    };

    export function ProrationPreviewDemo() {
      return (
        <div className="space-y-8">
          <Tabs defaultValue="upgrade" className="w-full">
            <TabsList className="grid w-full grid-cols-4">
              <TabsTrigger value="upgrade">Upgrade</TabsTrigger>
              <TabsTrigger value="downgrade">Downgrade</TabsTrigger>
              <TabsTrigger value="cycle-change">Cycle Change</TabsTrigger>
              <TabsTrigger value="next-cycle">Next Cycle</TabsTrigger>
            </TabsList>

            <TabsContent value="upgrade" className="space-y-6">
              <Card>
                <CardHeader>
                  <CardTitle>Monthly to Enterprise Upgrade</CardTitle>
                  <CardDescription>
                    Upgrading from Pro monthly to Enterprise monthly with 15 days
                    remaining
                  </CardDescription>
                </CardHeader>
                <CardContent>
                  <ProrationPreview
                    currentPlan={currentPlan}
                    newPlan={enterprisePlan}
                    billingCycle="monthly"
                    daysRemaining={15}
                    effectiveDate="immediately"
                    theme="minimal"
                    onConfirm={() => {}}
                    onCancel={() => {}}
                  />
                </CardContent>
              </Card>
            </TabsContent>

            <TabsContent value="downgrade" className="space-y-6">
              <Card>
                <CardHeader>
                  <CardTitle>Enterprise to Basic Downgrade</CardTitle>
                  <CardDescription>
                    Downgrading from Enterprise to Basic with account credit
                  </CardDescription>
                </CardHeader>
                <CardContent>
                  <ProrationPreview
                    currentPlan={{
                      plan: enterprisePlan,
                      type: "monthly",
                      price: "99.99",
                      nextBillingDate: "2024-01-15",
                      paymentMethod: "•••• 4242",
                      status: "active",
                    }}
                    newPlan={basicPlan}
                    billingCycle="monthly"
                    daysRemaining={20}
                    effectiveDate="immediately"
                    theme="minimal"
                    onConfirm={() => {}}
                    onCancel={() => {}}
                  />
                </CardContent>
              </Card>
            </TabsContent>

            <TabsContent value="cycle-change" className="space-y-6">
              <Card>
                <CardHeader>
                  <CardTitle>Monthly to Yearly Switch</CardTitle>
                  <CardDescription>
                    Switching from monthly to yearly billing for the same plan
                  </CardDescription>
                </CardHeader>
                <CardContent>
                  <ProrationPreview
                    currentPlan={currentPlan}
                    newPlan={currentPlan.plan}
                    billingCycle="yearly"
                    daysRemaining={10}
                    effectiveDate="immediately"
                    theme="minimal"
                    onConfirm={() => {}}
                    onCancel={() => {}}
                  />
                </CardContent>
              </Card>

              <Card>
                <CardHeader>
                  <CardTitle>Yearly to Monthly Switch</CardTitle>
                  <CardDescription>
                    Switching from yearly to monthly billing
                  </CardDescription>
                </CardHeader>
                <CardContent>
                  <ProrationPreview
                    currentPlan={yearlyCurrentPlan}
                    newPlan={yearlyCurrentPlan.plan}
                    billingCycle="monthly"
                    daysRemaining={120}
                    effectiveDate="immediately"
                    theme="classic"
                    onConfirm={() => {}}
                    onCancel={() => {}}
                  />
                </CardContent>
              </Card>
            </TabsContent>

            <TabsContent value="next-cycle" className="space-y-6">
              <Card>
                <CardHeader>
                  <CardTitle>Next Cycle Change</CardTitle>
                  <CardDescription>
                    Plan change effective at the next billing cycle with no
                    immediate charge
                  </CardDescription>
                </CardHeader>
                <CardContent>
                  <ProrationPreview
                    currentPlan={currentPlan}
                    newPlan={enterprisePlan}
                    billingCycle="monthly"
                    daysRemaining={25}
                    effectiveDate="next billing cycle"
                    theme="minimal"
                    onConfirm={() => {}}
                    onCancel={() => {}}
                  />
                </CardContent>
              </Card>

              <Card>
                <CardHeader>
                  <CardTitle>Custom Pricing Scenario</CardTitle>
                  <CardDescription>
                    Handling custom/enterprise pricing that doesn't follow standard
                    rates
                  </CardDescription>
                </CardHeader>
                <CardContent>
                  <ProrationPreview
                    currentPlan={currentPlan}
                    newPlan={customPlan}
                    billingCycle="monthly"
                    daysRemaining={12}
                    effectiveDate="next billing cycle"
                    theme="classic"
                    onConfirm={() => {}}
                    onCancel={() => {}}
                  />
                </CardContent>
              </Card>
            </TabsContent>
          </Tabs>
        </div>
      );
    }

    ```
  </Tab>
</Tabs>

## Installation

<Tabs items={['CLI', 'Manual']} className="bg-transparent border-none">
  <Tab value="CLI" className="mt-3">
    ```bash
    yarn dlx @billingsdk/cli add proration-preview
    ```
  </Tab>

  <Tab value="Manual" className="mt-3">
    **Step 1**: Install the following dependencies:

    ```bash
    npm install motion lucide-react class-variance-authority
    ```

    **Step 2**: Copy and paste the following code into your project.

    ```tsx title="src/components/billingsdk/proration-preview\.tsx"
    "use client";

    import { motion } from "motion/react";
    import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
    import { Badge } from "@/components/ui/badge";
    import { Button } from "@/components/ui/button";
    import { Separator } from "@/components/ui/separator";
    import {
      ArrowRight,
      Calendar,
      CreditCard,
      Calculator,
      Clock,
    } from "lucide-react";
    import { type Plan, type CurrentPlan } from "@/lib/billingsdk-config";
    import { cn } from "@/lib/utils";
    import { cva, type VariantProps } from "class-variance-authority";

    const prorationPreviewVariants = cva("w-full max-w-3xl mx-auto", {
      variants: {
        theme: {
          minimal: "",
          classic:
            "relative overflow-hidden rounded-xl border border-border/50 bg-gradient-to-br from-card/50 to-muted/30 backdrop-blur-sm",
        },
        size: {
          small: "text-sm",
          medium: "text-base",
          large: "text-lg",
        },
      },
      defaultVariants: {
        theme: "minimal",
        size: "medium",
      },
    });

    const cardVariants = cva("transition-all duration-300", {
      variants: {
        theme: {
          minimal: "border border-border bg-card",
          classic:
            "border border-border/30 bg-gradient-to-br from-card/80 to-muted/20 backdrop-blur-sm shadow-md",
        },
      },
      defaultVariants: {
        theme: "minimal",
      },
    });

    /**
     * Props for `ProrationPreview`.
     *
     * Combines visual variants from `prorationPreviewVariants` with
     * the billing context needed to compute proration math.
     *
     * - `currentPlan` and `newPlan` supply pricing and labels
     * - `billingCycle` controls the target cycle for the new plan
     * - `daysRemaining` and `effectiveDate` influence credit/charge math
     * - `onConfirm`/`onCancel` wire user actions
     */
    export interface ProrationPreviewProps extends VariantProps<
      typeof prorationPreviewVariants
    > {
      className?: string;
      currentPlan: CurrentPlan;
      newPlan: Plan;
      billingCycle: "monthly" | "yearly";
      daysRemaining?: number;
      effectiveDate?: string;
      onConfirm?: () => void;
      onCancel?: () => void;
      confirmText?: string;
      cancelText?: string;
    }

    /**
     * ProrationPreview
     *
     * Renders a detailed, accessible preview of billing changes when a user switches
     * subscription plans. It calculates and displays credits for unused time,
     * prorated charges for the new plan, and the resulting net amount, with clear
     * visual hierarchy and responsive styles.
     *
     * Key UI sections:
     * - From/To plan summary with upgrade/downgrade badges
     * - Billing breakdown (credit, prorated charge, net amount)
     * - Timeline note describing when changes take effect
     * - Primary/secondary actions to confirm or cancel
     *
     * Props accept both monthly and yearly cycles and support custom pricing
     * scenarios (e.g., enterprise). Visual appearance can be adjusted via
     * `theme` and `size` variants.
     *
     * @param props.className Optional container className override.
     * @param props.currentPlan Current subscription context including plan and cycle.
     * @param props.newPlan Target plan the user is moving to.
     * @param props.billingCycle Billing cycle for the new plan (monthly/yearly).
     * @param props.daysRemaining Remaining days in the current cycle (defaults to 15).
     * @param props.effectiveDate When the change takes effect (e.g., "immediately" or "next billing cycle").
     * @param props.onConfirm Callback invoked when user confirms the change.
     * @param props.onCancel Callback invoked when user cancels the change.
     * @param props.confirmText Custom label for the confirm action.
     * @param props.cancelText Custom label for the cancel action.
     * @param props.theme Visual theme variant (minimal | classic). Defaults to minimal.
     * @param props.size Component size (small | medium | large). Defaults to medium.
     */
    export function ProrationPreview({
      className,
      currentPlan,
      newPlan,
      billingCycle,
      daysRemaining = 15,
      effectiveDate = "immediately",
      onConfirm,
      onCancel,
      confirmText = "Confirm Change",
      cancelText = "Cancel",
      theme = "minimal",
      size = "medium",
    }: ProrationPreviewProps) {
      // Prices & proration (robust) - Fixed CodeRabbit issues
      const currentCycleDays = currentPlan.type === "yearly" ? 365 : 30;
      const newCycleDays = billingCycle === "yearly" ? 365 : 30;
      const isNumericValue = (v?: string) => {
        if (v == null) return false;
        const s = String(v).replace(/[^\d.\-]/g, "");
        const n = Number.parseFloat(s);
        return Number.isFinite(n);
      };
      const toNumber = (v?: string) => {
        if (v == null) return undefined;
        const s = String(v).replace(/[^\d.\-]/g, "");
        const n = Number.parseFloat(s);
        return Number.isFinite(n) ? n : undefined;
      };
      const currentRaw =
        currentPlan.type === "monthly"
          ? currentPlan.plan.monthlyPrice
          : currentPlan.type === "yearly"
            ? currentPlan.plan.yearlyPrice
            : currentPlan.price;
      const newRaw =
        billingCycle === "monthly" ? newPlan.monthlyPrice : newPlan.yearlyPrice;
      const currentPrice = toNumber(currentRaw);
      const newPrice = toNumber(newRaw);
      const isCustomCurrent = !isNumericValue(currentRaw);
      const isCustomNew = !isNumericValue(newRaw);
      const chargeCurrency = newPlan.currency ?? currentPlan.plan.currency ?? "$";
      const creditCurrency = currentPlan.plan.currency ?? newPlan.currency ?? "$";
      const clampedUnusedDays = Math.max(
        0,
        Math.min(daysRemaining, currentCycleDays),
      );
      const isNextCycle =
        typeof effectiveDate === "string" &&
        effectiveDate.toLowerCase().includes("next");

      const prorationDays = isNextCycle ? 0 : clampedUnusedDays;
      const canCompute =
        !isNextCycle &&
        !isCustomCurrent &&
        !isCustomNew &&
        currentPrice !== undefined &&
        newPrice !== undefined;
      const creditAmount = canCompute
        ? (currentPrice! / currentCycleDays) * clampedUnusedDays
        : 0;
      const proratedCharge = canCompute
        ? (newPrice! / newCycleDays) * prorationDays
        : 0;
      const netAmount = proratedCharge - creditAmount;

      const normalizedCurrentMonthly =
        currentPlan.type === "yearly" && currentPrice !== undefined
          ? currentPrice / 12
          : (currentPrice ?? 0);
      const normalizedNewMonthly =
        billingCycle === "yearly" && newPrice !== undefined
          ? newPrice / 12
          : (newPrice ?? 0);
      const hasComparablePrices =
        !isCustomCurrent &&
        !isCustomNew &&
        currentPrice !== undefined &&
        newPrice !== undefined;
      const isUpgrade =
        hasComparablePrices && normalizedNewMonthly > normalizedCurrentMonthly;
      const isDowngrade =
        hasComparablePrices && normalizedNewMonthly < normalizedCurrentMonthly;

      return (
        <div className={cn(prorationPreviewVariants({ theme, size }), className)}>
          {theme === "classic" && (
            <>
              <div className="bg-grid-pattern absolute inset-0 opacity-5" />
              <div className="bg-primary/5 absolute top-1/2 left-1/2 h-64 w-64 -translate-x-1/2 -translate-y-1/2 rounded-full blur-3xl" />
            </>
          )}

          <Card className={cn(cardVariants({ theme }))}>
            <CardHeader className="px-4 pb-3 sm:px-6 sm:pb-4">
              <CardTitle className="flex items-center gap-2 text-base sm:text-lg">
                <div className="bg-primary/10 ring-primary/20 rounded-lg p-2 ring-1">
                  <Calculator className="text-primary h-4 w-4 sm:h-5 sm:w-5" />
                </div>
                Plan Change Preview
              </CardTitle>
              <p className="text-muted-foreground text-sm">
                Review the charges and credits for your plan change
              </p>
            </CardHeader>

            <CardContent className="space-y-4 px-4 sm:space-y-6 sm:px-6">
              {/* From/To Plans */}
              <div className="grid grid-cols-1 items-center gap-3 sm:gap-4 md:grid-cols-3">
                {/* Current Plan */}
                <motion.div
                  initial={{ opacity: 0, x: -20 }}
                  animate={{ opacity: 1, x: 0 }}
                  transition={{ duration: 0.3 }}
                  className={cn(
                    "rounded-lg border p-3 sm:p-4",
                    theme === "classic"
                      ? "from-muted/50 to-background/50 border-border/50 bg-gradient-to-br"
                      : "bg-muted/50 border-border",
                  )}
                >
                  <div className="mb-2 flex items-center gap-2">
                    <Badge variant="outline" className="text-[10px] sm:text-xs">
                      Current
                    </Badge>
                    {isDowngrade && (
                      <Badge variant="secondary" className="text-[10px] sm:text-xs">
                        Downgrading
                      </Badge>
                    )}
                  </div>
                  <h3 className="text-base font-semibold sm:text-lg">
                    {currentPlan.plan.title}
                  </h3>
                  <p className="text-muted-foreground mb-3 text-xs sm:text-sm">
                    {isCustomCurrent
                      ? "Custom"
                      : `${creditCurrency}${currentPrice}/${currentPlan.type}`}
                  </p>
                  <div className="text-muted-foreground flex items-center gap-1 text-xs">
                    <Clock className="h-3 w-3 sm:h-4 sm:w-4" />
                    {daysRemaining} days remaining
                  </div>
                </motion.div>

                {/* Arrow */}
                <div className="flex justify-center">
                  <motion.div
                    initial={{ scale: 0 }}
                    animate={{ scale: 1 }}
                    transition={{ duration: 0.3, delay: 0.2 }}
                    className={cn(
                      "rounded-full p-2",
                      theme === "classic"
                        ? "from-primary to-primary/80 text-primary-foreground bg-gradient-to-r shadow-lg"
                        : "bg-primary/10 text-primary",
                    )}
                  >
                    <ArrowRight className="h-4 w-4 sm:h-5 sm:w-5" />
                  </motion.div>
                </div>

                {/* New Plan */}
                <motion.div
                  initial={{ opacity: 0, x: 20 }}
                  animate={{ opacity: 1, x: 0 }}
                  transition={{ duration: 0.3, delay: 0.1 }}
                  className={cn(
                    "rounded-lg border p-3 sm:p-4",
                    theme === "classic"
                      ? "from-primary/5 to-primary/10 border-primary/30 bg-gradient-to-br"
                      : "bg-primary/5 border-primary/30",
                  )}
                >
                  <div className="mb-2 flex items-center gap-2">
                    <Badge variant="default" className="text-[10px] sm:text-xs">
                      New Plan
                    </Badge>
                    {isUpgrade && (
                      <Badge variant="secondary" className="text-[10px] sm:text-xs">
                        Upgrading
                      </Badge>
                    )}
                  </div>
                  <h3 className="text-base font-semibold sm:text-lg">
                    {newPlan.title}
                  </h3>
                  <p className="text-muted-foreground mb-3 text-xs sm:text-sm">
                    {isCustomNew
                      ? "Custom"
                      : `${chargeCurrency}${newPrice}/${billingCycle}`}
                  </p>
                  <div className="text-muted-foreground flex items-center gap-1 text-xs">
                    <Calendar className="h-3 w-3 sm:h-4 sm:w-4" />
                    Effective {effectiveDate}
                  </div>
                </motion.div>
              </div>

              <Separator
                className={cn(
                  theme === "classic" &&
                    "via-border bg-gradient-to-r from-transparent to-transparent",
                )}
              />

              {/* Calculation Breakdown */}
              <motion.div
                initial={{ opacity: 0, y: 20 }}
                animate={{ opacity: 1, y: 0 }}
                transition={{ duration: 0.3, delay: 0.4 }}
                className={cn(
                  "rounded-lg border p-3 sm:p-4",
                  theme === "classic"
                    ? "from-muted/30 to-background/30 border-border/50 bg-gradient-to-br"
                    : "bg-muted/30 border-border",
                )}
              >
                <h4 className="mb-3 flex items-center gap-2 font-medium sm:mb-4">
                  <CreditCard className="h-4 w-4 sm:h-5 sm:w-5" />
                  Billing Breakdown
                </h4>

                <div className="space-y-3">
                  <div className="flex items-center justify-between text-xs sm:text-sm">
                    <span className="text-muted-foreground">
                      Credit for unused time
                    </span>
                    <span className="font-medium text-green-600">
                      {canCompute
                        ? `-${creditCurrency}${Math.abs(creditAmount).toFixed(2)}`
                        : "—"}
                    </span>
                  </div>

                  <div className="flex items-center justify-between text-xs sm:text-sm">
                    <span className="text-muted-foreground">
                      Prorated charge ({prorationDays} days)
                    </span>
                    <span className="font-medium">
                      {canCompute
                        ? `+${chargeCurrency}${proratedCharge.toFixed(2)}`
                        : "—"}
                    </span>
                  </div>

                  <Separator className="my-2" />

                  <div className="flex items-center justify-between font-semibold">
                    <span>
                      {canCompute
                        ? netAmount >= 0
                          ? "Amount to charge"
                          : "Credit to account"
                        : "Amount due will be calculated at checkout"}
                    </span>
                    <span
                      className={cn(
                        "text-base sm:text-lg",
                        canCompute
                          ? netAmount >= 0
                            ? "text-foreground"
                            : "text-green-600"
                          : "text-muted-foreground",
                      )}
                    >
                      {canCompute
                        ? `${netAmount >= 0 ? "+" : ""}${chargeCurrency}${netAmount.toFixed(2)}`
                        : "—"}
                    </span>
                  </div>
                </div>
              </motion.div>

              {/* Timeline */}
              <motion.div
                initial={{ opacity: 0 }}
                animate={{ opacity: 1 }}
                transition={{ duration: 0.3, delay: 0.6 }}
                className="bg-muted/20 border-border/50 rounded-lg border p-3 text-center sm:p-4"
              >
                <p className="text-muted-foreground text-xs sm:text-sm">
                  Your plan will change {effectiveDate}.
                  {isNextCycle
                    ? " No immediate charge."
                    : hasComparablePrices
                      ? netAmount >= 0
                        ? ` You'll be charged ${chargeCurrency}${Math.abs(netAmount).toFixed(2)}.`
                        : ` You'll receive a ${chargeCurrency}${Math.abs(netAmount).toFixed(2)} credit.`
                      : " Amount will be finalized at checkout."}
                </p>
              </motion.div>

              {/* Action Buttons */}
              <motion.div
                initial={{ opacity: 0, y: 10 }}
                animate={{ opacity: 1, y: 0 }}
                transition={{ duration: 0.3, delay: 0.8 }}
                className="flex flex-col gap-3 pt-3 sm:flex-row sm:pt-4"
              >
                <Button
                  onClick={onConfirm}
                  className={cn(
                    "flex-1",
                    theme === "classic" &&
                      "from-primary to-primary/90 bg-gradient-to-r transition-all duration-200 hover:shadow-md active:scale-95",
                  )}
                  size="lg"
                >
                  {confirmText}
                  <ArrowRight className="ml-2 h-4 w-4 sm:h-5 sm:w-5" />
                </Button>
                <Button
                  variant="outline"
                  onClick={onCancel}
                  className="flex-1"
                  size="lg"
                >
                  {cancelText}
                </Button>
              </motion.div>
            </CardContent>
          </Card>
        </div>
      );
    }

    ```

    **Step 3**: Update the import paths to match your project setup.
  </Tab>
</Tabs>

## Usage

```tsx
import { ProrationPreview } from "@/components/billingsdk/proration-preview"
```

```tsx
<ProrationPreview
  currentPlan={{
    plan: {
      id: "pro",
      title: "Pro",
      description: "Best for small teams",
      monthlyPrice: "29.99",
      yearlyPrice: "299.99",
      currency: "$",
      buttonText: "Current Plan",
      features: [
        { name: "Advanced features", icon: "check" },
        { name: "Priority support", icon: "check" },
      ],
    },
    type: "monthly",
    price: "29.99",
    nextBillingDate: "2024-01-15",
    paymentMethod: "•••• 4242",
    status: "active",
  }}
  newPlan={{
    id: "enterprise",
    title: "Enterprise", 
    description: "For large organizations",
    monthlyPrice: "99.99",
    yearlyPrice: "999.99",
    currency: "$",
    buttonText: "Upgrade",
    features: [
      { name: "All features", icon: "check" },
      { name: "Priority support", icon: "check" },
      { name: "Custom integrations", icon: "check" },
    ],
  }}
  billingCycle="monthly"
  daysRemaining={15}
  effectiveDate="immediately"
  onConfirm={() => console.log("Plan change confirmed")}
  onCancel={() => console.log("Plan change cancelled")}
/>
```

## Examples

### Upgrade Scenario

Shows cost breakdown when upgrading from Pro to Enterprise with remaining billing cycle.

### Downgrade Scenario

Displays credit calculations when downgrading plans with unused time refunds.

### Billing Cycle Changes

Handles switching between monthly and yearly billing for the same plan.

### Next Cycle Changes

Shows plan changes that take effect at the next billing cycle with no immediate charges.

## API Reference

### ProrationPreview

| Prop            | Type                             | Default            | Description                                  |
| --------------- | -------------------------------- | ------------------ | -------------------------------------------- |
| `currentPlan`   | `CurrentPlan`                    | -                  | The user's current subscription plan details |
| `newPlan`       | `Plan`                           | -                  | The target plan they want to switch to       |
| `billingCycle`  | `'monthly' \| 'yearly'`          | -                  | The billing cycle for the new plan           |
| `daysRemaining` | `number`                         | `15`               | Days remaining in current billing cycle      |
| `effectiveDate` | `string`                         | `"immediately"`    | When the plan change takes effect            |
| `onConfirm`     | `() => void`                     | -                  | Callback when user confirms the change       |
| `onCancel`      | `() => void`                     | -                  | Callback when user cancels the change        |
| `confirmText`   | `string`                         | `"Confirm Change"` | Text for the confirm button                  |
| `cancelText`    | `string`                         | `"Cancel"`         | Text for the cancel button                   |
| `theme`         | `'minimal' \| 'classic'`         | `'minimal'`        | Visual theme variant                         |
| `size`          | `'small' \| 'medium' \| 'large'` | `'medium'`         | Component size                               |
| `className`     | `string`                         | -                  | Additional CSS classes                       |

### CurrentPlan

```tsx
interface CurrentPlan {
  plan: Plan;
  type: 'monthly' | 'yearly' | 'custom';
  price?: string;
  nextBillingDate: string;
  paymentMethod: string;
  status: 'active' | 'inactive' | 'past_due' | 'cancelled';
}
```

### Plan

```tsx
interface Plan {
  id: string;
  title: string;
  description: string;
  monthlyPrice: string;
  yearlyPrice: string;
  currency?: string;
  buttonText: string;
  features: {
    name: string;
    icon: string;
    iconColor?: string;
  }[];
}
```

## Features

* **Accurate Proration Calculations** - Handles complex billing scenarios with precise math
* **Credit & Charge Breakdown** - Shows detailed billing adjustments and credits
* **Immediate vs Next Cycle** - Supports both immediate and next-cycle plan changes
* **Theme Variants** - Minimal and classic visual themes
* **Responsive Design** - Works seamlessly across all device sizes
* **Accessibility Ready** - Full keyboard navigation and screen reader support
* **Animation Effects** - Smooth transitions using Motion
* **Custom Pricing Support** - Handles non-standard pricing like "Custom" or "Enterprise"
* **Robust Error Handling** - Graceful handling of invalid pricing data

## Use Cases

* **Plan Upgrades** - Show costs when upgrading to higher-tier plans
* **Plan Downgrades** - Display credits when downgrading plans
* **Billing Cycle Changes** - Handle monthly/yearly billing switches
* **Enterprise Sales** - Support custom pricing and next-cycle changes
* **Billing Transparency** - Provide clear breakdown of charges and credits

## Billing Logic

The component implements sophisticated proration logic:

* **Credits** - Calculated based on unused time in current plan (remaining days, not elapsed)
* **Prorated Charges** - New plan charges based on remaining cycle days
* **Net Amount** - Final charge or credit after calculations
* **Cycle Handling** - Different logic for immediate vs next-cycle changes
* **Price Validation** - Robust parsing of pricing strings with fallbacks
* **Currency Consistency** - Uses current plan currency for credits, new plan currency for charges


# Trial Expiry Card
URL: /docs/components/trial-expiry-card

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.

***

title: Trial Expiry Card
description: 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.

***

<Tabs items={['Preview', 'Code']} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="trial-expiry-card">
      <TrialExpiryCardDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="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>
      );
    }

    ```
  </Tab>
</Tabs>

## Installation

<Tabs items={['shadcn', 'billingSDK']} defaultValue="shadcn" className="bg-transparent border-none">
  <Tab value="shadcn" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="installation-tabs">
      <Tab value="npx">
        ```bash
        npx shadcn@latest add @billingsdk/trial-expiry-card
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @billingsdk/trial-expiry-card
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @billingsdk/trial-expiry-card
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx shadcn@latest add @billingsdk/trial-expiry-card
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab value="billingSDK" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="billingsdk-cli-tabs">
      <Tab value="npx">
        ```bash
        npx @billingsdk/cli add trial-expiry-card
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx @billingsdk/cli add trial-expiry-card
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx @billingsdk/cli add trial-expiry-card
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx @billingsdk/cli add trial-expiry-card
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## Usage

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

### Basic Example with Live Countdown

```tsx
// 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

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

### With Custom Features

```tsx
<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

```tsx
<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

```tsx title="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>
  );
}

```


# Upcoming Charges
URL: /docs/components/upcoming-charges

The Upcoming Charges component displays information about upcoming billing cycles, including the next billing date, total amount, and a breakdown of individual charges.

***

title: Upcoming Charges
description: The Upcoming Charges component displays information about upcoming billing cycles, including the next billing date, total amount, and a breakdown of individual charges.
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

<Tabs items={["Preview", "Code"]} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="upcoming-charges">
      <UpcomingChargesDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/upcoming-charges-demo.tsx"
    "use client";

    import { UpcomingCharges } from "@/components/billingsdk/upcoming-charges";

    export function UpcomingChargesDemo() {
      return (
        <UpcomingCharges
          title="Upcoming Charges"
          description="Your upcoming charges for the next billing period"
          nextBillingDate="November 1, 2025"
          totalAmount="$149.99"
          charges={[
            {
              id: "ch_001",
              description: "Enterprise Plan (Annual)",
              amount: "$119.99",
              date: "Nov 1, 2025",
              type: "recurring",
            },
            {
              id: "ch_002",
              description: "Additional Team Seats (5 seats)",
              amount: "$30.00",
              date: "Nov 1, 2025",
              type: "prorated",
            },
          ]}
        />
      );
    }

    ```
  </Tab>
</Tabs>

## Installation

<Tabs items={['shadcn', 'billingSDK']} defaultValue="shadcn" className="bg-transparent border-none">
  <Tab value="shadcn" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="installation-tabs">
      <Tab value="npx">
        ```bash
        npx shadcn@latest add @billingsdk/upcoming-charges
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @billingsdk/upcoming-charges
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @billingsdk/upcoming-charges
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx shadcn@latest add @billingsdk/upcoming-charges
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab value="billingSDK" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="billingsdk-cli-tabs">
      <Tab value="npx">
        ```bash
        npx @billingsdk/cli add upcoming-charges
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx @billingsdk/cli add upcoming-charges
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx @billingsdk/cli add upcoming-charges
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx @billingsdk/cli add upcoming-charges
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## Usage

```tsx
import { UpcomingCharges } from '@/components/billingsdk/upcoming-charges';
```

```tsx
<UpcomingCharges
	title="Next Billing Cycle"
	description="Your upcoming charges for the next billing period"
	nextBillingDate="Oct 15, 2025"
	totalAmount="$39.50"
	charges={[
		{
			id: '1',
			description: 'Pro Plan (Monthly)',
			amount: '$29.00',
			date: 'Oct 15, 2025',
			type: 'recurring',
		},
		{
			id: '2',
			description: 'Additional Storage (10GB)',
			amount: '$5.00',
			date: 'Oct 15, 2025',
			type: 'prorated',
		},
	]}
/>;
```

## Props

| Prop            | Type           | Description                                      |
| --------------- | -------------- | ------------------------------------------------ |
| className       | `string`       | Additional CSS classes to apply to the component |
| title           | `string`       | Title for the upcoming charges section           |
| description     | `string`       | Description for the upcoming charges section     |
| nextBillingDate | `string`       | Date of the next billing cycle                   |
| totalAmount     | `string`       | Total amount for the next billing cycle          |
| charges         | `ChargeItem[]` | Array of upcoming charges                        |

### ChargeItem Object

| Property    | Type                                      | Description                      |
| ----------- | ----------------------------------------- | -------------------------------- |
| id          | `string`                                  | Unique identifier for the charge |
| description | `string`                                  | Description of the charge        |
| amount      | `string`                                  | Amount of the charge             |
| date        | `string`                                  | Date of the charge               |
| type        | `"prorated" \| "recurring" \| "one-time"` | Type of charge                   |

```tsx
<UpcomingCharges
	title="Upcoming Charges"
	description="Charges for your next billing cycle"
	nextBillingDate="November 1, 2025"
	totalAmount="$149.99"
	charges={[
		{
			id: 'ch_001',
			description: 'Enterprise Plan (Annual)',
			amount: '$119.99',
			date: 'Nov 1, 2025',
			type: 'recurring',
		},
		{
			id: 'ch_002',
			description: 'Additional Team Seats (5 seats)',
			amount: '$30.00',
			date: 'Nov 1, 2025',
			type: 'prorated',
		},
	]}
/>
```

### Credits

* Created by [@sapatmohit](https://github.com/sapatmohit)


# Update Plan Card
URL: /docs/components/update-plan/update-plan-card

The Update Plan Card component provides a compact, card-based interface for users to upgrade or change their subscription plan. It's perfect for embedding in dashboards or sidebars where space is limited.

***

title: Update Plan Card
description: The Update Plan Card component provides a compact, card-based interface for users to upgrade or change their subscription plan. It's perfect for embedding in dashboards or sidebars where space is limited.
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

<Tabs items={['Preview', 'Code']} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="update-plan-card">
      <UpdatePlanCardDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/update-plan-card-demo.tsx"
    "use client";

    import { UpdatePlanCard } from "@/components/billingsdk/update-plan-card";
    import { plans } from "@/lib/billingsdk-config";

    export function UpdatePlanCardDemo() {
      return (
        <main className="flex w-full flex-1 flex-col justify-center text-center">
          <UpdatePlanCard
            currentPlan={plans[0]}
            plans={plans}
            onPlanChange={(planId) => {
              console.log("Upgrade plan to", planId);
            }}
          />
        </main>
      );
    }

    ```
  </Tab>
</Tabs>

## Installation

<Tabs items={['shadcn', 'billingSDK']} defaultValue="shadcn" className="bg-transparent border-none">
  <Tab value="shadcn" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="installation-tabs">
      <Tab value="npx">
        ```bash
        npx shadcn@latest add @billingsdk/update-plan-card
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @billingsdk/update-plan-card
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @billingsdk/update-plan-card
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx shadcn@latest add @billingsdk/update-plan-card
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab value="billingSDK" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="billingsdk-cli-tabs">
      <Tab value="npx">
        ```bash
        npx @billingsdk/cli add update-plan-card
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx @billingsdk/cli add update-plan-card
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx @billingsdk/cli add update-plan-card
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx @billingsdk/cli add update-plan-card
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## Usage

```tsx
import { UpdatePlanCard } from "@/components/billingsdk/update-plan-card";
import { plans } from "@/lib/billingsdk-config";
```

```tsx
<UpdatePlanCard
  currentPlan={plans[0]}
  plans={plans}
  onPlanChange={(planId) => {
    // Handle plan change
    console.log('Plan changed to:', planId);
  }}
  title="Upgrade Your Plan"
/>
```

## Props

| Prop           | Type                       | Required | Description                                         |
| -------------- | -------------------------- | -------- | --------------------------------------------------- |
| `currentPlan`  | `Plan`                     | ✅        | The user's current plan object                      |
| `plans`        | `Plan[]`                   | ✅        | Array of available plans to choose from             |
| `onPlanChange` | `(planId: string) => void` | ✅        | Callback function when a plan is selected           |
| `className`    | `string`                   | ❌        | Additional CSS classes for styling                  |
| `title`        | `string`                   | ❌        | Custom title for the card (default: "Upgrade Plan") |

## Theming

The update plan card component is styled using the `shadcn/ui` library. You can customize the colors and fonts by overriding the CSS variables. You can also get the theme from the [Theming](/docs/theming) page.

## Example

```tsx title="src/components/update-plan-card-demo.tsx"
"use client";

import { UpdatePlanCard } from "@/components/billingsdk/update-plan-card";
import { plans } from "@/lib/billingsdk-config";

export function UpdatePlanCardDemo() {
  return (
    <main className="flex w-full flex-1 flex-col justify-center text-center">
      <UpdatePlanCard
        currentPlan={plans[0]}
        plans={plans}
        onPlanChange={(planId) => {
          console.log("Upgrade plan to", planId);
        }}
      />
    </main>
  );
}

```


# Update Plan Dialog
URL: /docs/components/update-plan/update-plan-dialog

The Update Plan Dialog component provides an interactive interface for users to upgrade or change their subscription plan. It features plan comparison, monthly/yearly toggle, and smooth animations for a seamless user experience.

***

title: Update Plan Dialog
description: The Update Plan Dialog component provides an interactive interface for users to upgrade or change their subscription plan. It features plan comparison, monthly/yearly toggle, and smooth animations for a seamless user experience.
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

<Tabs items={['Preview', 'Code']} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="update-plan-dialog">
      <UpdatePlanDialogDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/update-plan-dialog-demo.tsx"
    "use client";

    import { UpdatePlanDialog } from "@/components/billingsdk/update-plan-dialog";
    import { plans } from "@/lib/billingsdk-config";

    export function UpdatePlanDialogDemo() {
      return (
        <div className="mx-auto flex min-h-[300px] flex-1 flex-col justify-center p-4 text-center">
          <UpdatePlanDialog
            currentPlan={plans[1]}
            plans={plans}
            onPlanChange={(planId) => {
              console.log(planId);
            }}
            triggerText="Update Plan"
          />
        </div>
      );
    }

    ```
  </Tab>
</Tabs>

## Installation

<Tabs items={['shadcn', 'billingSDK']} defaultValue="shadcn" className="bg-transparent border-none">
  <Tab value="shadcn" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="installation-tabs">
      <Tab value="npx">
        ```bash
        npx shadcn@latest add @billingsdk/update-plan-dialog
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @billingsdk/update-plan-dialog
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @billingsdk/update-plan-dialog
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx shadcn@latest add @billingsdk/update-plan-dialog
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab value="billingSDK" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="billingsdk-cli-tabs">
      <Tab value="npx">
        ```bash
        npx @billingsdk/cli add update-plan-dialog
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx @billingsdk/cli add update-plan-dialog
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx @billingsdk/cli add update-plan-dialog
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx @billingsdk/cli add update-plan-dialog
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## Usage

```tsx
import { UpdatePlanDialog } from "@/components/billingsdk/update-plan-dialog";
import { plans } from "@/lib/billingsdk-config";
```

```tsx
<UpdatePlanDialog
  currentPlan={plans[0]}
  plans={plans}
  triggerText="Upgrade Plan"
  onPlanChange={(planId) => {
    // Handle plan change
    console.log('Plan changed to:', planId);
  }}
  title="Choose Your Plan"
/>
```

## Props

| Prop           | Type                       | Required | Description                                           |
| -------------- | -------------------------- | -------- | ----------------------------------------------------- |
| `currentPlan`  | `Plan`                     | ✅        | The user's current plan object                        |
| `plans`        | `Plan[]`                   | ✅        | Array of available plans to choose from               |
| `triggerText`  | `string`                   | ✅        | Text displayed on the trigger button                  |
| `onPlanChange` | `(planId: string) => void` | ✅        | Callback function when a plan is selected             |
| `className`    | `string`                   | ❌        | Additional CSS classes for styling                    |
| `title`        | `string`                   | ❌        | Custom title for the dialog (default: "Upgrade Plan") |

## Theming

The update plan dialog component is styled using the `shadcn/ui` library. You can customize the colors and fonts by overriding the CSS variables. You can also get the theme from the [Theming](/docs/theming) page.

## Example

```tsx title="src/components/update-plan-dialog-demo.tsx"
"use client";

import { UpdatePlanDialog } from "@/components/billingsdk/update-plan-dialog";
import { plans } from "@/lib/billingsdk-config";

export function UpdatePlanDialogDemo() {
  return (
    <div className="mx-auto flex min-h-[300px] flex-1 flex-col justify-center p-4 text-center">
      <UpdatePlanDialog
        currentPlan={plans[1]}
        plans={plans}
        onPlanChange={(planId) => {
          console.log(planId);
        }}
        triggerText="Update Plan"
      />
    </div>
  );
}

```


# Usage Meter Circle
URL: /docs/components/usage-meter/usage-meter-circle

Displays usage progress in a circular meter with an animated ring, status badges, and size variants.

***

title: Usage Meter Circle
description: Displays usage progress in a circular meter with an animated ring, status badges, and size variants.
-----------------------------------------------------------------------------------------------------------------

You can change the progress color of the usage meter to `default` or `usage`.

## Default Usage Meter Circle

<Tabs items={['Preview', 'Code']} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="usage-meter-circle">
      <UsageMeterCircleDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/usage-meter-circle-demo.tsx"
    "use client";

    import { UsageMeter } from "@/components/billingsdk/usage-meter";

    export default function UsageMeterCircleDemo() {
      return (
        <div className="mx-auto flex w-full flex-col gap-4">
          <UsageMeter
            usage={[
              {
                name: "Claude Sonnet 4",
                usage: 75,
                limit: 100,
              },
              {
                name: "ChatGPT 5",
                usage: 12,
                limit: 100,
              },
              {
                name: "Grok 3",
                usage: 57,
                limit: 100,
              },
              {
                name: "Gemini 2.5",
                usage: 95,
                limit: 100,
              },
            ]}
            title="LLM Usage"
            description="Your usage of the LLM models"
            variant="circle"
            size="md"
            className="mx-auto"
          />
        </div>
      );
    }

    ```
  </Tab>
</Tabs>

## Installation

<Tabs items={['shadcn', 'billingSDK']} defaultValue="shadcn" className="bg-transparent border-none">
  <Tab value="shadcn" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="installation-tabs">
      <Tab value="npx">
        ```bash
        npx shadcn@latest add @billingsdk/usage-meter-circle
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @billingsdk/usage-meter-circle
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @billingsdk/usage-meter-circle
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx shadcn@latest add @billingsdk/usage-meter-circle
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab value="billingSDK" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="billingsdk-cli-tabs">
      <Tab value="npx">
        ```bash
        npx @billingsdk/cli add usage-meter-circle
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx @billingsdk/cli add usage-meter-circle
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx @billingsdk/cli add usage-meter-circle
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx @billingsdk/cli add usage-meter-circle
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## Custom Usage Meter Circle

<Tabs items={['Preview', 'Code']} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="usage-meter-circle">
      <CustomUsageMeterCircleDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/custom-usage-meter-circle-demo.tsx"
    "use client";

    import { UsageMeter } from "@/components/billingsdk/usage-meter";

    export default function CustomUsageMeterCircleDemo() {
      return (
        <div className="mx-auto flex w-full flex-col gap-4">
          <UsageMeter
            usage={[
              {
                name: "Claude Sonnet 4",
                usage: 75,
                limit: 100,
              },
              {
                name: "ChatGPT 5",
                usage: 12,
                limit: 100,
              },
              {
                name: "Grok 3",
                usage: 57,
                limit: 100,
              },
              {
                name: "Gemini 2.5",
                usage: 95,
                limit: 100,
              },
            ]}
            title="LLM Usage"
            description="Your usage of the LLM models"
            variant="circle"
            size="md"
            className="mx-auto"
            progressColor="usage"
          />
        </div>
      );
    }

    ```
  </Tab>
</Tabs>

## Usage

```tsx
import { UsageMeter } from "@/components/billingsdk/usage-meter";
```

```tsx
// Default Usage Meter Circle
<UsageMeter
  usage={75}
  limit={100}
  title="Usage"
  description="You have used 75% of your limit"
  variant="circle"
  size="md"
  className="mx-auto"
  progressColor="default" // default, usage
/>

// Custom Usage Meter Circle
<UsageMeter
  usage={75}
  limit={100}
  title="Usage"
  description="You have used 75% of your limit"
  variant="circle"
  size="md"
  className="mx-auto"
  progressColor="usage" // default, usage
/>
```

## Props

| Prop            | Type                   | Required | Description                                    |
| --------------- | ---------------------- | -------- | ---------------------------------------------- |
| `usage`         | `number`               | ✅        | The usage of the user                          |
| `limit`         | `number`               | ✅        | The limit of the user                          |
| `className`     | `string`               | ❌        | Additional CSS classes for styling             |
| `title`         | `string`               | ❌        | Custom title for the usage meter               |
| `description`   | `string`               | ❌        | Custom description for the usage meter         |
| `variant`       | `"linear" \| "circle"` | ❌        | Variant of the usage meter (default: "linear") |
| `size`          | `"sm" \| "md" \| "lg"` | ❌        | Size of the usage meter (default: "md")        |
| `progressColor` | `"default" \| "usage"` | ❌        | Color of the progress bar (default: "default") |

## Theming

The usage meter circle component is styled using the `shadcn/ui` library. You can customize the colors and fonts by overriding the CSS variables. You can also get the theme from the [Theming](/docs/theming) page.

## Example

```tsx title="src/components/usage-meter-circle-demo.tsx"
"use client";

import { UsageMeter } from "@/components/billingsdk/usage-meter";

export default function UsageMeterCircleDemo() {
  return (
    <div className="mx-auto flex w-full flex-col gap-4">
      <UsageMeter
        usage={[
          {
            name: "Claude Sonnet 4",
            usage: 75,
            limit: 100,
          },
          {
            name: "ChatGPT 5",
            usage: 12,
            limit: 100,
          },
          {
            name: "Grok 3",
            usage: 57,
            limit: 100,
          },
          {
            name: "Gemini 2.5",
            usage: 95,
            limit: 100,
          },
        ]}
        title="LLM Usage"
        description="Your usage of the LLM models"
        variant="circle"
        size="md"
        className="mx-auto"
      />
    </div>
  );
}

```


# Usage Meter Linear
URL: /docs/components/usage-meter/usage-meter-linear

Displays usage progress with an animated linear bar, remaining quota, status badges, and size variants..

***

title: Usage Meter Linear
description: Displays usage progress with an animated linear bar, remaining quota, status badges, and size variants..
---------------------------------------------------------------------------------------------------------------------

You can change the progress color of the usage meter to `default` or `usage`.

## Default Usage Meter Linear

<Tabs items={['Preview', 'Code']} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="usage-meter-circle">
      <UsageMeterLinearDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/usage-meter-linear-demo.tsx"
    "use client";

    import { UsageMeter } from "@/components/billingsdk/usage-meter";

    export default function UsageMeterLinearDemo() {
      return (
        <div className="mx-auto flex w-full flex-col gap-4">
          <UsageMeter
            usage={[
              {
                name: "Claude Sonnet 4",
                usage: 75,
                limit: 100,
              },
              {
                name: "ChatGPT 5",
                usage: 12,
                limit: 100,
              },
              {
                name: "Grok 3",
                usage: 57,
                limit: 100,
              },
              {
                name: "Gemini 2.5",
                usage: 95,
                limit: 100,
              },
            ]}
            title="LLM Usage"
            description="Your usage of the LLM models"
            variant="linear"
            size="md"
            className="mx-auto"
          />
        </div>
      );
    }

    ```
  </Tab>
</Tabs>

## Installation

<Tabs items={['shadcn', 'billingSDK']} defaultValue="shadcn" className="bg-transparent border-none">
  <Tab value="shadcn" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="installation-tabs">
      <Tab value="npx">
        ```bash
        npx shadcn@latest add @billingsdk/usage-meter-linear
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @billingsdk/usage-meter-linear
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @billingsdk/usage-meter-linear
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx shadcn@latest add @billingsdk/usage-meter-linear
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab value="billingSDK" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="billingsdk-cli-tabs">
      <Tab value="npx">
        ```bash
        npx @billingsdk/cli add usage-meter-linear
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx @billingsdk/cli add usage-meter-linear
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx @billingsdk/cli add usage-meter-linear
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx @billingsdk/cli add usage-meter-linear
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## Custom Usage Meter Linear

<Tabs items={['Preview', 'Code']} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="usage-meter-circle">
      <CustomUsageMeterLinearDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/custom-usage-meter-linear-demo.tsx"
    "use client";

    import { UsageMeter } from "@/components/billingsdk/usage-meter";

    export default function CustomUsageMeterLinearDemo() {
      return (
        <div className="mx-auto flex w-full flex-col gap-4">
          <UsageMeter
            usage={[
              {
                name: "Claude Sonnet 4",
                usage: 75,
                limit: 100,
              },
              {
                name: "ChatGPT 5",
                usage: 12,
                limit: 100,
              },
              {
                name: "Grok 3",
                usage: 57,
                limit: 100,
              },
              {
                name: "Gemini 2.5",
                usage: 95,
                limit: 100,
              },
            ]}
            title="LLM Usage"
            description="Your usage of the LLM models"
            variant="linear"
            size="md"
            className="mx-auto"
            progressColor="usage"
          />
        </div>
      );
    }

    ```
  </Tab>
</Tabs>

## Usage

```tsx
import { UsageMeter } from "@/components/billingsdk/usage-meter";
```

```tsx
// Default Usage Meter Linear
<UsageMeter
  usage={75}
  limit={100}
  title="Usage"
  description="You have used 75% of your limit"
  variant="linear"
  size="md"
  className="mx-auto"
  progressColor="default" // default, usage
/>

// Custom Usage Meter Linear
<UsageMeter
  usage={75}
  limit={100}
  title="Usage"
  description="You have used 75% of your limit"
  variant="circle"
  size="md"
  className="mx-auto"
  progressColor="usage" // default, usage
/>
```

## Props

| Prop            | Type                   | Required | Description                                    |
| --------------- | ---------------------- | -------- | ---------------------------------------------- |
| `usage`         | `number`               | ✅        | The usage of the user                          |
| `limit`         | `number`               | ✅        | The limit of the user                          |
| `className`     | `string`               | ❌        | Additional CSS classes for styling             |
| `title`         | `string`               | ❌        | Custom title for the usage meter               |
| `description`   | `string`               | ❌        | Custom description for the usage meter         |
| `variant`       | `"linear" \| "circle"` | ❌        | Variant of the usage meter (default: "linear") |
| `size`          | `"sm" \| "md" \| "lg"` | ❌        | Size of the usage meter (default: "md")        |
| `progressColor` | `"default" \| "usage"` | ❌        | Color of the progress bar (default: "default") |

## Theming

The usage meter circle component is styled using the `shadcn/ui` library. You can customize the colors and fonts by overriding the CSS variables. You can also get the theme from the [Theming](/docs/theming) page.

## Example

```tsx title="src/components/usage-meter-linear-demo.tsx"
"use client";

import { UsageMeter } from "@/components/billingsdk/usage-meter";

export default function UsageMeterLinearDemo() {
  return (
    <div className="mx-auto flex w-full flex-col gap-4">
      <UsageMeter
        usage={[
          {
            name: "Claude Sonnet 4",
            usage: 75,
            limit: 100,
          },
          {
            name: "ChatGPT 5",
            usage: 12,
            limit: 100,
          },
          {
            name: "Grok 3",
            usage: 57,
            limit: 100,
          },
          {
            name: "Gemini 2.5",
            usage: 95,
            limit: 100,
          },
        ]}
        title="LLM Usage"
        description="Your usage of the LLM models"
        variant="linear"
        size="md"
        className="mx-auto"
      />
    </div>
  );
}

```


# Usage Table
URL: /docs/components/usage-table

Per-model LLM usage with token counts, cache reads, and API cost.

***

title: Usage Table
description: Per-model LLM usage with token counts, cache reads, and API cost.
------------------------------------------------------------------------------

<Tabs items={['Preview', 'Code']} className="bg-transparent border-none">
  <Tab value="Preview" className="border-none bg-transparent p-0 mt-3">
    <PreviewComponents registryName="usage-table">
      <UsageTableDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/usage-table-demo.tsx"
    import { UsageTable, type UsageItem } from "@/registry/billingsdk/usage-table";

    export default function UsageTableDemo() {
      const usageHistory: UsageItem[] = [
        {
          model: "gpt-5",
          inputWithCache: 0,
          inputWithoutCache: 518131,
          cacheRead: 1646080,
          output: 103271,
          totalTokens: 2267482,
        },
        {
          model: "claude-3.5-sonnet",
          inputWithCache: 176177,
          inputWithoutCache: 28413,
          cacheRead: 434612,
          output: 8326,
          totalTokens: 647528,
          costToYou: 1.0,
        },
        {
          model: "gemini-2.0-flash-exp",
          inputWithCache: 176100,
          inputWithoutCache: 28432,
          cacheRead: 434612,
          output: 8326,
          totalTokens: 647528,
          apiCost: 1,
          costToYou: 0,
        },
        {
          model: "gemini-2.5-pro",
          inputWithCache: 176177,
          inputWithoutCache: 28413,
          cacheRead: 434612,
          output: 7000,
          totalTokens: 647528,
          apiCost: 1,
          costToYou: 0,
        },
        {
          model: "claude-4-sonnet",
          inputWithCache: 68415,
          inputWithoutCache: 902,
          cacheRead: 864450,
          output: 12769,
          totalTokens: 946536,
          apiCost: 0.71,
          costToYou: 0.71,
        },
        {
          model: "claude-3.7-sonnet",
          inputWithCache: 68415,
          inputWithoutCache: 902,
          cacheRead: 864450,
          output: 12769,
          totalTokens: 946536,
          apiCost: 0.71,
        },
        {
          model: "auto",
          inputWithCache: 84551,
          inputWithoutCache: 0,
          cacheRead: 284876,
          output: 9458,
          totalTokens: 378885,
          apiCost: 0.23,
          costToYou: 0,
        },
        {
          model: "sonic",
          inputWithCache: 0,
          inputWithoutCache: 149484,
          cacheRead: 4354855,
          output: 23569,
          totalTokens: 4527908,
          costToYou: 2,
        },
      ];

      return (
        <UsageTable
          title="Usage Summary"
          usageHistory={usageHistory}
          showTotal={true}
          description="Per-model LLM usage with token counts, cache reads, and API cost."
        />
      );
    }

    ```
  </Tab>
</Tabs>

## Installation

<Tabs items={['shadcn', 'billingSDK']} defaultValue="shadcn" className="bg-transparent border-none">
  <Tab value="shadcn" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="installation-tabs">
      <Tab value="npx">
        ```bash
        npx shadcn@latest add @billingsdk/usage-table
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @billingsdk/usage-table
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @billingsdk/usage-table
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx shadcn@latest add @billingsdk/usage-table
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab value="billingSDK" className="border-none bg-transparent p-0 mt-3">
    <Tabs items={['npx', 'pnpm', 'yarn', 'bun']} defaultValue="npx" groupId="billingsdk-cli-tabs">
      <Tab value="npx">
        ```bash
        npx @billingsdk/cli add usage-table
        ```
      </Tab>

      <Tab value="pnpm">
        ```bash
        pnpm dlx @billingsdk/cli add usage-table
        ```
      </Tab>

      <Tab value="yarn">
        ```bash
        yarn dlx @billingsdk/cli add usage-table
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        bunx @billingsdk/cli add usage-table
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## Usage

```tsx
import { UsageTable, type UsageItem } from "@/components/billingsdk/usage-table";
```

```tsx
const usageHistory: UsageItem[] = [
    {
      model: 'gpt-5',
      inputWithCache: 0,
      inputWithoutCache: 518131,
      cacheRead: 1646080,
      output: 103271,
      totalTokens: 2267482,
    },
    {
      model: 'claude-3.5-sonnet',
      inputWithCache: 176177,
      inputWithoutCache: 28413,
      cacheRead: 434612,
      output: 8326,
      totalTokens: 647528,
      costToYou: 1.00
    },
    {
      model: 'gemini-2.0-flash-exp',
      inputWithCache: 176100,
      inputWithoutCache: 28432,
      cacheRead: 434612,
      output: 8326,
      totalTokens: 647528,
      apiCost: 1,
      costToYou: 0
    },
    {
      model: 'gemini-2.5-pro',
      inputWithCache: 176177,
      inputWithoutCache: 28413,
      cacheRead: 434612,
      output: 7000,
      totalTokens: 647528,
      apiCost: 1,
      costToYou: 0
    },
    {
      model: 'claude-4-sonnet',
      inputWithCache: 68415,
      inputWithoutCache: 902,
      cacheRead: 864450,
      output: 12769,
      totalTokens: 946536,
      apiCost: 0.71,
      costToYou: 0.71
    },
    {
      model: 'claude-3.7-sonnet',
      inputWithCache: 68415,
      inputWithoutCache: 902,
      cacheRead: 864450,
      output: 12769,
      totalTokens: 946536,
      apiCost: 0.71,
    },
    {
      model: 'auto',
      inputWithCache: 84551,
      inputWithoutCache: 0,
      cacheRead: 284876,
      output: 9458,
      totalTokens: 378885,
      apiCost: 0.23,
      costToYou: 0
    },
    {
      model: 'sonic',
      inputWithCache: 0,
      inputWithoutCache: 149484,
      cacheRead: 4354855,
      output: 23569,
      totalTokens: 4527908,
      costToYou: 2
    }
];
```

```tsx
  <UsageTable 
    title="Usage Summary"
    usageHistory={usageHistory}
    showTotal={true}
    description="Per-model LLM usage with token counts, cache reads, and API cost."
  />
```

## Props

| Prop           | Type          | Required | Description                        |
| -------------- | ------------- | -------- | ---------------------------------- |
| `usageHistory` | `UsageItem[]` | ✅        | List of usage to display           |
| `className`    | `string`      | ❌        | Additional CSS classes for styling |
| `title`        | `string`      | ❌        | Optional heading text              |
| `description`  | `string`      | ❌        | Optional description text          |
| `showTotal`    | `boolean`     | ❌        | Show total row (default: true)     |

## UsageItem

```ts
interface UsageItem {
  model: string
  inputWithCache: number
  inputWithoutCache: number
  cacheRead: number
  output: number
  totalTokens: number
  apiCost?: number
  costToYou?: number
}
```

### Credits

* Created by [@vamsisai696](https://x.com/vamsisai696)