# 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
```

## 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>

## `@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 or Express.js)
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) or Express.js (Node.js web framework)
* **Payment Provider**: Dodo Payments

### Generated Files

After running `init`, you'll get:

<Tabs items={['Next.js + Dodo Payments', 'Express.js + 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/
    ├── src/
    │   ├── lib/
    │   │   └── dodopayments.ts
    │   └── routes/
    │       └── dodopayments/
    │           ├── route.ts
    │           ├── 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

### Dependencies Installed

<Tabs items={['Next.js', 'Express.js']}>
  <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>
</Tabs>

<Callout title="Environment Setup">
  After running `init`, copy `.env.example` to `.env.local` (Next.js) or `.env` (Express.js) and configure your Dodo Payments API keys and webhook secrets.
</Callout>

## Express.js Setup Instructions

### 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
```

### Available API Endpoints

The Express.js template provides these endpoints:

* `POST /api/dodopayments/checkout` - Create checkout sessions
* `GET /api/dodopayments/customer` - Retrieve customer data
* `POST /api/dodopayments/customer` - Create new customers
* `PUT /api/dodopayments/customer` - Update customer information
* `GET /api/dodopayments/customer/subscriptions` - Get customer subscriptions
* `GET /api/dodopayments/customer/payments` - Get customer payment history
* `GET /api/dodopayments/products` - List all products
* `GET /api/dodopayments/product` - Get specific product details
* `GET /api/dodopayments/subscriptions` - Retrieve subscription details
* `GET /api/dodopayments/payments` - Get payment information
* `POST /api/dodopayments/webhook` - Handle DodoPayments webhooks

### 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"
  }
}
```

## `@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>

## Supported Frameworks

### Next.js (App Router)

* ✅ **Status**: Fully supported
* 📁 **Structure**: App Router with API routes
* 🔧 **Features**: Server components, server actions, middleware support

### Express.js

* ✅ **Status**: Fully supported
* 📁 **Structure**: Modular route-based architecture
* 🔧 **Features**: RESTful API routes, middleware support, TypeScript integration

### Coming Soon

* 🚧 **Fastify**: High-performance backend framework
* 🚧 **Additional React Frameworks**: Vite, Remix support

## Supported Payment Providers

### Dodo Payments

* ✅ **Status**: Fully supported
* 🔧 **Features**: Payment processing, subscriptions, webhooks
* 📚 **Integration**: Complete API route templates included

### Coming Soon

* 🚧 **Stripe**: Industry-standard payment processing
* 🚧 **Additional Providers**: Based on community demand

## Configuration

### Environment Variables

After running `@billingsdk/cli init`, configure these environment variables:

```bash
# Dodo Payments Configuration
DODO_PAYMENTS_API_KEY=your-api-key
DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
DODO_PAYMENTS_RETURN_URL=https://yourdomain.com/checkout/success
DODO_PAYMENTS_ENVIRONMENT="test"or"live"

# Next.js Configuration
NEXT_PUBLIC_APP_URL=http://localhost:3000
```

### Customizing Templates

The CLI uses templates from the public registry. You can:

* Modify generated files after installation
* Create custom templates for your organization
* Extend existing components with additional features

## 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)!

<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)!
</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
        npx shadcn@latest add @billingsdk/pricing-table-one
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        npx 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
        npx @billingsdk/cli add pricing-table-one
        ```
      </Tab>

      <Tab value="bun">
        ```bash
        npx @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
    npx @billingsdk/cli init
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    npx @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 |

### 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            |

### Payment Processing

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

| Component                                                               | Description                                                                                   |
| ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| **[Payment Method Selector](/docs/components/payment-method-selector)** | Interactive payment method selector supporting cards, digital wallets, UPI, and BNPL services |
| **[Payment Method Manager](/docs/components/payment-method-manager)**   | Complete UI for managing billing payment methods (credit card, ACH) with CRUD and validation  |
| **[Payment Success Dialog](/docs/components/payment-success-dialog)**   | Dialog for successful payment during checkout flow                                            |

### 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             |

### Usage Analytics

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

| Component                                                                 | Description                                                         |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| **[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  |

### 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`, or `popup`.

## 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="w-full h-full flex flex-col gap-6 min-h-[500px] rounded-lg overflow-hidden bg-background-secondary 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 text-center gap-4 py-16">
                    <h1 className="text-3xl font-bold tracking-tight text-foreground-secondary">
                        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="underline underline-offset-4 hover:text-primary 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']} 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
        npx 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']} 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
        npx @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="w-full h-full flex flex-col gap-6 min-h-[500px] border rounded-lg overflow-hidden bg-background-secondary 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 text-center gap-4 py-16">
                    <h1 className="text-3xl font-bold tracking-tight text-foreground-secondary">
                        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="underline underline-offset-4 hover:text-primary 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="w-full h-full flex flex-col gap-4 min-h-[500px] justify-center items-center border rounded-lg">
                {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="w-full h-full justify-center items-center flex flex-row 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="w-full h-full flex flex-col gap-6 min-h-[500px] rounded-lg overflow-hidden bg-background-secondary 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 text-center gap-4 py-16">
            <h1 className="text-3xl font-bold tracking-tight text-foreground-secondary">
              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="underline underline-offset-4 hover:text-primary 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" // destructive
/>
```

## 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"` | ✅        | 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="w-full h-full flex flex-col gap-6 min-h-[500px] rounded-lg overflow-hidden bg-background-secondary 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 text-center gap-4 py-16">
                <h1 className="text-3xl font-bold tracking-tight text-foreground-secondary">
                    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="underline underline-offset-4 hover:text-primary transition"
                    >
                        Get Started →
                    </a>
                </div>
            </section>
        </div>
    )
}

```


# 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 flex-col w-full">
          <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']} 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
        npx 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']} 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
        npx @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 flex-col w-full">
      <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="flex flex-1 flex-col justify-center text-center p-4 mx-auto min-h-[300px]">
          <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']} 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
        npx 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']} 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
        npx @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="flex flex-1 flex-col justify-center text-center p-4 mx-auto min-h-[300px]">
      <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>
    )
}
```


# 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']} 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
        npx 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']} 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
        npx @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)


