# Usage Meter Circle
URL: /docs/components/usage-meter/usage-meter-circle

Displays usage progress in a circular meter with an animated ring, status badges, and size variants.

***

title: Usage Meter Circle
description: Displays usage progress in a circular meter with an animated ring, status badges, and size variants.
-----------------------------------------------------------------------------------------------------------------

You can change the progress color of the usage meter to `default` or `usage`.

## Default Usage Meter Circle

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

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

    import { UsageMeter } from "@/components/billingsdk/usage-meter";

    export default function UsageMeterCircleDemo() {
      return (
        <div className="mx-auto flex w-full flex-col gap-4">
          <UsageMeter
            usage={[
              {
                name: "Claude Sonnet 4",
                usage: 75,
                limit: 100,
              },
              {
                name: "ChatGPT 5",
                usage: 12,
                limit: 100,
              },
              {
                name: "Grok 3",
                usage: 57,
                limit: 100,
              },
              {
                name: "Gemini 2.5",
                usage: 95,
                limit: 100,
              },
            ]}
            title="LLM Usage"
            description="Your usage of the LLM models"
            variant="circle"
            size="md"
            className="mx-auto"
          />
        </div>
      );
    }

    ```
  </Tab>
</Tabs>

## Installation

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

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

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

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

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

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

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

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

## Custom Usage Meter Circle

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

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

    import { UsageMeter } from "@/components/billingsdk/usage-meter";

    export default function CustomUsageMeterCircleDemo() {
      return (
        <div className="mx-auto flex w-full flex-col gap-4">
          <UsageMeter
            usage={[
              {
                name: "Claude Sonnet 4",
                usage: 75,
                limit: 100,
              },
              {
                name: "ChatGPT 5",
                usage: 12,
                limit: 100,
              },
              {
                name: "Grok 3",
                usage: 57,
                limit: 100,
              },
              {
                name: "Gemini 2.5",
                usage: 95,
                limit: 100,
              },
            ]}
            title="LLM Usage"
            description="Your usage of the LLM models"
            variant="circle"
            size="md"
            className="mx-auto"
            progressColor="usage"
          />
        </div>
      );
    }

    ```
  </Tab>
</Tabs>

## Usage

```tsx
import { UsageMeter } from "@/components/billingsdk/usage-meter";
```

```tsx
// Default Usage Meter Circle
<UsageMeter
  usage={75}
  limit={100}
  title="Usage"
  description="You have used 75% of your limit"
  variant="circle"
  size="md"
  className="mx-auto"
  progressColor="default" // default, usage
/>

// Custom Usage Meter Circle
<UsageMeter
  usage={75}
  limit={100}
  title="Usage"
  description="You have used 75% of your limit"
  variant="circle"
  size="md"
  className="mx-auto"
  progressColor="usage" // default, usage
/>
```

## Props

| Prop            | Type                   | Required | Description                                    |
| --------------- | ---------------------- | -------- | ---------------------------------------------- |
| `usage`         | `number`               | ✅        | The usage of the user                          |
| `limit`         | `number`               | ✅        | The limit of the user                          |
| `className`     | `string`               | ❌        | Additional CSS classes for styling             |
| `title`         | `string`               | ❌        | Custom title for the usage meter               |
| `description`   | `string`               | ❌        | Custom description for the usage meter         |
| `variant`       | `"linear" \| "circle"` | ❌        | Variant of the usage meter (default: "linear") |
| `size`          | `"sm" \| "md" \| "lg"` | ❌        | Size of the usage meter (default: "md")        |
| `progressColor` | `"default" \| "usage"` | ❌        | Color of the progress bar (default: "default") |

## Theming

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

## Example

```tsx title="src/components/usage-meter-circle-demo.tsx"
"use client";

import { UsageMeter } from "@/components/billingsdk/usage-meter";

export default function UsageMeterCircleDemo() {
  return (
    <div className="mx-auto flex w-full flex-col gap-4">
      <UsageMeter
        usage={[
          {
            name: "Claude Sonnet 4",
            usage: 75,
            limit: 100,
          },
          {
            name: "ChatGPT 5",
            usage: 12,
            limit: 100,
          },
          {
            name: "Grok 3",
            usage: 57,
            limit: 100,
          },
          {
            name: "Gemini 2.5",
            usage: 95,
            limit: 100,
          },
        ]}
        title="LLM Usage"
        description="Your usage of the LLM models"
        variant="circle"
        size="md"
        className="mx-auto"
      />
    </div>
  );
}

```