Update a live chart by record ID — Semiotic

Home · Getting Started · Charts · Features · Playground

This page requires JavaScript for interactive chart demos.

AI / Machine-readable docs: llms.txt · llms-full.txt · Full AI Reference · schema.json · API Reference · Examples

View on GitHub · npx semiotic-ai for CLI access

Machine-readable page content

Canonical: https://semiotic.nteract.io/tasks/update-live-chart

Update a live chart by record ID

Maintain a bounded window of incoming records, apply corrections, and reconcile the display after reconnecting.

Show incoming observations, keep the UI stable, and correct existing records without duplicates.

Data needed:Synthetic observations with stable IDs, numeric event time and value; a four-record retained window.

Source checkout · Semiotic 3.9.2. Check the installed version before applying this guide.

Read as plain text Download task packet

When this fits

Use when a React application needs ref-based updates and explicit record correction.
The host owns subscription lifecycle, replay and reconnection policy.

Static SVG cannot establish subscription cleanup, correct replay or browser lifecycle behavior.
This simulated feed is not a production network protocol, durable queue or live service.

Try the complete example

Synthetic fixture. Three readings start at 09:00–09:02. Five events include two corrections and three new observations. The line uses observation time; the event counter records processing order.

Connected. Source event 0 of5; display through event 0.Display is current.

Next event: Correct obs-02 from 18 to 14.

Advance the source to inspect corrections and retention. Disconnect to freeze the displayed window, then reconnect to catch up.

Records currently retained by the chart
Record ID	Observation time	Reading (units)

Retention: the four latest observations by event time. Corrections replace a retained record by ID; older observations are removed. A reconnect takes the current source window, so it can recover a missed correction without retaining a complete event history. At completion, expect obs-03 = 17, obs-04 = 20, obs-05 = 16 and obs-06 = 19.

Use it in your application

LineChart from semiotic/line, inpush mode.

Mounted browser lifecycle · React browser only

Save as LiveChartExample.tsx beside its companion files below.

TSX

