# TimeSeriesPanel
> A chart card for one metric at a time, with a previous-period comparison line, a metric switcher and threshold lines. Also exports PeriodToggle.
Source: https://docs.nasaqui.com/components/time-series-panel
## Install
```bash
npx shadcn@latest add https://docs.nasaqui.com/r/time-series-panel.json
```
TimeSeriesPanel is the traffic chart of an analytics page. It draws the selected metric as a filled line, can overlay the previous period as a dashed line, shows the total or average with its change, and draws reference lines such as Google's "good" and "poor" limits. It is built on `ChartContainer`, so tooltips, colours and RTL axis handling match the rest of the charts. `PeriodToggle` is the matching 7 / 28 / 90 days control.
## When to use
- Traffic, clicks, views, latency or any metric over days or hours.
- Comparing this period with the last one.
- Showing a metric against fixed thresholds.
## When not to use
- A single small trend: use `Sparkline` from [`chart`](https://docs.nasaqui.com/components/chart).
- Share of a total: use [`BreakdownTable`](https://docs.nasaqui.com/components/breakdown-table).
- Several unrelated charts: compose [`ChartContainer`](https://docs.nasaqui.com/components/chart) directly.
## Import
```tsx
import { TimeSeriesPanel, PeriodToggle } from "@fadymondy/nasaq/web";
```
## Quick start
```tsx
import { TimeSeriesPanel } from "@fadymondy/nasaq/web";
export function Traffic() {
return (
);
}
```
## Anatomy
```
TimeSeriesPanel data-slot="time-series-panel" (a Card)
CardHeader title, description, action
metric switcher toggle buttons when there is more than one metric
compare switch when previousData is set
summary total or average, and its change
ChartContainer the area chart, previous line and reference lines
PeriodToggle data-slot="toggle-group"
```
## API
### TimeSeriesPanel
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `metrics` | `readonly TimeSeriesMetric[]` | required | The metrics the panel can show. |
| `data` | `readonly TimeSeriesPoint[]` | required | One row per day or hour: `date` plus a number per metric id. |
| `previousData` | `readonly TimeSeriesPoint[]` | none | The comparison period, index-aligned with `data`. |
| `title` | `ReactNode` | none | Card title. |
| `description` | `ReactNode` | none | Card description. |
| `metric / defaultMetric / onMetricChange` | `string / string / (id) => void` | `first metric` | Selected metric, controlled or not. |
| `compare / defaultCompare / onCompareChange` | `boolean / boolean / (on) => void` | `false` | Whether the comparison line shows. |
| `referenceLines` | `readonly TimeSeriesReferenceLine[]` | none | Horizontal lines with a label and a tone. |
| `dateFormat` | `FormatDateOptions` | `month and day` | How axis and tooltip dates are written. |
| `chartClassName` | `string` | none | Classes on the chart, to change its height. |
| `action` | `ReactNode` | none | Content at the header's inline end, usually a `PeriodToggle`. |
| `loading` | `boolean` | `false` | Skeleton. |
| `error` | `ReactNode` | none | Shows an error with a retry button instead of the chart. |
| `onRetry` | `() => void` | none | Called by the retry button. |
| `className` | `string` | none | Extra classes on the root. |
| `labels` | `Partial` | none | Replace any built-in English or Arabic string. |
### TimeSeriesMetric
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` | required | Key in each data row. |
| `label` | `string` | required | Name in the switcher, tooltip and summary. |
| `format` | `FormatNumberOptions` | none | Intl options for values. |
| `color` | `string` | `var(--primary)` | A token such as `var(--nq-tag-teal)`. |
| `aggregate` | `"sum" \| "avg"` | `sum` | How the summary combines the period; use `avg` for rates and positions. |
| `lowerIsBetter` | `boolean` | `false` | Tones the change: down is good. |
### PeriodToggle
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options` | `readonly number[]` | `[7, 28, 90]` | Period lengths. |
| `value` | `number` | required | Selected length. |
| `onValueChange` | `(days: number) => void` | required | Called with the new length. |
| `labels` | `{ period?, lastDays? }` | none | `lastDays` is `(n) => string`; the APM page uses it for hours. |
| `className` | `string` | none | Extra classes on the root. |
## Examples
Against Google's LCP thresholds:
```tsx
import { TimeSeriesPanel } from "@fadymondy/nasaq/web";
export const Lcp = ({ data }: { data: { date: string; lcp: number }[] }) => (
);
```
Period control in the header:
```tsx
import { PeriodToggle, TimeSeriesPanel } from "@fadymondy/nasaq/web";
import { useState } from "react";
export function Panel({ data }: { data: { date: string; clicks: number }[] }) {
const [days, setDays] = useState(28);
return } />;
}
```
Hourly data:
```tsx
import { TimeSeriesPanel } from "@fadymondy/nasaq/web";
export const Rpm = () => ;
```
## Accessibility
The chart has a text alternative naming the metric and range, and the switcher and comparison switch are ordinary buttons reachable with Tab. Tooltips also show on keyboard focus of the chart. Localise metric labels, `title` and the `labels` you override.
## RTL & i18n
- `useChartAxis` reverses the x axis and moves the y axis to the inline end in RTL, so time runs right to left.
- Every figure uses the active locale with Western digits and is bidi-isolated (`Num`), so `+12.4%` keeps its order in Arabic.
- Dates are formatted with the locale and Western digits; day strings ("2026-09-29") are read as local days, so they never shift.
## Styling & tokens
- Colours come from tokens (`--primary`, `--nq-success`, `--nq-warning`, `--nq-danger`, `--nq-tag-*`); never pass raw hex.
- Colours per metric come from `TimeSeriesMetric.color`; the comparison line uses `--muted-foreground`.
## Do / Don't
- Do index-align `previousData` with `data` (day 1 against day 1).
- Do set `aggregate: "avg"` for rates, positions and percentiles.
- Don't put more than about four metrics in one switcher.
- Don't use it for unordered categories.
## Related
- [`chart`](https://docs.nasaqui.com/components/chart)
- [`metric-tiles`](https://docs.nasaqui.com/components/metric-tiles)
- [`stat-card`](https://docs.nasaqui.com/components/stat-card)
- [`web-vital-gauge`](https://docs.nasaqui.com/components/web-vital-gauge)
## Lab
https://docs.nasaqui.com/?path=/docs/components-monitoring-time-series-panel--docs
## Code
### React
```tsx
import { TimeSeriesPanel } from "@fadymondy/nasaq/web";
export function Traffic() {
return (
);
}
```
### shadcn
```tsx
import { TimeSeriesPanel } from "@/components/ui/time-series-panel";
export function Traffic() {
return (
);
}
```
### Vue
```vue
```
### Blade
```blade
```
### HTML + Alpine
```html