Usage Card

ngx-prompt-kit original — not part of ibelick/prompt-kit

Persistent session/account-level usage indicator. Three display modes — ring (Instagram/Discord pattern, usage IS the chrome), inline (sidebar header row), and card (standalone block, JetBrains AI widget pattern). All share threshold colors at 75/90/100% and identity-integrated by design.

Examples

Ring — identity-integrated

Default mode. Circular SVG arc wraps the avatar; name + sublabel stack to the right. Most compact mode — hover for the full readout.

NiclasPro plan

<pk-usage-card
  [used]="2_500"
  [limit]="10_000"
  [avatar]="avatarUrl"
  name="Niclas"
  sublabel="Pro plan"
/>

Inline — sidebar header row

Horizontal layout for sidebar headers. Avatar + name + sublabel + readout on top, fill bar below. Numbers visible at a glance — use this when ring is too small for the readout to be useful.

NiclasResets in 12 days

30,000 / 50,000 · 60%

<pk-usage-card
  display="inline"
  [used]="30_000"
  [limit]="50_000"
  [avatar]="avatarUrl"
  name="Niclas"
  sublabel="Resets in 12 days"
/>

Card — standalone block with top-up

Full hlm-card chrome, label header, fill bar, count, optional Top-up button. The button only renders when [topUpLabel] is set — no dead CTAs. 88% usage trips the amber threshold.

NiclasPro plan

Token usage 44,000 / 50,000 · 88%

<pk-usage-card
  display="card"
  [used]="44_000"
  [limit]="50_000"
  label="Token usage"
  unit="tokens"
  topUpLabel="Top up"
  [avatar]="avatarUrl"
  name="Niclas"
  sublabel="Pro plan"
  (topUpClicked)="onTopUp()"
/>

Threshold trio — ring colors at 30 / 85 / 105 %

Three rings side-by-side at the muted, amber, and destructive thresholds. Easiest way to verify the traffic-light state in both themes.

30%

85%

105%

<pk-usage-card [used]="3_000"  [limit]="10_000" [avatar]="a" [ringSize]="56" [ringStroke]="3.5" />
<pk-usage-card [used]="8_500"  [limit]="10_000" [avatar]="b" [ringSize]="56" [ringStroke]="3.5" />
<pk-usage-card [used]="10_500" [limit]="10_000" [avatar]="c" [ringSize]="56" [ringStroke]="3.5" />

Monochrome — opt out of threshold colors

Set [monochrome]='true' to drop the traffic-light entirely. Ring stroke, bar fill, and number text all use the foreground color (near-white in dark, near-black in light). Useful when usage is informational rather than actionable — no warning state needed.

30%

85%

105%

<pk-usage-card
  [used]="3_000"
  [limit]="10_000"
  [avatar]="avatarUrl"
  [ringSize]="56"
  [ringStroke]="3.5"
  [monochrome]="true"
/>

Installation

Add the usage-card component (and the cn() utility) to your project.

ng generate ngx-prompt-kit:usage-card

Component API

PkUsageCard

Prop	Type	Default	Description
used	`number`	—	Current usage value (required).
limit	`number \| null`	—	Cap. Required prop, but null/0 degrades gracefully — bar/ring hide and the readout shows just the used count + unit.
display	`"ring" \| "inline" \| "card"`	"ring"	ring: SVG arc wrapping the avatar (most compact). inline: sidebar header row with bar + readout. card: standalone hlm-card with label, bar, count, optional top-up.
avatar	`string?`	—	Image URL or data URI; falls back to initials.
name	`string?`	—	Display name. Drives initials fallback when avatar is absent.
sublabel	`string?`	—	Smaller muted line under name — plan tier, reset window, etc.
label	`string`	"Usage"	Used in card mode header, tooltip, and aria-label.
unit	`string`	"tokens"	Trailing unit when the bar is hidden (limit unset).
showPercentage	`boolean`	true	Append "· N%" to the readout.
locale	`string?`	—	BCP-47 locale for Intl.NumberFormat. Defaults to runtime locale.
ringSize	`number`	40	Ring + avatar diameter in px (ring mode only).
ringStroke	`number`	2.5	Ring stroke width in px (ring mode only).
topUpLabel	`string \| null`	null	Card mode only. Set to a label string to render the Top-up button. Null hides it entirely — no dead CTA when consumers haven't wired anything.
class	`string`	—	Extra classes for the host.

Outputs

Prop	Type	Default	Description
topUpClicked	`() => void`	—	Fires when the Top-up button is clicked. Only emits if topUpLabel is set (button is rendered).