import React, { useEffect, useRef, useState } from "react" import { LineChart } from "semiotic/line" import { connectLiveChart, createLiveSource, LIVE_EVENTS, liveChartProps, type LiveSource, type Observation, } from "./live-chart" import "./live-chart.css" /** The optional source lets lifecycle tests inspect subscriptions directly. */ export function LiveChartSession({ source }: { source: LiveSource }) { const chartRef = useRef<React.ComponentRef<typeof LineChart>>(null) const [connected, setConnected] = useState(true) const [playing, setPlaying] = useState(false) const [sourceCursor, setSourceCursor] = useState(source.cursor) const [display, setDisplay] = useState<{ rows: Observation[]; cursor: number }>({ rows: [], cursor: 0, }) useEffect(() => { if (!connected || !chartRef.current) return // Effects run after the child ref is available. Cleanup also handles // React StrictMode's setup/cleanup/setup cycle without duplicate listeners. return connectLiveChart(source, chartRef.current, (rows, cursor) => { setDisplay({ rows, cursor }) }) }, [source, connected]) useEffect(() => { if (!playing || !connected) return const timer = window.setInterval(() => { const advanced = source.advance() setSourceCursor(source.cursor) if (!advanced || source.cursor === LIVE_EVENTS.length) setPlaying(false) }, 1_000) return () => window.clearInterval(timer) }, [source, playing, connected]) function advance() { source.advance() setSourceCursor(source.cursor) } const finished = sourceCursor === LIVE_EVENTS.length const lag = sourceCursor - display.cursor return ( <section className="task-live" aria-label="Live chart demonstration"> <p> <strong>Synthetic fixture.</strong> Three readings start at 09:00–09:02. Five events include two corrections and three new observations. The line uses observation time; the event counter records processing order. </p> <div className="task-live__controls"> <button type="button" onClick={advance} disabled={finished || playing}> Advance source </button> <button type="button" onClick={() => setPlaying((value) => !value)} disabled={!connected || finished} > {playing ? "Pause replay" : "Play replay"} </button> <button type="button" onClick={() => { setPlaying(false) setConnected((value) => !value) }} > {connected ? "Disconnect" : "Reconnect"} </button> </div> <p role="status" aria-live="polite" data-testid="live-chart-status"> {connected ? "Connected" : "Disconnected"}. Source event {sourceCursor} of{" "} {LIVE_EVENTS.length}; display through event {display.cursor}.{" "} {lag ? `${lag} unapplied event${lag === 1 ? "" : "s"}.` : "Display is current."} </p> <p> {finished ? "Replay complete." : `Next event: ${LIVE_EVENTS[sourceCursor].label}.`} {!connected && " Advance the source while disconnected, then reconnect to replace the frozen display with the source’s current window."} </p> <div data-testid="live-chart-rendering"> {/* No data prop: push mode remains active across control re-renders. */} <LineChart ref={chartRef} {...liveChartProps} height={320} responsiveWidth /> </div> <div className="task-live__table"> <table> <caption>Records currently retained by the chart</caption> <thead> <tr> <th scope="col">Record ID</th> <th scope="col">Observation time</th> <th scope="col">Reading (units)</th> </tr> </thead> <tbody> {display.rows.map((row) => ( <tr key={row.id}> <th scope="row">{row.id}</th> <td>09:{String(row.minute).padStart(2, "0")}</td> <td>{row.value}</td> </tr> ))} </tbody> </table> </div> <p> Retention: the four latest observations by event time. Corrections replace a retained record by ID; older observations are removed. A reconnect takes the current source window, so it can recover a missed correction without retaining a complete event history. At completion, expect obs-03 = 17, obs-04 = 20, obs-05 = 16 and obs-06 = 19. </p> </section> ) } export default function LiveChartExample() { const [source, setSource] = useState(createLiveSource) const [session, setSession] = useState(0) function restart() { setSource(createLiveSource()) setSession((value) => value + 1) } return ( <> <LiveChartSession key={session} source={source} /> <button type="button" onClick={restart}> Restart fixture </button> </> ) }

Deterministic source and reconnect policy · Host-owned synthetic feed

Save as live-chart.ts beside its companion files below.

TSX

import type { ComponentRef } from "react" import type { LineChart } from "semiotic/line" export interface Observation { id: string minute: number value: number } export const RETAINED_RECORDS = 4 export const INITIAL_OBSERVATIONS: Observation[] = [ { id: "obs-01", minute: 0, value: 12 }, { id: "obs-02", minute: 1, value: 18 }, { id: "obs-03", minute: 2, value: 15 }, ] // Event order is processing order. A correction preserves the observation's // event time and ID; it does not create a new point at its arrival time. export const LIVE_EVENTS = [ { row: { id: "obs-02", minute: 1, value: 14 }, label: "Correct obs-02 from 18 to 14" }, { row: { id: "obs-04", minute: 3, value: 20 }, label: "Add obs-04 at minute 3" }, { row: { id: "obs-05", minute: 4, value: 16 }, label: "Add obs-05; discard obs-01" }, { row: { id: "obs-03", minute: 2, value: 17 }, label: "Correct obs-03 from 15 to 17" }, { row: { id: "obs-06", minute: 5, value: 19 }, label: "Add obs-06; discard obs-02" }, ] satisfies Array<{ row: Observation; label: string }> export const liveChartProps = { xAccessor: "minute", yAccessor: "value", pointIdAccessor: "id", xLabel: "Observation time (minutes after 09:00)", yLabel: "Synthetic reading (units)", title: "The latest four observations", description: "Synthetic observations by event time. Corrections keep their original time and record ID.", summary: "Advance the source to inspect corrections and retention. Disconnect to freeze the displayed window, then reconnect to catch up.", showPoints: true, showGrid: true, accessibleTable: true, xExtent: [0, 5] as [number, number], yExtent: [0, 24] as [number, number], } type FeedMessage = | { kind: "snapshot"; rows: Observation[]; cursor: number } | { kind: "change"; row: Observation; removed: string[]; cursor: number } /** A deterministic, in-memory source, not a network or ordering protocol. */ export function createLiveSource() { let rows = INITIAL_OBSERVATIONS.map((row) => ({ ...row })) let cursor = 0 const listeners = new Set<(message: FeedMessage) => void>() return { get cursor() { return cursor }, get subscriberCount() { return listeners.size }, get rows() { return rows.map((row) => ({ ...row })) }, subscribe(listener: (message: FeedMessage) => void) { listeners.add(listener) // Registration and snapshot are synchronous in this fixture. A remote // source needs an atomic snapshot/cursor handoff to avoid losing events. listener({ kind: "snapshot", rows: rows.map((row) => ({ ...row })), cursor }) return () => { listeners.delete(listener) } }, advance() { const event = LIVE_EVENTS[cursor] if (!event) return false const byId = new Map(rows.map((row) => [row.id, row])) byId.set(event.row.id, { ...event.row }) const ordered = [...byId.values()].sort((a, b) => a.minute - b.minute) const removed = ordered.slice(0, -RETAINED_RECORDS).map((row) => row.id) rows = ordered.slice(-RETAINED_RECORDS) cursor += 1 for (const listener of listeners) { listener({ kind: "change", row: { ...event.row }, removed, cursor }) } return true }, } } export type LiveSource = ReturnType<typeof createLiveSource> type LiveChartHandle = ComponentRef<typeof LineChart> /** Connect only after React mounts the chart and supplies its ref. */ export function connectLiveChart( source: LiveSource, chart: LiveChartHandle, onReadback: (rows: Observation[], cursor: number) => void, ) { const retainedIds = new Set<string>() return source.subscribe((message) => { if (message.kind === "snapshot") { chart.clear() chart.pushMany(message.rows) retainedIds.clear() for (const row of message.rows) retainedIds.add(row.id) } else { for (const id of message.removed) { chart.remove(id) retainedIds.delete(id) } if (retainedIds.has(message.row.id)) { chart.update(message.row.id, (previous) => ({ ...previous, ...message.row })) } else if (!message.removed.includes(message.row.id)) { chart.push(message.row) retainedIds.add(message.row.id) } } // Inspect the chart's retained store, rather than echoing the source rows. const actual = chart.getData().map((row) => ({ id: String(row.id), minute: Number(row.minute), value: Number(row.value), })) onReadback(actual, message.cursor) }) }

Example styles · Browser presentation

Save as live-chart.css beside its companion files below.

CSS

.task-live { min-width: 0; } .task-live__controls { display: flex; flex-wrap: wrap; gap: 0.6rem; } .task-live__controls button { min-height: 40px; padding: 0.4rem 0.8rem; } .task-live__table { overflow-x: auto; margin: 1rem 0; } .task-live__table table { width: 100%; border-collapse: collapse; } .task-live__table caption { text-align: left; font-weight: 600; margin-bottom: 0.5rem; } .task-live__table th, .task-live__table td { text-align: left; padding: 0.5rem; border-bottom: 1px solid var(--border-color, #aaa); }

Check the result

Repository source checks passed on 2026-09-07T19:35:59.815Z.

Corrections replace records by stable ID without increasing the retained count.
At most four records remain in the chart after new observations.
While disconnected, the displayed window remains unchanged; reconnect replaces it with the current source window.
Unmount and StrictMode cleanup leave no active subscription or playback timer.
After all five events, retained IDs obs-03 through obs-06 have values 17, 20, 16 and 19.

BASH

npx vitest run docs/src/pages/tasks/examples/live-chart.test.tsx npx playwright test --config playwright.docs-examples.config.ts integration-tests/docs-examples-task-live.spec.ts

These checks leave the following questions open:

Real transport failures, server retention, clock synchronization and production backpressure.
Performance on physical devices or under a production event rate.
Assistive-technology reception and organic adoption.

Repair and recheck

Pushed rows disappear when React renders again.

Omit data entirely in push mode. Push the initial window through the mounted ref; do not pass data={[]}.

Recheck:Change host UI state and confirm that the retained records survive.

Behavior contract: streaming.push-mode-data

A correction cannot find a record or creates duplicates.

Set pointIdAccessor to id and use update(id, updater). On reconnect, replace the bounded window from the authoritative host snapshot.

Recheck:Inspect the chart handle's data after correction and reconnect, including IDs, values and count.

Behavior contract: streaming.ref-mutations-require-id-accessors

Leave useful maintenance context

The host needs explicit correction and reconnect behavior over a bounded observation window.

Cleanup, stable IDs, retention, data-prop omission and reconnect replacement after lifecycle or dependency changes.

A static export records one window. It does not carry an active subscription, prove cleanup or promise future updates.

Keep project notes optional. A changed requirement or dependency policy can justify a different approach.

What to recheck after an update

Current source guidance; an installed-release introduction has not been established.

Assumption to revisit:A static render or an empty data array demonstrates a working live chart.

Omit data for push mode. Establish the subscription after the ref mounts, correct records by ID, clean up and reconcile from the authoritative window on reconnect.

Retained records and actual canvas paint through correction, disconnect, reconnect and restart.
Subscriptions and replay timers after unmount and StrictMode cleanup.

Production transport reliability and event-rate performance require their own environment-specific checks.

Inspect exact API, source identity and mode rules

Verified source checkout guidance; npm package, hosted site and MCP deployment identities require separate checks.

Content revision: sha256:2a4bd7657b540055ebeb5fc6a7f0fba4c10e31df80fdceb815a6bce711570e92

Selected properties copied from ai/schema.json; retrieve the component resource for the full schema. React push mode follows the included behavior contracts. Full resource: semiotic://schema/LineChart.

JSON

{ "type": "object", "properties": { "xAccessor": { "type": "string", "description": "Key or accessor function for x-axis values. Functions can derive a value, e.g. `d => d.timestamp`.", "default": "x", "x-semiotic-runtime-types": [ "string", "function" ] }, "yAccessor": { "type": "string", "description": "Key or accessor function for y-axis values. Functions support dynamic lookups, e.g. `d => d[d.metricLabel]`.", "default": "y", "x-semiotic-runtime-types": [ "string", "function" ] }, "pointIdAccessor": { "type": "string", "description": "Stable ID for point annotations and push-mode remove()/update().", "x-semiotic-runtime-types": [ "string", "function" ] }, "title": { "type": "string", "description": "Visible chart title and the chart's accessible name." }, "description": { "type": "string", "description": "Concise accessible description that overrides the chart's generated aria-label." }, "summary": { "type": "string", "description": "Screen-reader-only summary of the chart's key takeaway; include keyboard interaction guidance when relevant." }, "accessibleTable": { "type": [ "boolean", "object" ], "description": "Expose the chart data through Semiotic's screen-reader data table. Object form `{ portalTarget: string }` relocates its interactive UI to the DOM element with that ID.", "default": true, "oneOf": [ { "type": "boolean" }, { "type": "object", "additionalProperties": false, "required": [ "portalTarget" ], "properties": { "portalTarget": { "type": "string", "description": "ID of a DOM element outside any consumer-owned role=img wrapper. React callers may also pass an Element or a callback through the typed API." } } } ] }, "height": { "type": "number", "default": 400 }, "responsiveWidth": { "type": "boolean" } }, "requiredForStatic": [ "data" ] }

accessibility.description-props: High-level charts expose title for the visible name, description for a concise accessible description, summary for a screen-reader-only takeaway and interaction guidance, and accessibleTable for the data-table fallback.Put title, description, summary, and accessibleTable directly on the chart component when they appear in its schema. If a consumer-owned role=img wraps the chart, use accessibleTable: { portalTarget: "element-id" } and render that target outside the image. For generated L1–L3 description or a navigable chart tree, use ChartContainer with chartConfig plus describe and/or navigable; do not invent frameProps fields.
props.data-required-by-usage-mode: Static usage (`renderChart`, MCP previews, SSR snapshots, and copy/paste examples with immediate data) requires data in props. React push mode selects live ingestion by omitting data and mutating through a ref.Pass usageMode="push" to `semiotic-ai --doctor` when validating ref-based JSX with no data prop. Keep usageMode="static" or omit it for renderChart/MCP/static configs where data must be present.
streaming.push-mode-data: HOC push mode is selected by omitting the data prop entirely. Passing data={[]} is static empty data and can clear/reinitialize the frame on render.For live charts, create a ref, omit data, then call ref.current.push() or pushMany(). For static renderChart/MCP snapshots, provide data because renderChart cannot push later.
streaming.ref-mutations-require-id-accessors: push() and pushMany() can append without IDs, but remove(id) and update(id, updater) require a stable ID accessor: pointIdAccessor for XY/realtime charts, dataIdAccessor for ordinal charts, and nodeIDAccessor/edgeIdAccessor for network operations.When generating code that calls remove() or update(), include the matching ID accessor and make sure pushed rows carry that ID field.
rendering.renderchart-static-props: MCP renderChart and semiotic/server renderChart render a single static SVG/PNG snapshot. Browser-only realtime components and future ref pushes are not renderable through that path.Use renderChart only with renderable HOC components and complete static data. For live behavior, return React code with a ref and do not promise MCP-rendered output.

Agent-observed execution of repository tests; independent review is not recorded.