# 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="max-w-2xl mx-auto"
                    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-processing/payment-success-dialog)

## 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']} 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
        npx shadcn@latest add @billingsdk/subscription-management
        ```
      </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 subscription-management
        ```
      </Tab>

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

      <Tab value="yarn">
        ```bash
        npx @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";
```

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

```tsx
<SubscriptionManagement
  className="max-w-2xl mx-auto"
  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="max-w-2xl mx-auto"
                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>
    );
}

```


# Payment Method Manager
URL: /docs/components/payment-method-manager

The Payment Method Manager component provides a PCI-compliant UI for managing billing payment methods. Uses redirect-to-gateway approach for secure add/edit operations with no direct handling of sensitive data.

***

title: Payment Method Manager
description: The Payment Method Manager component provides a PCI-compliant UI for managing billing payment methods. Uses redirect-to-gateway approach for secure add/edit operations with no direct handling of sensitive data.
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

<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-manager">
      <PaymentMethodManagerDemo />
    </PreviewComponents>
  </Tab>

  <Tab value="Code" className="mt-3">
    ```tsx title="src/components/payment-method-manager-demo.tsx"


    "use client"

    import React, { useState } from "react";
    import { PaymentMethodManager, PaymentMethod } from "@/components/billingsdk/payment-method-manager";

    const initialMethods: PaymentMethod[] = [
      {
        id: "pm1",
        type: "credit",
        last4: "1234",
        expiry: "12/25",
        isDefault: true,
      },
      {
        id: "pm2",
        type: "ach",
        last4: "5678",
        expiry: undefined,
        isDefault: false,
        routing: "123456789",
      },
      {
        id: "pm3",
        type: "credit",
        last4: "4321",
        expiry: "11/27",
        isDefault: false,
      },
    ];

    export function PaymentMethodManagerDemo() {
      const [paymentMethods, setPaymentMethods] = useState<PaymentMethod[]>(initialMethods);

      const handleAdd = (method: PaymentMethod) => {
        setPaymentMethods((prev) => [...prev, method]);
      };

      const handleEdit = (updated: PaymentMethod) => {
        setPaymentMethods((prev) => prev.map((pm) => pm.id === updated.id ? updated : pm));
      };

      const handleRemove = (id: string) => {
        setPaymentMethods((prev) => prev.filter((pm) => pm.id !== id));
      };

      const handleSetDefault = (id: string) => {
        setPaymentMethods((prev) => prev.map((pm) => ({ ...pm, isDefault: pm.id === id })));
      };

      const handleRedirect = (type: 'add' | 'edit', methodId?: string) => {
        console.log("Redirecting...", { type, methodId });
      };

      return (
        <PaymentMethodManager
          paymentMethods={paymentMethods}
          onAdd={handleAdd}
          onEdit={handleEdit}
          onRemove={handleRemove}
          onSetDefault={handleSetDefault}
          onRedirect={handleRedirect}
          className="w-full"
        />
      );
    }

    ```
  </Tab>
