import { RealtimeWaterfallChart } from "semiotic"
RealtimeWaterfallChart visualizes cumulative deltas as connected bars that rise and fall from a running baseline. Positive values appear as gain bars and negative values as loss bars, with optional connector lines linking consecutive bars. It wrapsStreamXYFrame withchartType="waterfall" and promotes waterfall styling to top-level props. Create a ref and callref.current.push(point) in a setInterval to stream data in.
Quick Start
Create a ref, push delta data points on an interval, and RealtimeWaterfallChart handles the rest. The sliding window keeps the most recent points in view. Positive values render as gain bars, negative values as loss bars.
JSX
import { RealtimeWaterfallChart } from "semiotic" import { useRef, useEffect } from "react" function StreamingWaterfall() { const chartRef = useRef() const indexRef = useRef(0) useEffect(() => { const id = setInterval(() => { chartRef.current?.push({ time: indexRef.current++, value: (Math.random() - 0.45) * 30 }) }, 40) return () => clearInterval(id) }, []) return ( <RealtimeWaterfallChart ref={chartRef} positiveColor="#28a745" negativeColor="#dc3545" windowSize={150} showAxes={true} /> ) }
Examples
With Connector Lines
Set connectorStroke to draw lines connecting consecutive bars, making the cumulative flow easier to follow.
JSX
<RealtimeWaterfallChart ref={chartRef} positiveColor="#28a745" negativeColor="#dc3545" connectorStroke="#999" connectorWidth={1} windowSize={150} />
Custom Colors and Gaps
Use positiveColor, negativeColor,gap, and stroke for a customized visual style.
JSX
<RealtimeWaterfallChart ref={chartRef} positiveColor="#007bff" negativeColor="#fd7e14" stroke="#333" strokeWidth={1} gap={2} connectorStroke="#aaa" connectorWidth={1} windowSize={150} />
Props
| Prop | Type | Required | Default | Description |
|---|
data | array | — | [] | Controlled data array. Each object should contain fields matched by timeAccessor and valueAccessor. Positive values represent gains, negative values represent losses. |
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 delta value (positive = gain, negative = loss). |
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. |
extentPadding | number | — | — | Padding factor applied to auto-computed extents. |
positiveColor | string | — | — | Fill color for positive (gain) bars. |
negativeColor | string | — | — | Fill color for negative (loss) bars. |
connectorStroke | string | — | — | Stroke color for connector lines between bars. Omit to hide connectors. |
connectorWidth | number | — | — | Stroke width for connector lines. |
gap | number | — | — | Gap between bars in pixels. |
stroke | string | — | — | Bar stroke (outline) color. |
strokeWidth | number | — | — | Bar stroke width. |
showAxes | boolean | — | true | Show canvas-drawn axes. |
background | string | — | — | Background fill color for the chart area. |
enableHover | boolean | object | — | — | Enable hover annotations on bars. |
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 rendered on the chart. |
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 more control — custom connector rendering, mixed chart types, or complex annotation logic — graduate toStreamXYFrame directly. Every RealtimeWaterfallChart is just a configuredStreamXYFrame under the hood.
Chart (simple)
JSX
import { RealtimeWaterfallChart } from "semiotic" <RealtimeWaterfallChart ref={chartRef} positiveColor="#28a745" negativeColor="#dc3545" connectorStroke="#999" windowSize={300} enableHover />
Frame (full control)
JSX
import { StreamXYFrame } from "semiotic" <StreamXYFrame ref={frameRef} chartType="waterfall" windowSize={300} waterfallStyle={{ positiveColor: "#28a745", negativeColor: "#dc3545", connectorStroke: "#999" }} hoverAnnotation={true} showAxes={true} size={[500, 300]} />
The waterfall styling props (positiveColor,negativeColor, connectorStroke, etc.) map directly to fields within the waterfallStyle object on StreamXYFrame.