MeterUsage

A usage overview component: fetches data from analysis/query and renders a total plus a bar trend.

Loading interactive preview…

import {
  MeterUsage,
  MeterChart,

View code ↗Hide code ↑

Actual React source for this preview, including demo controls, shared styles and isolated mocks. The docs host supplies the client and theme; application installation and React / Vue usage follow below.

usage-preview.tsx

import {
  MeterUsage,
  MeterChart,
} from "@meterry/component-react"
import type {
  MeterThemeInput,
  MeterFilterValues,
} from "@meterry/component"
import { METRICS, type PreviewEnvironment } from "./preview-data"
import { EMPTY_FILTERS, styleProps } from "./preview-shared"

export function UsagePreview({
  environment,
  theme,
  filters = EMPTY_FILTERS,
}: {
  environment: PreviewEnvironment
  theme: MeterThemeInput
  filters?: MeterFilterValues
}) {
  return (
    <div data-testid="usage-preview">
      <MeterUsage
        {...styleProps}
        title="Token usage · last 7 days"
        query={{
          startTime: environment.startTime,
          endTime: environment.endTime,
          metrics: [...METRICS],
          measures: ["quantity"],
          filters,
        }}
        slots={{
          value: ({ total, formattedTotal }) => (
            <div
              className="docs-preview-value"
              data-testid="usage-total"
              data-value={total}
            >
              {formattedTotal}
              <span className="docs-preview-unit">tokens</span>
            </div>
          ),
          chart: ({ model }) => (
            <MeterChart
              unstyled
              type="bar"
              theme={theme}
              data={model.series[0]?.points ?? []}
              x="label"
              series={[{ key: "usage", label: "Tokens", value: "value" }]}
              height={180}
              showLegend={false}
              slots={{ header: () => null }}
            />
          ),
        }}
      />
    </div>
  )
}

preview-shared.tsx

import { useSyncExternalStore } from "react"
import {
  createEChartsSeriesRegistry,
  type ChartSeries,
  type MeterClassNames,
  type MeterFilterValues,
  type TableColumn,
  type UsageTableRow,
} from "@meterry/component"
import {
  METRICS,
  MODELS,
  type PreviewEnvironment,
  type PreviewRow,
  type TrendRow,
} from "./preview-data"

export const EMPTY_FILTERS: MeterFilterValues = {}
const classNames: MeterClassNames = {
  root: "docs-preview-root",
  card: "docs-preview-card",
  header: "docs-preview-header",
  caption: "docs-preview-caption",
  title: "docs-preview-title",
  body: "docs-preview-body",
  toolbar: "docs-preview-filter-bar",
  filterBar: "docs-preview-filter-bar",
  filter: "docs-preview-filter",
  table: "docs-preview-table",
  list: "docs-preview-list",
  listFooter: "docs-preview-pagination",
  pagination: "docs-preview-pagination",
  actions: "docs-preview-actions",
  button: "docs-preview-button",
  chart: "docs-preview-chart",
  value: "docs-preview-value",
  unit: "docs-preview-unit",
  empty: "docs-preview-status",
  loading: "docs-preview-status",
  error: "docs-preview-status",
}
export const styleProps = { unstyled: true, classNames }
// Adapt only preview label colors to Starlight, without mutating the global registry.
export const previewSeriesRegistry = createEChartsSeriesRegistry()
for (const type of ["pie", "doughnut"]) {
  const builtin = previewSeriesRegistry.builder(type)
  previewSeriesRegistry.register(
    type,
    (series, index, model) => ({
      ...builtin(series, index, model),
      label: {
        color: model.theme.colors.text,
        textBorderWidth: 0,
      },
    }),
    { polar: true }
  )
}

export const columns: TableColumn<PreviewRow>[] = [
  { key: "bucket", header: "Date", sortable: true },
  {
    key: "model",
    header: "Model",
    sortable: true,
    filter: {
      type: "select",
      options: MODELS.map((value) => ({ label: value, value })),
    },
  },
  { key: "provider", header: "Provider" },
  {
    key: "metric",
    header: "Metric",
    filter: {
      type: "select",
      options: METRICS.map((value) => ({ label: value, value })),
    },
  },
  {
    key: "quantity",
    header: "Quantity",
    sortable: true,
    align: "right",
    filter: { type: "number", placeholder: "Minimum quantity" },
    format: (value) => Number(value).toLocaleString("en-US"),
  },
  {
    key: "amount",
    header: "Amount (USD)",
    sortable: true,
    align: "right",
    format: (value) => `$${Number(value).toFixed(4)}`,
  },
]
// Shared Model/Provider controls and table-local Metric/Quantity controls are independent.
export const sharedColumns = columns.map((column) =>
  column.key === "model" ? { ...column, filter: undefined } : column
)

export const trendSeries: ChartSeries<TrendRow>[] = [
  { key: "input", label: "Input tokens", value: "input_tokens" },
  { key: "output", label: "Output tokens", value: "output_tokens" },
]

// API identity is raw_event_id; override the snapshot's legacy default event column.
export const eventColumns: TableColumn<UsageTableRow>[] = [
  { key: "raw_event_id", header: "Event ID" },
  {
    key: "occurred_at",
    header: "Occurred at",
    format: (value) =>
      new Date(Number(value) * 1000).toISOString().slice(0, 10),
  },
  { key: "source", header: "Source" },
  {
    key: "model",
    header: "Model",
    accessor: (row) =>
      (row.labels as Record<string, string> | undefined)?.model,
  },
]

export function RequestSummary({
  environment,
}: {
  environment: PreviewEnvironment
}) {
  useSyncExternalStore(
    environment.subscribeRequests,
    () => environment.requests.length,
    () => 0
  )
  const details = environment.requests.filter((request) =>
    request.path.endsWith("/details")
  ).length
  const trend = environment.requests.filter((request) =>
    request.path.endsWith("/analysis/query")
  ).length
  const aggregate = environment.requests.filter((request) =>
    request.path.endsWith("/usage/query")
  ).length
  return (
    <output className="docs-preview-filter-summary" data-testid="request-count">
      Mock API requests: {environment.requests.length} · Events: {details} ·
      Trend: {trend} · Aggregate: {aggregate}
    </output>
  )
}

preview-data.ts

import {
  SubjectClient,
  createSubjectTokenProvider,
  mergeMeterFilters,
  type AnalysisQueryRequest,
  type AnalysisQueryResponse,
  type FetchLike,
  type MeterFilterValues,
  type TableQuery,
  type TableResult,
  type UsageQueryRequest,
  type UsageQueryResponse,
} from "@meterry/component"

export const DAY = 86_400
export const MODELS = ["gpt-4o-mini", "claude-sonnet", "glm-5.1"] as const
export const PROVIDERS = ["openai", "anthropic", "r9s"] as const
export const METRICS = ["input_tokens", "output_tokens"] as const
export type PreviewScenario = "sample" | "empty" | "error"
export type PreviewRow = {
  bucket: string
  model: string
  provider: string
  metric: string
  quantity: number
  amount: number
}
export type TrendRow = {
  bucket: string
  input_tokens: number
  output_tokens: number
}
export type PreviewRequest = { path: string; afterId?: string }
export type PreviewEnvironment = {
  requests: PreviewRequest[]
  subscribeRequests: (listener: () => void) => () => void
  failNextRequest: () => void
  client: SubjectClient
  startTime: number
  endTime: number
}

/** Synthetic browser-only fixtures, not production usage or pricing. */
export function createFixture(now = Date.now()) {
  const today = Math.floor(now / 1000 / DAY) * DAY
  const startTime = today - 6 * DAY
  const rows: PreviewRow[] = []
  for (let day = 0; day < 7; day++) {
    for (let model = 0; model < MODELS.length; model++) {
      for (let metric = 0; metric < METRICS.length; metric++) {
        const quantity = 1000 + day * 140 + model * 600 + metric * 400
        rows.push({
          bucket: new Date((startTime + day * DAY) * 1000)
            .toISOString()
            .slice(0, 10),
          model: MODELS[model]!,
          provider: PROVIDERS[model]!,
          metric: METRICS[metric]!,
          quantity,
          amount: Number((quantity * 0.000002).toFixed(6)),
        })
      }
    }
  }
  return { rows, startTime, endTime: Math.floor(now / 1000) + 1 }
}

function selectRows(
  rows: PreviewRow[],
  request: UsageQueryRequest | AnalysisQueryRequest
) {
  const metrics = request.metrics?.length ? request.metrics : METRICS
  return rows.filter((row) => {
    const timestamp = Date.parse(row.bucket) / 1000
    if (
      timestamp < (request.start_time ?? -Infinity) ||
      timestamp >= (request.end_time ?? Infinity)
    )
      return false
    if (!metrics.includes(row.metric as (typeof METRICS)[number])) return false
    return Object.entries(request.filters ?? {}).every(([key, value]) => {
      if (value === "") return true
      if (key === "quantity" || key === "amount") {
        return Number.isFinite(Number(value)) && row[key] >= Number(value)
      }
      return key in row && String(row[key as keyof PreviewRow]) === value
    })
  })
}

function analysisResponse(
  rows: PreviewRow[],
  request: AnalysisQueryRequest
): AnalysisQueryResponse {
  const groups = new Map<
    string,
    {
      metric: string
      measure: string
      model?: string
      points: Map<string, number>
    }
  >()
  for (const row of selectRows(rows, request)) {
    for (const measure of request.measures) {
      const model = request.group_by?.includes("model") ? row.model : undefined
      const key = [row.metric, measure, model].filter(Boolean).join(":")
      const group = groups.get(key) ?? {
        metric: row.metric,
        measure,
        model,
        points: new Map(),
      }
      const value =
        measure === "amount"
          ? row.amount
          : measure === "item_count"
            ? 1
            : row.quantity
      group.points.set(row.bucket, (group.points.get(row.bucket) ?? 0) + value)
      groups.set(key, group)
    }
  }
  let remaining = request.limit ?? Infinity
  const series: AnalysisQueryResponse["series"] = []
  for (const [key, group] of groups) {
    const points = [...group.points]
      .sort(([a], [b]) => a.localeCompare(b))
      .slice(0, remaining)
      .map(([bucket, value]) => ({ bucket, value }))
    remaining -= points.length
    if (points.length)
      series.push({
        key,
        label: group.metric,
        measure: group.measure,
        dimensions: {
          metric: group.metric,
          ...(group.model ? { model: group.model } : {}),
        },
        points,
      })
  }
  return {
    group_by: request.group_by ?? ["bucket"],
    measures: request.measures,
    series,
    meta: {
      timezone: "UTC",
      bucket_size: request.bucket_size ?? "1d",
      start_time: request.start_time,
      end_time: request.end_time,
    },
  }
}

function usageResponse(
  rows: PreviewRow[],
  request: UsageQueryRequest
): UsageQueryResponse {
  const dimensions = request.group_by ?? ["bucket", "model", "metric"]
  const groups = new Map<
    string,
    { dimensions: Record<string, string>; measures: Record<string, number> }
  >()
  for (const row of selectRows(rows, request)) {
    const values = Object.fromEntries(
      dimensions.map((key) => [key, String(row[key as keyof PreviewRow] ?? "")])
    )
    const key = JSON.stringify(values)
    const group = groups.get(key) ?? { dimensions: values, measures: {} }
    for (const measure of request.measures ?? ["quantity"]) {
      const value =
        measure === "amount"
          ? row.amount
          : measure === "item_count"
            ? 1
            : row.quantity
      group.measures[measure] = (group.measures[measure] ?? 0) + value
    }
    groups.set(key, group)
  }
  return { rows: [...groups.values()].slice(0, request.limit ?? groups.size) }
}

function delay(
  milliseconds: number,
  signal?: AbortSignal | null
): Promise<void> {
  return new Promise((resolve, reject) => {
    const abort = () => {
      clearTimeout(timer)
      signal?.removeEventListener("abort", abort)
      reject(new DOMException("Preview request aborted", "AbortError"))
    }
    const timer = setTimeout(() => {
      signal?.removeEventListener("abort", abort)
      resolve()
    }, milliseconds)
    if (signal?.aborted) abort()
    else signal?.addEventListener("abort", abort, { once: true })
  })
}

/** Every request stays in this fetch adapter; no network or stored credentials. */
export function createPreviewEnvironment(
  options: {
    scenario?: PreviewScenario
    now?: number
    delayMs?: number
  } = {}
): PreviewEnvironment {
  const fixture = createFixture(options.now)
  const rows = options.scenario === "empty" ? [] : fixture.rows
  const requests: PreviewRequest[] = []
  const listeners = new Set<() => void>()
  let failNext = false
  const json = (body: unknown, status = 200) =>
    new Response(JSON.stringify(body), {
      status,
      headers: { "content-type": "application/json" },
    })
  const fetch: FetchLike = async (input, init) => {
    const url = new URL(
      typeof input === "string"
        ? input
        : input instanceof URL
          ? input.href
          : input.url,
      "https://docs-preview.invalid"
    )
    requests.push({
      path: url.pathname,
      afterId: url.searchParams.get("after_id") ?? undefined,
    })
    for (const listener of listeners) listener()
    await delay(options.delayMs ?? 180, init?.signal)
    if (
      url.origin !== "https://docs-preview.invalid" ||
      ![
        "/v1/subject/analysis/query",
        "/v1/subject/usage/query",
        "/v1/subject/usage/events/details",
      ].includes(url.pathname)
    )
      return json({ message: "Unknown preview endpoint" }, 404)
    if (options.scenario === "error" || failNext) {
      failNext = false
      return json({ message: "Simulated preview request failure" }, 503)
    }
    if (url.pathname.endsWith("/details")) {
      if (init?.method !== "GET")
        return json({ message: "Preview details require GET" }, 405)
      const request: UsageQueryRequest = {
        start_time: Number(url.searchParams.get("start_time")) || undefined,
        end_time: Number(url.searchParams.get("end_time")) || undefined,
        metrics: url.searchParams
          .getAll("metrics")
          .flatMap((value) => value.split(",")),
        metric: url.searchParams.get("metric") ?? undefined,
      }
      if (!request.metrics?.length && request.metric)
        request.metrics = [request.metric]
      const events = selectRows(rows, request).map((row) => ({
        raw_event_id: `raw_preview_${String(fixture.rows.indexOf(row) + 1).padStart(4, "0")}`,
        occurred_at: Date.parse(row.bucket) / 1000,
        source: "documentation",
        subject_type: "user",
        subject_id: "documentation-preview",
        labels: { model: row.model, provider: row.provider },
        metrics: {
          [row.metric]: {
            value: String(row.quantity),
            amount: String(row.amount),
            currency: "USD",
          },
        },
      }))
      const after = url.searchParams.get("after_id")
      const cursorIndex = after
        ? events.findIndex((event) => event.raw_event_id === after)
        : -1
      if (after && cursorIndex < 0)
        return json({ message: "Invalid preview cursor" }, 400)
      const start = cursorIndex + 1
      const limit = Math.min(
        1000,
        Math.max(1, Number(url.searchParams.get("limit")) || 100)
      )
      const page = events.slice(start, start + limit)
      return json({
        usage_events: page,
        total: events.length,
        ...(start + page.length < events.length
          ? { next_after_id: page.at(-1)?.raw_event_id }
          : {}),
      })
    }
    if (init?.method !== "POST")
      return json({ message: "Preview query requires POST" }, 405)
    let body: UsageQueryRequest | AnalysisQueryRequest
    try {
      body = JSON.parse(String(init?.body ?? "{}"))
    } catch {
      return json({ message: "Invalid preview query" }, 400)
    }
    if (!Array.isArray(body.measures))
      return json({ message: "Missing preview measures" }, 400)
    return json(
      url.pathname.endsWith("/analysis/query")
        ? analysisResponse(rows, body as AnalysisQueryRequest)
        : usageResponse(rows, body)
    )
  }
  const provider = createSubjectTokenProvider(
    async () => ({
      token_type: "Bearer",
      access_token: "documentation-preview-only",
      expires_in: 900,
      expires_at: Math.floor(Date.now() / 1000) + 900,
      subject: { type: "user", id: "documentation-preview" },
      rules: ["analysis"],
    }),
    { tokenStorage: null }
  )
  return {
    requests,
    subscribeRequests: (listener) => {
      listeners.add(listener)
      return () => {
        listeners.delete(listener)
      }
    },
    failNextRequest: () => {
      failNext = true
    },
    client: new SubjectClient(provider, {
      baseUrl: "https://docs-preview.invalid",
      credentials: "omit",
      fetch,
    }),
    startTime: fixture.startTime,
    endTime: fixture.endTime,
  }
}

export async function fetchPreviewTrend(
  environment: PreviewEnvironment,
  filters: MeterFilterValues = {},
  signal?: AbortSignal
): Promise<TrendRow[]> {
  const response = await environment.client.analysisQuery(
    {
      bucket_size: "1d",
      start_time: environment.startTime,
      end_time: environment.endTime,
      metrics: [...METRICS],
      group_by: ["bucket"],
      measures: ["quantity"],
      filters,
    },
    { signal }
  )
  const byBucket = new Map<string, TrendRow>()
  for (const series of response.series) {
    const metric = series.dimensions?.metric
    if (metric !== "input_tokens" && metric !== "output_tokens") continue
    for (const point of series.points) {
      const row = byBucket.get(point.bucket) ?? {
        bucket: point.bucket,
        input_tokens: 0,
        output_tokens: 0,
      }
      row[metric] += Number(point.value)
      byBucket.set(point.bucket, row)
    }
  }
  return [...byBucket.values()].sort((a, b) => a.bucket.localeCompare(b.bucket))
}

export async function loadPreviewRows(
  environment: PreviewEnvironment,
  query: TableQuery,
  shared: MeterFilterValues = {}
): Promise<TableResult<PreviewRow>> {
  const response = await environment.client.usageQuery({
    bucket_size: "1d",
    start_time: environment.startTime,
    end_time: environment.endTime,
    metrics: [...METRICS],
    group_by: ["bucket", "model", "provider", "metric"],
    measures: ["quantity", "amount"],
    filters: mergeMeterFilters(query.filters, shared),
    limit: 500,
  })
  const rows: PreviewRow[] = response.rows.map((row) => ({
    bucket: String(row.dimensions.bucket),
    model: String(row.dimensions.model),
    provider: String(row.dimensions.provider),
    metric: String(row.dimensions.metric),
    quantity: Number(row.measures.quantity),
    amount: Number(row.measures.amount),
  }))
  if (query.sort) {
    const { key, direction } = query.sort
    rows.sort((a, b) => {
      const left = a[key as keyof PreviewRow],
        right = b[key as keyof PreviewRow]
      const order =
        typeof left === "number" && typeof right === "number"
          ? left - right
          : String(left).localeCompare(String(right))
      return direction === "desc" ? -order : order
    })
  }
  return {
    total: rows.length,
    rows: rows.slice(
      (query.page - 1) * query.pageSize,
      query.page * query.pageSize
    ),
  }
}

Installation

React

Terminal

npm install @meterry/component @meterry/component-react echarts echarts-for-react

Vue 3

Terminal

npm install @meterry/component @meterry/component-vue echarts vue-echarts

For default styles, optionally install @meterry/component-tailwindcss. For authentication, shared clients and theming, see Getting Started.

The examples below show how to fetch usage through a shared client and apply dimension filters. See Getting Started for a complete React or Vue integration.

Note

This preview uses the real React component with a browser-only mock Subject API. No login, real billing requests, or stored credentials are used. Select Empty data or Simulated error to explore those states. Application integration still requires your own backend-issued Subject Token.

Usage

// React: recommended — mount under MeterClientProvider
<MeterClientProvider getJwt={getSubjectToken}>
  <MeterUsage title="Usage" rangeDays={7} />
</MeterClientProvider>

// Compatibility mode: component-level getJwt creates a client automatically
<MeterUsage getJwt={getSubjectToken} tokenScope="meter:current-user" />

<!-- Vue 3 -->
<script setup>
provideMeterClient({ getJwt: getSubjectToken })
</script>
<template>
  <MeterUsage title="Usage" :range-days="7" measure="quantity" />
</template>

Props

Prop	Type	Default	Description
client	SubjectClient	—	Explicit shared client; takes precedence over context and getJwt
getJwt	GetJwt	—	Compatibility mode: component-level Subject Token issuance, creates a client automatically
tokenScope	string	—	Scope of the shared token provider in compatibility mode (isolate per user/tenant/environment)
tokenStorageKey	string	meter:subject-token	Override the localStorage key
baseUrl	string	''	API prefix
query	UsageWidgetQuery	—	Overrides bucketSize / metrics / groupBy / measures / time range and supplies dimension filters
rangeDays	number	7	Time window in days
title	string	messages.usageTitle	Title
measure	string	first measure	Measure used for the total and the chart (e.g. quantity, amount)
loading / empty	ReactNode / VNode	messages defaults	Loading and empty state content
error	(error: Error) => Node	—	Custom error rendering
onError	(error: Error) => void	—	Error callback
slots	MeterUsageSlots	—	Replace the header / value / chart rendering
messages	Partial<MeterMessages>	—	Copy overrides, see Internationalization
seriesRegistry	EChartsSeriesRegistry	global registry	Scoped chart type registry
className / classNames / unstyled	—	—	Styling, see Theming & Styles

Shared dimension filters

Pass active dimension values through query.filters (Record<string, string>):

import { MeterUsage, useMeterFilters } from '@meterry/component-react'
import type { MeterFilterController } from '@meterry/component'

function FilteredUsage({ controller }: { controller: MeterFilterController }) {
  const filters = useMeterFilters(controller)
  return <MeterUsage query={{ metrics: ['tokens'], filters }} />
}

<template>
  <!-- filters is the ref returned by useMeterFilterValues(controller). -->
  <MeterUsage :query="{ metrics: ['tokens'], filters }" />
</template>

These snippets assume the corresponding React/Vue bindings and a page-level filter controller; see Shared Filters for the complete setup. The component normalizes empty strings away before sending the analysis request and omits filters if none are active. Keys and non-empty values are otherwise passed unchanged; the service decides matching semantics. Metric and time selectors may need to update query.metrics, startTime, or endTime instead of becoming dimensions.

The filter bar debounces text/number input by default. MeterUsage itself does not debounce programmatic query changes. It cancels superseded requests using an AbortSignal and ignores stale responses/errors, including after unmounting. Custom fetch implementations should honor the signal.

Slots

<MeterUsage
  client={client}
  slots={{
    header: ({ caption, title }) => <MyHeader caption={caption} title={title} />,
    value: ({ total, formattedTotal, measure }) => (
      <strong>{formattedTotal} {measure}</strong>
    ),
    chart: ({ model, option }) => <MyChart option={option} />, // option feeds echarts directly
  }}
/>

Changing query or rangeDays loads usage for the new selection. Use loading, empty, and error to provide helpful messages while loading, when no usage matches, or when a request fails.