DreamLake
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.

Position
50
  • Response: 00:01.400 – 00:02.100
  • Correction: 00:01.400
0s0.5s1s1.5s2s2.5s3s(s)
Velocity
50
  • Response: 00:01.400 – 00:02.100
  • Correction: 00:01.400
0s0.5s1s1.5s2s2.5s3s(s)
Force
50
  • Response: 00:01.400 – 00:02.100
  • Correction: 00:01.400
0s0.5s1s1.5s2s2.5s3s(s)
Correction
50
  • Response: 00:01.400 – 00:02.100
  • Correction: 00:01.400
0s0.5s1s1.5s2s2.5s3s(s)
Click a chart to seek
Code CompactSpec.tsx

Basic

Hover the signals below. Each readout uses the nearest recorded sample, including when the cursor falls between measurements.

Left arm
(°)
90.045.00.0-45.0-90.0
0s5s10s15s20s(s)
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:

tsx
import { EpisodeLineChart } from "@dreamlake/viz";

<EpisodeLineChart
  duration={3}
  unit="°C"
  series={[
    {
      id: "temperature",
      label: "Temperature",
      color: "#3388aa",
      data: { x: [0, 1, 2, 3], y: [20, 22, 21, 23] },
    },
  ]}
/>;

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.

Line width · three-second recording
50
0s0.5s1s1.5s2s2.5s3s(s)

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
tsx
<EpisodeLineChart
  series={[
    { ...recorded, width: 3 }, // Overrides lineWidth for this trace.
    { ...reference, dash: "4 3", opacity: 0.55 }, // Inherits 2px.
  ]}
  duration={3}
  size="compact"
  height={150}
  lineWidth={2}
  activeLineWidth={4}
  highlightOnHover
/>

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.

Click a chart to set playhead
Synthetic · 121 samples · 60 secondsTemperature · recorded range
(°C)
28.0026.0024.0022.0020.0018.00
00:0000:1000:2000:3000:4000:5001:00(mm:ss)
Reference sensor · shared cursor
(°C)
28.0026.0024.0022.0020.0018.00
00:0000:1000:2000:3000:4000:5001:00(mm:ss)

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:

tsx
const series = [{
  id: 'temperature', label: 'Temperature', color: '#3388aa',
  data: {
    x: [0, 1, 2, 3], y: [20, 22, 21, 23],
    low: [18, 19, 20, 21], high: [22, 25, 23, 26],
  },
}]
<EpisodeLineChart series={series} duration={3} unit="°C" />

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.

Click chart or timeline to seek
Synthetic · 121 samples · 60 secondsGripper force
(N)
10.008.006.004.002.000.00
  • 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
00:0000:1000:2000:3000:4000:5001:00(mm:ss)
1.00×

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
tsx
const markers = [{ id: 'contact', time: 18, label: 'Contact' }]
const ranges = [{ id: 'grasp', start: 18, end: 34, label: 'Grasp' }]
<EpisodeLineChart series={series} duration={60} markers={markers} ranges={ranges} />

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.

REC · 00:00.000
Recorded camera
Window: 5.00–15.00 s · Zoom: 2.000×Preview: —Click a plot to seek
Synthetic · 81 samples · 20 secondsGripper force
(N)
8.006.004.002.000.00
  • Grasp: 00:07.000 – 00:12.000
  • Contact: 00:06.000
  • Release: 00:14.000
5s10s15s(s)
Gripper position
(m)
1.000.800.600.400.200.00
  • Grasp: 00:07.000 – 00:12.000
  • Contact: 00:06.000
  • Release: 00:14.000
5s10s15s(s)
2.00×

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:

tsx
const [viewport, setViewport] = useState({ zoom: 1, panPct: 0 })
const viewportProps = { ...viewport, onViewportChange: setViewport }

<EpisodeLineChart {...viewportProps} series={series} duration={duration} />
<EpisodeTimeline {...viewportProps} duration={duration} />

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 }.

GestureResult
Alt, Ctrl, or Meta + wheelZoom around the pointer.
Horizontal wheel or dragPan a zoomed chart. A drag begins after four pixels.
Shift + vertical dragZoom around the initial pointer position.
Click without draggingCall onSeek with the clicked time.
Focus the plot, then + / -Zoom in / out.
Left / right arrowPan by 10% of the visible window.
HomeReset 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:

Click to seek
10,000 original samples · 60 secondsDense recording
(N)
10.0008.0006.0004.0002.0000.000
  • Missing observations: 00:42.000 – 00:46.000
  • Single-sample spike: 00:29.997
00:0000:1000:2000:3000:4000:5001:00(mm:ss)

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”.

Left arm
(°)
90.045.00.0-45.0-90.0
0s5s10s15s20s(s)
Left arm motors
(°C)
53.045.538.030.523.0
0s5s10s15s20s(s)
Right arm
10.50-0.5-1
NO SIGNAL
0s5s10s15s20s(s)
Touch
(N)
5.002.500.00-2.50-5.00
0s5s10s15s20s(s)
Code MultiChartSyncSpec.tsx

