Charts — Realtime Swarm Chart — Semiotic

Home · Getting Started · Charts · Features · Playground

This page requires JavaScript for interactive chart demos.

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

View on GitHub · npx semiotic-ai for CLI access

Machine-readable page content

Canonical: https://semiotic.nteract.io/charts/realtime-swarm-chart

RealtimeSwarmChart

charts

import { RealtimeSwarmChart } from "semiotic"

Wraps: StreamXYFrame

RealtimeSwarmChart renders individual data points as dots at their (time, value) coordinates, creating a streaming scatter or swarm visualization. It wrapsStreamXYFrame withchartType="swarm" and promotes dot styling to top-level props. Create a ref and call ref.current.push(point) in asetInterval to stream data in. Supports category-based color coding and threshold coloring via annotations.

Quick Start

Create a ref, push data points on an interval, and RealtimeSwarmChart handles the rest. The sliding window keeps the most recent points in view.

JSX

import { RealtimeSwarmChart } from "semiotic" import { useRef, useEffect } from "react" function StreamingSwarm() { const chartRef = useRef() const indexRef = useRef(0) useEffect(() => { const id = setInterval(() => { chartRef.current?.push({ time: indexRef.current++, value: 10 + Math.random() * 80 }) }, 30) return () => clearInterval(id) }, []) return ( <RealtimeSwarmChart ref={chartRef} radius={3} fill="#007bff" opacity={0.7} windowSize={200} showAxes={true} /> ) }

Examples

Color-Coded by Category

Use categoryAccessor and colors to color-code dots by group, such as different sensors or event types.

JSX

const sensors = ["sensor1", "sensor2", "sensor3"] useEffect(() => { const id = setInterval(() => { const i = indexRef.current++ const sensor = sensors[i % 3] const base = sensor === "sensor1" ? 60 : sensor === "sensor2" ? 45 : 30 chartRef.current?.push({ time: i, value: base + (Math.random() - 0.5) * 20, sensor }) }, 30) return () => clearInterval(id) }, []) <RealtimeSwarmChart ref={chartRef} categoryAccessor="sensor" colors={{ sensor1: "#007bff", sensor2: "#28a745", sensor3: "#fd7e14" }} radius={4} opacity={0.8} windowSize={200} showAxes={true} />

Custom Dot Styling

Control the appearance with radius,fill, opacity, and stroke to create a distinctive look. Here the data follows a sinusoidal pattern with random noise.

JSX

useEffect(() => { const id = setInterval(() => { const i = indexRef.current++ chartRef.current?.push({ time: i, value: 50 + Math.sin(i * 0.08) * 25 + (Math.random() - 0.5) * 10 }) }, 30) return () => clearInterval(id) }, []) <RealtimeSwarmChart ref={chartRef} radius={5} fill="#6f42c1" opacity={0.6} stroke="#4c2889" strokeWidth={1} windowSize={200} showAxes={true} />

Props

Prop	Type	Required	Default	Description
`data`	array	—	`[]`	Controlled data array. Each object should contain fields matched by timeAccessor and valueAccessor.
`timeAccessor`	string \| function	—	`"time"`	Field name or function to access the time value from each data point.
`valueAccessor`	string \| function	—	`"value"`	Field name or function to access the numeric value from each data point.
`size`	[number, number]	—	`[500, 300]`	Chart dimensions as [width, height].
`margin`	object	—	—	Chart margins: { top, right, bottom, left }.
`arrowOfTime`	"left" \| "right"	—	`"right"`	Direction that time flows across the chart.
`windowMode`	"sliding" \| "growing"	—	`"sliding"`	Data retention strategy. "sliding" discards old points beyond windowSize.
`windowSize`	number	—	`200`	Ring buffer capacity when using sliding window mode.
`timeExtent`	[number, number]	—	—	Fixed time domain. Defaults to auto-fit.
`valueExtent`	[number, number]	—	—	Fixed value domain. Defaults to auto-fit.
`yScaleType`	"linear" \| "log" \| "symlog"	—	`"linear"`	Value-axis scale. symlog supports signed values while compressing large magnitudes.
`extentPadding`	number	—	—	Padding factor applied to auto-computed extents.
`categoryAccessor`	string \| function	—	—	Category accessor for color-coding dots by group.
`colors`	object	—	—	Category-to-color map when using categoryAccessor.
`radius`	number	—	—	Dot radius in pixels.
`fill`	string	—	—	Dot fill color when no categoryAccessor is set.
`opacity`	number	—	—	Dot opacity (0 to 1).
`stroke`	string	—	—	Dot stroke (outline) color.
`strokeWidth`	number	—	—	Dot stroke width.
`pointStyle`	function	—	—	Per-datum dot style callback. Returned fill, stroke, strokeWidth, opacity, and r values override chart defaults.
`showAxes`	boolean	—	`true`	Show canvas-drawn axes.
`background`	string	—	—	Background fill color for the chart area.
`enableHover`	boolean \| object	—	—	Enable hover annotations on dots.
`tooltipContent`	function	—	—	Custom tooltip render function. Receives hover data.
`onHover`	function	—	—	Callback fired on hover. Receives hover data or null.
`annotations`	array	—	—	Array of annotation objects, including threshold coloring rules.
`svgAnnotationRules`	function	—	—	Custom SVG annotation render function.
`tickFormatTime`	function	—	—	Custom formatter for time axis tick labels.
`tickFormatValue`	function	—	—	Custom formatter for value axis tick labels.
`className`	string	—	—	CSS class name for the chart container.

Graduating to the Frame

When you need full control — threshold coloring, combined chart types, or custom canvas marks — graduate toStreamXYFrame directly. Every RealtimeSwarmChart is just a configuredStreamXYFrame under the hood.

Chart (simple)

JSX

import { RealtimeSwarmChart } from "semiotic" <RealtimeSwarmChart ref={chartRef} data={sensorStream} timeAccessor="time" valueAccessor="value" categoryAccessor="sensor" colors={{ sensor1: "#007bff", sensor2: "#28a745" }} radius={4} opacity={0.8} enableHover />

Frame (full control)

JSX

import { StreamXYFrame } from "semiotic" <StreamXYFrame ref={frameRef} chartType="swarm" data={sensorStream} timeAccessor="time" valueAccessor="value" categoryAccessor="sensor" barColors={{ sensor1: "#007bff", sensor2: "#28a745" }} swarmStyle={{ radius: 4, opacity: 0.8 }} hoverAnnotation={true} showAxes={true} size={[500, 300]} />

Note that colors on RealtimeSwarmChart maps tobarColors on StreamXYFrame, and dot styling props are grouped into a swarmStyle object at the Frame level.

RealtimeLineChart — streaming continuous line for time-series data
RealtimeHistogram — streaming temporal histograms with binned bars
RealtimeWaterfallChart — cumulative deltas as connected rising and falling bars
StreamXYFrame — the underlying Frame with full control over every rendering detail
Scatterplot — for static (non-realtime) point-based XY visualization