</Tabs>

## Installation

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

  <Tab value="pnpm">
    ```bash
    pnpm dlx shadcn@latest add @billingsdk/payment-method-manager
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    npx shadcn@latest add @billingsdk/payment-method-manager
    ```
  </Tab>
</Tabs>

## Usage

```tsx
import { PaymentMethodManager, type PaymentMethod } from "@/components/billingsdk/payment-method-manager";
```

```tsx
const [paymentMethods, setPaymentMethods] = useState<PaymentMethod[]>([
  {
    id: 'pm_1',
    type: 'credit',
    last4: '4242',
    expiry: '12/25',
    isDefault: true,
  },
  {
    id: 'pm_2',
    type: 'ach',
    last4: '1234',
    isDefault: false,
    routing: '021000021',
  },
]);
```

```tsx
<PaymentMethodManager
  className="max-w-4xl mx-auto"
  paymentMethods={paymentMethods}
  onAdd={(method) => setPaymentMethods([...paymentMethods, method])}
  onEdit={(method) => setPaymentMethods(paymentMethods.map(pm => pm.id === method.id ? method : pm))}
  onRemove={(id) => setPaymentMethods(paymentMethods.filter(pm => pm.id !== id))}
  onSetDefault={(id) => setPaymentMethods(paymentMethods.map(pm => ({ ...pm, isDefault: pm.id === id })))}
  onRedirect={(type, methodId) => {
    // Redirect to payment gateway (e.g., Stripe, Razorpay)
    console.log("Redirecting to gateway:", { type, methodId });
  }}
/>
```

## Props

| Prop             | Type                                                 | Required | Description                                                                   |
| ---------------- | ---------------------------------------------------- | -------- | ----------------------------------------------------------------------------- |
| `className`      | `string`                                             | ❌        | Additional CSS classes for styling                                            |
| `paymentMethods` | `PaymentMethod[]`                                    | ✅        | Array of payment methods to display                                           |
| `onAdd`          | `(method: PaymentMethod) => void`                    | ❌        | Callback when a new payment method is added                                   |
| `onEdit`         | `(method: PaymentMethod) => void`                    | ❌        | Callback when a payment method is edited                                      |
| `onRemove`       | `(id: string) => void`                               | ❌        | Callback when a payment method is removed                                     |
| `onSetDefault`   | `(id: string) => void`                               | ❌        | Callback to set a payment method as default                                   |
| `onRedirect`     | `(type: 'add' \| 'edit', methodId?: string) => void` | ✅        | Callback to redirect to payment gateway for PCI-compliant add/edit operations |

## PaymentMethod Interface

```tsx
interface PaymentMethod {
  id: string;
  type: 'credit' | 'ach';
  last4: string;
  expiry?: string; // Required for credit cards (MM/YY format)
  isDefault: boolean;
  routing?: string; // Required for ACH accounts
}
```

## Theming

The Payment Method Manager 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/payment-method-manager-demo.tsx"


"use client"

import React, { useState } from "react";
import { PaymentMethodManager, PaymentMethod } from "@/components/billingsdk/payment-method-manager";

const initialMethods: PaymentMethod[] = [
  {
    id: "pm1",
    type: "credit",
    last4: "1234",
    expiry: "12/25",
    isDefault: true,
  },
  {
    id: "pm2",
    type: "ach",
    last4: "5678",
    expiry: undefined,
    isDefault: false,
    routing: "123456789",
  },
  {
    id: "pm3",
    type: "credit",
    last4: "4321",
    expiry: "11/27",
    isDefault: false,
  },
];