Synced with EpisodeTimeline + EpisodeVideoStack

Move across the video, timeline, or charts to inspect the same recorded moment:

REC · 00:00.000
front/camera/front/image_compressed
REC · 00:00.000
wrist/camera/wrist/image_compressed
REC · 00:00.000
top/camera/top/image_compressed
1.00×
Left arm
(°)
90.045.00.0-45.0-90.0
0s5s10s15s20s(s)
Left arm motors
(°C)
53.045.538.030.523.0
0s5s10s15s20s(s)
Right arm
10.50-0.5-1
NO SIGNAL
0s5s10s15s20s(s)
Touch
(N)
5.002.500.00-2.50-5.00
0s5s10s15s20s(s)
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.

tsx
const [time, setTime] = useState<number | null>(null)
const [ownerId, setOwnerId] = useState<string | null>(null)
const bind = (id: string) => ({
  time,
  isScrubOwner: ownerId === id,
  onHover: (t: number) => { setTime(t); setOwnerId(id) },
  onHoverEnd: () => { setTime(null); setOwnerId(null) },
})

<EpisodeLineChart {...bind('joints')} series={joints} duration={duration} />
<EpisodeLineChart {...bind('temperature')} series={temperatures} duration={duration} />

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

ts
interface EpisodeLineChartSeries {
  id: string;
  label?: string;
  data: { x: number[]; y: number[]; low?: number[]; high?: number[] };
  color: string;
  fillColor?: string;
  fillOpacity?: number;
  width?: number;
  dash?: string;
  opacity?: number;
  linecap?: "butt" | "round" | "square";
  readout?: boolean;
  ghost?: boolean;
  formatValue?: (value: number) => string;
}

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.

ExportValue
EPISODE_LINE_CHART_PALETTE.blueoklch(60% 0.13 235)
EPISODE_LINE_CHART_PALETTE.yellowoklch(80% 0.15 95)
EPISODE_LINE_CHART_PALETTE.greenoklch(66% 0.12 150)
EPISODE_LINE_CHART_PALETTE.purpleoklch(58% 0.13 295)
EPISODE_LINE_CHART_FAILUREoklch(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

PropTypeDefaultPurpose
seriesEpisodeLineChartSeries[]requiredSignals, drawn in array order.
durationnumberrequiredEpisode length in seconds; greater than zero.
title / captionstring—Chart title and optional caption above it.
lineWidthnumber2Default non-scaling trace width in CSS pixels; per-series width takes precedence. Zero hides inherited strokes.
activeLineWidthnumberbase × 1.65Active 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-fitExplicit y bounds. Auto-fit includes valid bands, adds 5% padding, and rounds outward.
timenumber | nullnullShared 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.
heightnumber | stringparent / 150px compactTotal chart height, including title and axes.
background"none" | "subtle""none"Opt into a tinted chart surface.
isScrubOwnerbooleantrueEmphasize this cursor; false suppresses its readout. Only a local pointer or keyboard interaction shows a readout.
zoom / panPctnumber1 / 0Controlled visible window.
onViewportChange(v: ViewportState) => void—Receive requested zoom and pan.
minZoom / maxZoomnumber1 / InfinityViewport zoom limits.
markersEpisodeLineChartMarker[][]Named event times.
rangesEpisodeLineChartRange[][]Labeled intervals.
highlightOnHoverbooleanfalseIdentify the nearest visible trace.
highlightThresholdPxnumber8Maximum pointer-to-trace distance in CSS pixels.
activeSeriesIdstring | nulllocal hoverControlled series identity; null clears it.
onActiveSeriesChange(id: string | null) => void—Receive requested identification changes.
unitstringderivedY-axis unit. Derived from a readout formatter when available; '' hides it.
formatTick(v: number) => stringderivedTick text. Uses a readout's custom formatter with trailing unit removed, or step-aware numeric precision. An explicit formatter is used verbatim.
unitHintstring—Explanation below the tooltip time.
showMidlinebooleantrueDraw the zero gridline, or midpoint tick if zero is absent. False leaves its label visible.
disabledbooleanfalseShow the unavailable-channel state.
classNamestring—Root CSS classes.

EpisodeLineChartSeries

FieldTypeDefaultPurpose
idstringrequiredStable signal identifier.
labelstring—Tooltip label; omit to exclude the readout.
data{ x: number[]; y: number[]; low?: number[]; high?: number[] }requiredAligned timestamps, values, and optional bounds.
colorstringrequiredCSS stroke color.
fillColor / fillOpacitystring / numberseries color / 0.16Band styling, independent of line opacity.
widthnumberchart lineWidth (2)Non-scaling CSS-pixel stroke width; zero hides the stroke.
dashstringsolidSVG dash pattern, such as '3 2.4'.
opacitynumber1Line opacity.
linecap'butt' | 'round' | 'square''butt'Stroke end shape.
readoutbooleantrueInclude a labeled series in the tooltip.
ghostbooleanfalseDim its readout and add a tgt suffix for reference signals.
formatValue(v: number) => stringv => 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.