Browse docs
Line charts
EpisodeLineChart plots recorded signals against seconds. Hover to compare
sample values; use onSeek to send a clicked time to playback.
Compact embeds
Charts and timelines use transparent surfaces by default. Set
background="subtle" to opt into a panel tint; semantic ranges and uncertainty
bands keep their own colors. size="compact" supplies a 150px total chart
height and fewer y-axis labels. Use height={130} through height={170} to fit
an embedded 2×2 chart grid, or height="100%" inside explicitly sized grid rows
with min-height: 0. The normal size continues to fill its parent.
The example uses a three-second recording, fractional-second labels and short
major/minor tick marks. All four charts share time, onHover, zoom and pan;
only the hovered chart shows a readout. No new cursor callback is needed.
Use onHoverEnd to clear the preview. isScrubOwner={false} explicitly
suppresses a readout. The readout follows both pointer axes in a body portal,
stays 12px below and to the right of the pointer and can extend beyond the chart.
Only browser edges clamp it into view. It passes pointer events through; Escape dismisses it. Keyboard zoom/pan shows the focused
chart's readout when time is set. Recorded sample values are never interpolated.
Both axes have short 6px major and 3px minor ticks. Y-axis marks extend into
the gutter without moving the plot or adding minor grid lines. Their numeric
values follow the nice-number selection guide;
explicit yRange bounds and custom formatters stay authoritative. Compact axes
normally target three majors; if a nonconstant range leaves fewer than two,
they retry a target of five. For [13, 87], majors are 20, 40, 60 and 80 without
expanding the exact domain. Minor ticks remain short and unlabelled.
- Response: 00:01.400 – 00:02.100
- Correction: 00:01.400
- Response: 00:01.400 – 00:02.100
- Correction: 00:01.400
- Response: 00:01.400 – 00:02.100
- Correction: 00:01.400
- Response: 00:01.400 – 00:02.100
- Correction: 00:01.400
Code CompactSpec.tsx
Basic
Hover the signals below. Each readout uses the nearest recorded sample, including when the cursor falls between measurements.
Code BasicSpec.tsx
For the data props, supply matching x and y arrays. This fragment omits
the container height and controlled cursor; expand the live example above for
the complete wiring:
The y-axis fits the data automatically. Set yRange to compare several charts
on a fixed scale; Numeric axes explains tick labels.
Line width and active emphasis
Primary traces default to 2 CSS pixels, including compact charts. Set
lineWidth once for the chart; a finite, non-negative series.width overrides
it for that series. Values such as 1.5, 2, 2.5 and 3 are supported.
Start at 2px and check both themes at the final embed size. Distinguish a
reference with dash, opacity and a label instead of making it a hairline.
Widths stay in CSS pixels at every chart size and zoom. The dashed reference uses the same base width; dash and opacity distinguish it. Hover a trace or use the highlight button to compare active emphasis.
Code LineWidthSpec.tsx
Identification through highlightOnHover or activeSeriesId normally raises
that series to 1.65 times its resolved base width (2px becomes 3.3px).
activeLineWidth replaces that automatic width with a CSS-pixel floor:
max(baseWidth, activeLineWidth). It can never make a thick series thinner.
The example's 3px override becomes 4px when active, while activeLineWidth={2}
would leave it at 3px. This prop controls emphasis; it does not enable hover
identification by itself.
These are non-scaling SVG strokes measured in CSS pixels, not SVG viewBox units or device pixels. Zoom and chart resizing do not shrink them. A zero base width hides the stroke and stays hidden when active; data, bands, readouts and interaction remain available. Negative or non-finite overrides fall back to the chart width; an invalid chart width falls back to 2px, and an invalid active width uses the automatic multiplier. Width changes never alter sample values, axis domains or seek times.
Uncertainty bands
Turn the bands off to isolate the center traces. Between 24 and 28 seconds, missing bounds leave a gap in the band without interrupting the center line.
Blue fill: supplied lower/upper range. Bounds unavailable at 24–28 s; center values remain recorded. No confidence level is inferred.
Code UncertaintyBandSpec.tsx
Supply low and high at the same timestamps as y:
Calculate intervals before passing them in. Valid bounds expand the automatic
y-domain; yRange clips the line and band together. Missing, non-finite, or
inverted bounds leave gaps. Invalid center samples also break the band.
fillColor and fillOpacity override the default series-colored, 16% fill;
tooltips report center values.
Events and time ranges
The force trace below places contact and release markers alongside a shaded grasp interval. The timeline uses the same intervals to show task phases.
- Grasp: 00:18.000 – 00:34.000
- Settle (clipped): 00:46.000 – 01:00.000
- Start: 00:00.000
- Contact: 00:18.000
- Release: 00:34.000
The same Grasp interval (18–34 s) aligns in the chart and timeline. Start at 0 s remains visible. Settle extends to 65 s in data and is clipped at 60 s. Annotation overlays preserve hover and seek.
Code AnnotationsSpec.tsx
Use episode seconds, stable IDs, and labels. Invalid markers and empty, inverted, or non-finite ranges are omitted. Ranges clip to the visible window. Crowded labels may disappear visually but remain in the accessible list. Annotations do not capture clicks or select intervals.
Shared zoom and pan
Zoom into an event below: both charts and the timeline keep the same window. Video continues to use episode time.
- Grasp: 00:07.000 – 00:12.000
- Contact: 00:06.000
- Release: 00:14.000
- Grasp: 00:07.000 – 00:12.000
- Contact: 00:06.000
- Release: 00:14.000
One shared window for both charts and timeline. Event times stay absolute: Contact 6 s, Grasp 7–12 s, Release 14 s. The camera follows the same absolute preview/playhead time.
Alt/Ctrl/Meta + wheel zooms at the pointer. Drag pans; Shift-drag zooms. Focus a plot for + / −, arrow keys, or Home. Plain vertical scrolling stays with the page.
Code SharedViewportSpec.tsx
Share zoom, panPct, and their change callback:
The window starts at panPct * duration and spans duration / zoom. Omit both
props for local viewport state. Reset a controlled group to { zoom: 1, panPct: 0 }.
| Gesture | Result |
|---|---|
| Alt, Ctrl, or Meta + wheel | Zoom around the pointer. |
| Horizontal wheel or drag | Pan a zoomed chart. A drag begins after four pixels. |
| Shift + vertical drag | Zoom around the initial pointer position. |
| Click without dragging | Call onSeek with the clicked time. |
Focus the plot, then + / - | Zoom in / out. |
| Left / right arrow | Pan by 10% of the visible window. |
Home | Reset the viewport. |
A completed drag does not seek. Ordinary vertical scrolling scrolls the page. All chart layers follow the viewport; a cursor outside it is hidden.
Dense series
Increase the sample count, then zoom into a spike:
- Missing observations: 00:42.000 – 00:46.000
- Single-sample spike: 00:29.997
One recorded sample reaches 9 N. The 42–46 s gap stays empty in both the line and supplied bounds. The dashed reference stays at 5 N. Hover reads original samples; zoom in to inspect the spike.
Code DenseSeriesSpec.tsx
rendering="auto" reduces dense display geometry while preserving local
extrema and gaps. Axis fitting and tooltip lookup still use the original
samples. Use rendering="exact" to retain every visible sample after the
browser measures the plot. Both modes use a bounded preview before measurement.
Supply finite, ascending timestamps and matching array lengths. Unsorted data
uses a slower fallback and is not reordered. Replace the data object when
changing its arrays so cached timestamp metadata refreshes.
Series identification
Enable highlightOnHover to emphasize a nearby trace and its tooltip row.
Use activeSeriesId to connect that emphasis to another view. The
seven-signal example adds keyboard and
touch controls.
Shared pin and hover preview
Clicking can pin one time across every linked plot while hover continues to
preview other moments. Use one useTimelinePreview(clock) controller for the
whole group: preview(ownerId, time) on hover, endPreview(ownerId) on leave,
and pin(time) on seek. Ending the current preview returns every view to the
pin. Do not give each chart its own pin or stop forwarding hover when pinned.
The shared timeline example connects two compact charts, a timeline and a shared clock readout, with keyboard and touch controls and an explicit playback policy.
Multi-chart sync
Hover an available chart to read its values at the shared time. The unavailable channel keeps its space with “NO SIGNAL”.
Code MultiChartSyncSpec.tsx
Synced with EpisodeTimeline + EpisodeVideoStack
Move across the video, timeline, or charts to inspect the same recorded moment:
Code EpisodeViewSpec.tsx
Cursor sync protocol
Share time across charts. Each chart detects local hover automatically; peers
show shared hairlines without duplicate readouts. Optionally track the owner
with isScrubOwner to also distinguish bright and muted hairlines.
Timeline and Video
share the hover callbacks but do not use isScrubOwner. Video tracks camera
identity through activeId. Keep a separate playback time if leaving a hover
should restore the committed playhead.
Series shape
Non-finite values break the line. Add label for a normal tooltip row; use
formatValue to format that signal's readout.
Palette
Assign CSS colors directly or use these exports consistently across views. The palette is unchanged between light and dark themes.
| Export | Value |
|---|---|
EPISODE_LINE_CHART_PALETTE.blue | oklch(60% 0.13 235) |
EPISODE_LINE_CHART_PALETTE.yellow | oklch(80% 0.15 95) |
EPISODE_LINE_CHART_PALETTE.green | oklch(66% 0.12 150) |
EPISODE_LINE_CHART_PALETTE.purple | oklch(58% 0.13 295) |
EPISODE_LINE_CHART_FAILURE | oklch(58% 0.17 25) |
Keep signal labels alongside color. Use EPISODE_LINE_CHART_FAILURE with an
error label; a dashed, lower-opacity trace can distinguish reference data.
Tooltip behaviour
Tooltips show time and up to five labeled signals. Identifying a series keeps
its row inside that limit and wraps its full label. The hovered chart's
readout follows both pointer coordinates with a fixed lower-right offset:
its top-left corner is 12px to the right and 12px below the pointer. Crossing a
chart's middle or edges does not flip it above or to the left. The body portal
can extend outside the plot and any clipping ancestor. Only the browser viewport
clamps it as needed to keep an 8px margin. Moving the pointer still moves the
readout when controlled time is frozen; sample selection continues to use the
chart's time semantics. Scrolling updates its position without anchoring it to
the chart corner. Peers show only the shared hairline. Hover readouts always
pass pointer events through.
Disabled state
Set disabled for an unavailable channel. It retains its size, shows
“NO SIGNAL”, and disables chart layers and pointer interaction.
Props
| Prop | Type | Default | Purpose |
|---|---|---|---|
series | EpisodeLineChartSeries[] | required | Signals, drawn in array order. |
duration | number | required | Episode length in seconds; greater than zero. |
title / caption | string | — | Chart title and optional caption above it. |
lineWidth | number | 2 | Default non-scaling trace width in CSS pixels; per-series width takes precedence. Zero hides inherited strokes. |
activeLineWidth | number | base × 1.65 | Active trace width in CSS pixels, never less than its resolved base width. |
rendering | 'auto' | 'exact' | 'auto' | Reduce dense display geometry or retain visible vertices after measurement. |
yRange | [number, number] | auto-fit | Explicit y bounds. Auto-fit includes valid bands, adds 5% padding, and rounds outward. |
time | number | null | null | Shared cursor time; null hides it. |
onHover | (t: number) => void | — | Receive the hovered time. |
onHoverEnd | () => void | — | Receive pointer leave. |
onSeek | (t: number) => void | — | Receive a click's time. |
size | "default" | "compact" | "default" | Compact sets a 150px total height and fewer y ticks. |
height | number | string | parent / 150px compact | Total chart height, including title and axes. |
background | "none" | "subtle" | "none" | Opt into a tinted chart surface. |
isScrubOwner | boolean | true | Emphasize this cursor; false suppresses its readout. Only a local pointer or keyboard interaction shows a readout. |
zoom / panPct | number | 1 / 0 | Controlled visible window. |
onViewportChange | (v: ViewportState) => void | — | Receive requested zoom and pan. |
minZoom / maxZoom | number | 1 / Infinity | Viewport zoom limits. |
markers | EpisodeLineChartMarker[] | [] | Named event times. |
ranges | EpisodeLineChartRange[] | [] | Labeled intervals. |
highlightOnHover | boolean | false | Identify the nearest visible trace. |
highlightThresholdPx | number | 8 | Maximum pointer-to-trace distance in CSS pixels. |
activeSeriesId | string | null | local hover | Controlled series identity; null clears it. |
onActiveSeriesChange | (id: string | null) => void | — | Receive requested identification changes. |
unit | string | derived | Y-axis unit. Derived from a readout formatter when available; '' hides it. |
formatTick | (v: number) => string | derived | Tick text. Uses a readout's custom formatter with trailing unit removed, or step-aware numeric precision. An explicit formatter is used verbatim. |
unitHint | string | — | Explanation below the tooltip time. |
showMidline | boolean | true | Draw the zero gridline, or midpoint tick if zero is absent. False leaves its label visible. |
disabled | boolean | false | Show the unavailable-channel state. |
className | string | — | Root CSS classes. |
EpisodeLineChartSeries
| Field | Type | Default | Purpose |
|---|---|---|---|
id | string | required | Stable signal identifier. |
label | string | — | Tooltip label; omit to exclude the readout. |
data | { x: number[]; y: number[]; low?: number[]; high?: number[] } | required | Aligned timestamps, values, and optional bounds. |
color | string | required | CSS stroke color. |
fillColor / fillOpacity | string / number | series color / 0.16 | Band styling, independent of line opacity. |
width | number | chart lineWidth (2) | Non-scaling CSS-pixel stroke width; zero hides the stroke. |
dash | string | solid | SVG dash pattern, such as '3 2.4'. |
opacity | number | 1 | Line opacity. |
linecap | 'butt' | 'round' | 'square' | 'butt' | Stroke end shape. |
readout | boolean | true | Include a labeled series in the tooltip. |
ghost | boolean | false | Dim its readout and add a tgt suffix for reference signals. |
formatValue | (v: number) => string | v => v.toFixed(2) | Format tooltip values, including any physical-unit conversion. |
Readable axes and readout placement
Axis labels use 11px monospace at full opacity, with darker ink in light mode and brighter ink in dark mode. UIKit hosts can customize --uikit-axis; standalone charts use the same fallback colors. Gridlines remain faint.
Readouts follow the cursor by default (see Tooltip behaviour), with a borderless, translucent background and backdrop blur in both themes. They are portalled to the page body, so a small tile's overflow never clips them. ChartTooltip accepts placement="outside" with boundaryRef for the whole figure to keep the readout beside the figure instead. That readout follows the cursor only along the figure's external edge and never covers a plotted line. A figure that fills the viewport leaves no external space, so that readout is hidden. clampToViewport is deprecated and has no effect, because the cursor readout always stays inside the viewport.
Ordinary vertical wheel and touch scrolling belong to the page. Hold Alt, Ctrl or Command while scrolling to zoom; horizontal gestures pan a zoomed chart. Interactive readout lists allow scroll chaining at their boundaries.