export function PaymentMethodManagerDemo() {
  const [paymentMethods, setPaymentMethods] = useState<PaymentMethod[]>(initialMethods);

  const handleAdd = (method: PaymentMethod) => {
    setPaymentMethods((prev) => [...prev, method]);
  };

  const handleEdit = (updated: PaymentMethod) => {
    setPaymentMethods((prev) => prev.map((pm) => pm.id === updated.id ? updated : pm));
  };

  const handleRemove = (id: string) => {
    setPaymentMethods((prev) => prev.filter((pm) => pm.id !== id));
  };

  const handleSetDefault = (id: string) => {
    setPaymentMethods((prev) => prev.map((pm) => ({ ...pm, isDefault: pm.id === id })));
  };

  const handleRedirect = (type: 'add' | 'edit', methodId?: string) => {
    console.log("Redirecting...", { type, methodId });
  };

  return (
    <PaymentMethodManager
      paymentMethods={paymentMethods}
      onAdd={handleAdd}
      onEdit={handleEdit}
      onRemove={handleRemove}
      onSetDefault={handleSetDefault}
      onRedirect={handleRedirect}
      className="w-full"
    />
  );
}

```

## Credits

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


# 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="w-full max-w-md mx-auto min-h-[600px] flex 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']} 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
        npx 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']} 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
        npx @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="w-full max-w-md mx-auto min-h-[600px] flex 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="p-6 flex flex-col gap-4">
            <div className="text-sm text-muted-foreground">
              Click the button to preview the success dialog.
            </div>
            <button className="px-3 py-2 rounded-md border 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']} 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
        npx 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']} 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
        npx @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="p-6 flex flex-col gap-4">
        <div className="text-sm text-muted-foreground">
          Click the button to preview the success dialog.
        </div>
        <button className="px-3 py-2 rounded-md border 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 Four
URL: /docs/components/pricing-table/pricing-table-four

The Pricing Table Four 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 Four
description: The Pricing Table Four 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-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"
                description="Transform your project with our comprehensive pricing options designed for every need."
                onPlanSelect={(planId: string) => console.log('Selected plan:', planId)}
                size="medium"
                className="w-full"
            />
        )
    }
    ```
  </Tab>
</Tabs>

## Installation

<Tabs items={['npx', 'pnpm', 'yarn']} 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
    npx shadcn@latest add @billingsdk/pricing-table-four
    ```
  </Tab>
</Tabs>

## Usage

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

<PricingTableFour 
  plans={plans}
  title="Choose Your Plan"
  description="Select the perfect plan for your needs. Upgrade or downgrade anytime."
  onPlanSelect={(planId) => console.log('Selected plan:', planId)}
  size="medium"
/>
```

## 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                                              |

## Features

* **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
* **Customizable Sizing**: Small, medium, and large size variants

## 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"
            description="Transform your project with our comprehensive pricing options designed for every need."
            onPlanSelect={(planId: string) => console.log('Selected plan:', planId)}
            size="medium"
            className="w-full"
        />
    )
}
```

### Credits

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


# 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']} 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
        npx 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']} 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
        npx @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 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={"w-full max-w-4xl mx-auto"}
                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']} 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
        npx 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']} 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
        npx @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={"w-full max-w-4xl mx-auto"}
            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="w-full max-w-4xl mx-auto"
                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="w-full max-w-4xl mx-auto"
                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']} 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
        npx 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']} 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
        npx @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="w-full max-w-4xl mx-auto"
            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
        />
    </>
} 
```


# 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 flex-1 flex-col justify-center text-center w-full">
                <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']} 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
        npx 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']} 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
        npx @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 flex-1 flex-col justify-center text-center w-full">
            <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="flex flex-1 flex-col justify-center text-center p-4 mx-auto min-h-[300px]">
          <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']} 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
        npx 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']} 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
        npx @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="flex flex-1 flex-col justify-center text-center p-4 mx-auto min-h-[300px]">
      <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="flex flex-col gap-4 mx-auto w-full">
          <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']} 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
        npx 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']} 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
        npx @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="flex flex-col gap-4 mx-auto w-full">
          <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="flex flex-col gap-4 mx-auto w-full">
      <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="flex flex-col gap-4 mx-auto w-full">
          <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']} 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
        npx 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']} 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
        npx @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="flex flex-col gap-4 mx-auto w-full">
            <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="flex flex-col gap-4 mx-auto w-full">
      <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.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
        }
      ];


      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']} 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
        npx 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']} 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
        npx @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)