# Usage Monitor

Real-time dashboard with diamond header, progress metrics, burn rate, predictions, and status bar



<ComponentPreview base="opentui" name="usage-monitor-demo" />

Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    ```bash
    npx shadcn@latest add @termcn/opentui-usage-monitor
    ```
  </TabsContent>

  <TabsContent value="manual">
    <Steps>
      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource base="opentui" name="usage-monitor" title="components/ui/usage-monitor.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

Usage [#usage]

```tsx
import { UsageMonitor } from "@/components/ui/usage-monitor";
```

```tsx
<UsageMonitor refreshInterval={2000}>
  <UsageMonitor.Header title="API Usage Dashboard" />
  <UsageMonitor.Tags items={["Pro Plan", "Billing: Monthly", "US-East"]} />
  <UsageMonitor.Section icon="📊" title="Requests">
    <UsageMonitor.Metric
      label="API Calls"
      value={8420}
      max={10000}
      percent={84.2}
      status="yellow"
      format="number"
    />
  </UsageMonitor.Section>
  <UsageMonitor.Stats>
    <UsageMonitor.StatRow label="Avg Latency" value="142ms" />
    <UsageMonitor.StatRow label="Error Rate" value="0.3%" valueColor="green" />
  </UsageMonitor.Stats>
  <UsageMonitor.StatusBar clock sessionLabel="dashboard" exitHint="q to quit" />
</UsageMonitor>
```

API Reference [#api-reference]

UsageMonitor [#usagemonitor]

| Prop              | Type        | Default    |
| ----------------- | ----------- | ---------- |
| `refreshInterval` | `number`    | `1000`     |
| `separatorChar`   | `string`    | `"─"`      |
| `children`        | `ReactNode` | `required` |

UsageMonitor.Header [#usagemonitorheader]

| Prop             | Type     | Default     |
| ---------------- | -------- | ----------- |
| `title`          | `string` | `required`  |
| `titleColor`     | `string` | `"cyan"`    |
| `decorator`      | `string` | `"◆ ✦ ◆ ✦"` |
| `separatorChar`  | `string` | `"═"`       |
| `separatorColor` | `string` | -           |

UsageMonitor.Tags [#usagemonitortags]

| Prop             | Type       | Default    |
| ---------------- | ---------- | ---------- |
| `items`          | `string[]` | `required` |
| `bracketColor`   | `string`   | `"cyan"`   |
| `separatorColor` | `string`   | `"cyan"`   |

UsageMonitor.Section [#usagemonitorsection]

| Prop       | Type        | Default    |
| ---------- | ----------- | ---------- |
| `icon`     | `string`    | -          |
| `title`    | `string`    | -          |
| `subtitle` | `string`    | -          |
| `children` | `ReactNode` | `required` |

UsageMonitor.Metric [#usagemonitormetric]

| Prop           | Type                                                            | Default    |
| -------------- | --------------------------------------------------------------- | ---------- |
| `icon`         | `string`                                                        | -          |
| `label`        | `string`                                                        | `required` |
| `value`        | `number`                                                        | `required` |
| `max`          | `number`                                                        | `required` |
| `percent`      | `number`                                                        | `required` |
| `status`       | `"green" \| "yellow" \| "red" \| "blue"`                        | `required` |
| `format`       | `"number" \| "currency" \| "duration" \| "percent" \| "custom"` | `required` |
| `formatFn`     | `(v: number, max: number) => string`                            | -          |
| `barWidth`     | `number`                                                        | `22`       |
| `barFillChar`  | `string`                                                        | `"█"`      |
| `barEmptyChar` | `string`                                                        | `"░"`      |
| `barColor`     | `string`                                                        | `"white"`  |
| `maxDim`       | `boolean`                                                       | `false`    |
| `showMax`      | `boolean`                                                       | `true`     |

UsageMonitor.DistributionMetric [#usagemonitordistributionmetric]

| Prop       | Type                                                   | Default    |
| ---------- | ------------------------------------------------------ | ---------- |
| `icon`     | `string`                                               | -          |
| `label`    | `string`                                               | `required` |
| `segments` | `{ label: string; percent: number; color?: string }[]` | `required` |
| `barWidth` | `number`                                               | `22`       |

UsageMonitor.Stats [#usagemonitorstats]

| Prop       | Type        | Default    |
| ---------- | ----------- | ---------- |
| `children` | `ReactNode` | `required` |

UsageMonitor.StatRow [#usagemonitorstatrow]

| Prop          | Type     | Default    |
| ------------- | -------- | ---------- |
| `icon`        | `string` | -          |
| `label`       | `string` | `required` |
| `value`       | `string` | `required` |
| `valueSuffix` | `string` | -          |
| `valueColor`  | `string` | `"white"`  |

UsageMonitor.Predictions [#usagemonitorpredictions]

| Prop       | Type        | Default    |
| ---------- | ----------- | ---------- |
| `children` | `ReactNode` | `required` |

UsageMonitor.Prediction [#usagemonitorprediction]

| Prop         | Type     | Default    |
| ------------ | -------- | ---------- |
| `label`      | `string` | `required` |
| `value`      | `string` | `required` |
| `valueColor` | `string` | `"yellow"` |

UsageMonitor.StatusBar [#usagemonitorstatusbar]

| Prop           | Type                           | Default   |
| -------------- | ------------------------------ | --------- |
| `clock`        | `boolean`                      | `false`   |
| `clockColor`   | `string`                       | `"cyan"`  |
| `sessionLabel` | `string`                       | -         |
| `sessionColor` | `string`                       | `"green"` |
| `exitHint`     | `string`                       | -         |
| `statusDot`    | `"green" \| "yellow" \| "red"` | `"green"` |
| `separator`    | `string`                       | `" \| "`  |