Documentation / @ripl/charts

@ripl/charts

Pre-built, animated chart components for Ripl — a unified API for 2D graphics rendering in the browser.

Installation

npm install @ripl/charts

Chart Types

Category	Charts
Cartesian	Bar, Line, Area, Scatter, Trend (multi-series bar/line), Stock, Realtime
Radial	Pie/Donut, Radar, Polar Area, Polar Scatter, Radial Bar, Gauge, Sunburst
Relational	Sankey, Chord, Force-Directed, Arc Diagram
Distribution	Heatmap, Treemap, Packed Circle, Funnel
Scheduling	Gantt

Usage

import {
    BarChart,
} from '@ripl/charts';

const chart = new BarChart('#chart', {
    data: [
        { label: 'A',
            value: 10 },
        { label: 'B',
            value: 25 },
        { label: 'C',
            value: 15 },
    ],
    keyBy: 'label',
    series: [
        { valueBy: item => item.value },
    ],
});

Features

• Animated transitions — Smooth entry, update, and exit animations out of the box
• Interactive — Tooltips, crosshairs, hover effects, and click events
• Configurable — Axes, legends, grids, colors, padding, and more
• Canvas & SVG — Renders to either context via Ripl's unified API
• Tree-shakable — Import only the chart types you need

Documentation

Full documentation, options reference, and interactive demos are available at ripl.run.

License

MIT

Classes

Class	Description
ArcDiagramChart	Arc diagram: a cartesian axis whose points are nodes, connected by semicircular arcs whose thickness encodes the link value. Nodes are laid out in order along the axis (horizontal by default, or vertical), optionally sized by their connection count. On entry the arcs draw out of each node and cascade along the axis — a ripple that fades each node in as its arcs reach it — and updates animate arcs reshaping and nodes resizing. Supports labels, tooltips, and typed node/link interaction events.
AreaChart	Area chart rendering filled regions beneath series lines.
BarChart	Bar chart supporting vertical/horizontal orientation and grouped/stacked modes.
BoxPlotChart	Box-plot chart: summarises a numeric field per category with the shared boxplotStats transform and draws a box (Q1–Q3) with a median line, whiskers to the 1.5×IQR fences, and outlier points. Boxes fade/grow in on entry and animate out on exit.
CartesianChart	Base class providing shared cartesian component lifecycle and layout.
Chart	Abstract base class for all chart types, providing the scene, renderer, animation, colour management, title/legend layout, and the render/update lifecycle that every concrete chart builds on. Consumers never instantiate this directly — each chart exposes a createXChart factory (e.g. createBarChart) and this class supplies the shared behaviour behind it.
ChartLayout	Tracks the remaining free space within a chart and allows components to reserve bands from any edge. The order of reservation determines stacking: bands reserved first sit furthest from the plot area.
ChordChart	Chord diagram visualizing inter-relationships in a square matrix.
ColorLegend	A continuous-colour legend: a gradient bar (approximated by solid segments so it works identically on Canvas and SVG) annotated with formatted value labels drawn from a ColorScale. Renders into a reserved region like the other chart components; formatting is supplied explicitly, keeping the scale and the formatter decoupled.
ForceDirectedChart	Force-directed network chart laying out nodes and links with a settling physics simulation.
FunnelChart	Funnel chart rendering horizontally centered bars of decreasing width.
GanttChart	Gantt chart rendering time-based task bars on a categorical y-axis and time x-axis.
GaugeChart	Gauge chart displaying a single value on a 270-degree arc.
HeatmapChart	Heatmap chart rendering a grid of colored cells on two categorical axes.
HistogramChart	Histogram chart: bins a numeric field with the shared bin transform and draws each bin as a bar on a continuous value axis against a frequency axis. Supports animated entry/update/exit, tooltips, grid, and a chart title.
LineChart	Line chart rendering one or more series as polylines with optional markers.
PackedCircleChart	Packed circle chart rendering each datum as a circle whose area encodes its value, arranged in a tight, non-overlapping cluster. Great for showing many parts of a whole without the rigid grid of a treemap. Supports labels on sufficiently large circles, tooltips, and animated transitions.
PieChart	Pie chart rendering proportional arc segments with optional inner radius (donut).
PolarAreaChart	Polar area chart rendering equal-angle segments whose radius encodes value.
PolarScatterChart	Polar scatter chart plotting points by angle and radius on a circular grid.
RadarChart	Radar (spider) chart plotting multi-axis data as filled polygonal areas.
RadialBarChart	Radial bar chart rendering each category as a concentric ring whose arc length encodes its value.
RealtimeChart	Realtime streaming chart rendering continuously updating line/area series.
Ribbon	A chord diagram ribbon connecting two arc segments with quadratic Bézier curves through the center.
SankeyChart	Sankey diagram visualizing directional flow between nodes.
SankeyLinkPath	A curved Sankey link shape rendered as a cubic Bézier curve between source and target points.
ScatterChart	Scatter chart (bubble chart) plotting data points as circles on two continuous axes.
StockChart	Candlestick (stock) chart rendering OHLC data with optional volume bars.
SunburstChart	Sunburst chart rendering hierarchical data as concentric arc rings.
TreemapChart	Abstract base class for all chart types, providing the scene, renderer, animation, colour management, title/legend layout, and the render/update lifecycle that every concrete chart builds on. Consumers never instantiate this directly — each chart exposes a createXChart factory (e.g. createBarChart) and this class supplies the shared behaviour behind it.
TrendChart	Trend chart combining bar and line series on shared categorical/value axes.

Interfaces

Interface	Description
ArcDiagramChartEventMap	Events emitted by an ArcDiagramChart that consumers can subscribe to via chart.on(...).
ArcDiagramChartOptions	Options for configuring an ArcDiagramChart.
ArcDiagramLink	A link between two nodes.
ArcDiagramLinkEvent	Payload emitted for arc diagram link interaction events.
ArcDiagramNode	A node in an arc diagram.
ArcDiagramNodeEvent	Payload emitted for arc diagram node interaction events.
AreaChartEventMap	Events emitted by an AreaChart that consumers can subscribe to via chart.on(...).
AreaChartMarkerEvent	Payload emitted for area marker interaction events.
AreaChartOptions	Options for configuring an AreaChart.
AreaChartSeriesOptions	Configuration for an individual area chart series.
BarChartBarEvent	Payload emitted for bar interaction events.
BarChartEventMap	Events emitted by a BarChart that consumers can subscribe to via chart.on(...).
BarChartOptions	Options for configuring a BarChart.
BarChartSeriesOptions	Configuration for an individual bar chart series.
BaseChartOptions	Base options shared by all chart types.
BaseTrendChartSeriesOptions	Base configuration shared by all trend chart series types.
Bin	A histogram bin covering the half-open interval [x0, x1) (the last bin includes x1).
BinOptions	Options for bin.
BoxPlotBoxEvent	Payload emitted for box interaction events.
BoxPlotChartEventMap	Events emitted by a BoxPlotChart that consumers can subscribe to via chart.on(...).
BoxPlotChartOptions	Options for configuring a BoxPlotChart.
BoxplotStats	Five-number summary plus IQR and outliers, as used by a box plot.
CartesianChartOptions	Options shared by all cartesian charts.
CartesianSetup	Declares which optional cartesian components a chart wants constructed.
ChartAnimationOptions	Fully resolved chart animation options.
ChartArea	A rectangular region expressed as a top-left origin plus dimensions.
ChartAxisItemOptions	Options for a single axis (x or y).
ChartAxisOptions	Combined x and y axis configuration.
ChartCrosshairOptions	Fully resolved chart crosshair options.
ChartDataLabelsOptions	Fully resolved data label options.
ChartGridOptions	Fully resolved chart grid options.
ChartLegendOptions	Fully resolved chart legend options.
ChartPadding	Padding with explicit top, right, bottom, and left values.
ChartSegmentLabelsOptions	Fully resolved segment-label options for radial charts.
ChartTitleOptions	Fully resolved chart title options.
ChartTooltipOptions	Fully resolved chart tooltip options.
ChartYAxisItemOptions	Y-axis specific options extending the base axis item with a left/right position.
ChordChartArcEvent	Payload emitted for chord outer-arc interaction events.
ChordChartEventMap	Events emitted by a ChordChart that consumers can subscribe to via chart.on(...).
ChordChartOptions	Options for configuring a ChordChart.
ChordChartRibbonEvent	Payload emitted for chord ribbon interaction events.
ColorLegendComponentOptions	Options for constructing a ColorLegend.
ColorLegendOptions	Visual options for a ColorLegend.
DataLabelSpec	Describes a single data label to render.
ForceDirectedChartEventMap	Events emitted by a ForceDirectedChart that consumers can subscribe to via chart.on(...).
ForceDirectedChartOptions	Options for configuring a ForceDirectedChart.
ForceDirectedLinkEvent	Payload emitted for force-directed link interaction events.
ForceDirectedNodeEvent	Payload emitted for force-directed node interaction events.
ForceNetworkLink	A link between two nodes.
ForceNetworkNode	A node in a force-directed network.
FunnelChartEventMap	Events emitted by a FunnelChart that consumers can subscribe to via chart.on(...).
FunnelChartOptions	Options for configuring a FunnelChart.
FunnelChartSegmentEvent	Payload emitted for funnel segment interaction events.
GanttChartEventMap	Events emitted by a GanttChart that consumers can subscribe to via chart.on(...).
GanttChartOptions	Options for configuring a GanttChart.
GanttChartTaskEvent	Payload emitted for gantt task interaction events.
GaugeChartEventMap	Events emitted by a GaugeChart that consumers can subscribe to via chart.on(...).
GaugeChartOptions	Options for configuring a GaugeChart.
GaugeChartValueEvent	Payload emitted for gauge value interaction events.
HeatmapChartCellEvent	Payload emitted for heatmap cell interaction events.
HeatmapChartEventMap	Events emitted by a HeatmapChart that consumers can subscribe to via chart.on(...).
HeatmapChartOptions	Options for configuring a HeatmapChart.
HistogramBinEvent	Payload emitted for histogram bin interaction events.
HistogramChartEventMap	Events emitted by a HistogramChart that consumers can subscribe to via chart.on(...).
HistogramChartOptions	Options for configuring a HistogramChart.
HoverHighlightOptions	Options describing how an element should respond to hover.
HoverTooltip	Minimal tooltip surface required by the hover helper (decouples it from the Tooltip class).
InteractionPoint	The pointer position passed to interaction callbacks.
KdeOptions	Options for kde.
LinearRegression	A fitted simple linear regression.
LineChartEventMap	Events emitted by a LineChart that consumers can subscribe to via chart.on(...).
LineChartMarkerEvent	Payload emitted for line marker interaction events.
LineChartOptions	Options for configuring a LineChart.
LineChartSeriesOptions	Configuration for an individual line chart series.
PackedCircleChartCellEvent	Payload emitted for packed circle interaction events.
PackedCircleChartEventMap	Events emitted by a PackedCircleChart that consumers can subscribe to via chart.on(...).
PackedCircleChartOptions	Options for configuring a PackedCircleChart.
Padding	Resolved padding with explicit top, right, bottom, and left values.
PieChartEventMap	Events emitted by a PieChart that consumers can subscribe to via chart.on(...).
PieChartOptions	Options for configuring a PieChart.
PieChartSegmentEvent	Payload emitted for pie segment interaction events.
PolarAreaChartEventMap	Events emitted by a PolarAreaChart that consumers can subscribe to via chart.on(...).
PolarAreaChartOptions	Options for configuring a PolarAreaChart.
PolarAreaChartSegmentEvent	Payload emitted for polar-area segment interaction events.
PolarScatterChartEventMap	Events emitted by a PolarScatterChart that consumers can subscribe to via chart.on(...).
PolarScatterChartOptions	Options for configuring a PolarScatterChart.
PolarScatterMarkerEvent	Payload emitted for polar scatter marker interaction events.
PolarScatterSeriesOptions	Configuration for an individual polar scatter series.
RadarChartEventMap	Events emitted by a RadarChart that consumers can subscribe to via chart.on(...).
RadarChartOptions	Options for configuring a RadarChart.
RadarChartPointEvent	Payload emitted for radar point interaction events.
RadarChartSeriesOptions	Configuration for an individual radar chart series.
RadialBarChartBarEvent	Payload emitted for radial bar interaction events.
RadialBarChartEventMap	Events emitted by a RadialBarChart that consumers can subscribe to via chart.on(...).
RadialBarChartOptions	Options for configuring a RadialBarChart.
RadialLabelAnchor	A resolved anchor for a radial label, plus alignment.
RadialLabelInput	Input geometry for placing a label around a radial (arc-based) segment.
RadialLabelPlacement	Resolved inside and outside placements for a radial segment label.
RealtimeChartOptions	Options for configuring a RealtimeChart.
RealtimeChartSeriesOptions	Configuration for an individual realtime chart series.
ResolvedAnimation	A fully resolved animation ready to be applied to a transition.
RibbonState	State interface for a ribbon shape connecting two arc segments via quadratic curves.
SankeyChartEventMap	Events emitted by a SankeyChart that consumers can subscribe to via chart.on(...).
SankeyChartLinkEvent	Payload emitted for Sankey link interaction events.
SankeyChartNodeEvent	Payload emitted for Sankey node interaction events.
SankeyChartOptions	Options for configuring a SankeyChart.
SankeyLink	A directional flow between two nodes in a Sankey diagram.
SankeyLinkState	State interface for a Sankey link, defining source and target endpoint coordinates.
SankeyNode	A node in a Sankey diagram, with an optional typed datum carried through to node events.
ScatterChartEventMap	Events emitted by a ScatterChart that consumers can subscribe to via chart.on(...).
ScatterChartMarkerEvent	Payload emitted for scatter marker interaction events.
ScatterChartOptions	Options for configuring a ScatterChart.
ScatterChartSeriesOptions	Configuration for an individual scatter chart series.
SegmentLabelLayout	Fully resolved layout for a segment label: placement, content, styling, and leader-line points.
SegmentLabelSpec	Describes a single segment label to render.
StockChartCandleEvent	Payload emitted for stock candlestick interaction events.
StockChartEventMap	Events emitted by a StockChart that consumers can subscribe to via chart.on(...).
StockChartOptions	Options for configuring a StockChart.
SunburstChartEventMap	Events emitted by a SunburstChart that consumers can subscribe to via chart.on(...).
SunburstChartOptions	Options for configuring a SunburstChart.
SunburstChartSegmentEvent	Payload emitted for sunburst segment interaction events.
SunburstNode	A node in a sunburst hierarchy with optional nested children and an optional typed datum.
TreemapChartCellEvent	Payload emitted for treemap cell interaction events.
TreemapChartEventMap	Events emitted by a TreemapChart that consumers can subscribe to via chart.on(...).
TreemapChartOptions	Options for configuring a TreemapChart.
TrendChartAreaSeriesOptions	Series options for area-type series within a trend chart.
TrendChartBarSeriesOptions	Series options for bar-type series within a trend chart.
TrendChartEventMap	Events emitted by a TrendChart that consumers can subscribe to via chart.on(...).
TrendChartLineSeriesOptions	Series options for line-type series within a trend chart.
TrendChartOptions	Options for configuring a TrendChart.
TrendChartValueEvent	Payload emitted for trend bar/marker interaction events.

Type Aliases

Type Alias	Description
Accessor	A value accessor expressed as a property key, a constant, or a function.
ArcDiagramOrientation	How the node axis is oriented.
AxisFormatType	Built-in axis label format types.
BarChartMode	Whether multiple series are drawn side by side (grouped) or accumulated into one column (stacked).
BarChartOrientation	Whether bars are laid out vertically (default) or horizontally.
BorderRadiusInput	Border radius expressed as a uniform number or a per-corner tuple.
CartesianTarget	Re-exported for convenience to subclasses that accept a render target.
ChartAnimationInput	Animation input accepting a boolean toggle or partial options object.
ChartAxisInput	Axis input accepting a boolean toggle or a full axis options object.
ChartCrosshairInput	Crosshair input accepting a boolean toggle or partial options object.
ChartDataLabelsInput	Data label input: a boolean toggle, a LabelAnchor string selecting where labels sit, or a partial options object.
ChartGridInput	Grid input accepting a boolean toggle or partial options object.
ChartLegendInput	Legend input accepting a boolean, position string, or partial options object.
ChartOptions	Alias for a chart's options type, used by factory helpers for readability and future augmentation.
ChartSegmentLabelsInput	Segment-label input: a boolean toggle, a SegmentLabelPosition string (which also enables labels), or a partial options object.
ChartSide	An edge of the layout from which a band can be reserved.
ChartTitleInput	Title input accepting a plain string or partial options object.
ChartTooltipInput	Tooltip input accepting a boolean toggle or partial options object.
ColorLegendOrientation	Orientation of the colour legend bar.
CrosshairAxis	Which axis the crosshair tracks.
EaseName	Named easing function identifiers.
LabelAnchor	Where a data label is anchored relative to its marker/bar.
LegendPosition	Position of the chart legend relative to the chart area.
LineStyle	How a series line is stroked: a preset, or a custom canvas dash array.
NumericAccessor	A strongly-typed numeric accessor: a numeric-valued property key of TData, or a function returning a number. Using this (instead of a bare keyof TData) makes the compiler reject a key that points at a non-numeric field. Fields that also accept a fixed constant (e.g. a scatter sizeBy) widen this with `
NumericKey	The keys of TData whose values are number. Resolves to never for unknown/loose data.
PaddingInput	Padding expressed as a uniform number or a [top, right, bottom, left] tuple.
SegmentLabelPosition	Where a radial segment label sits: inside the segment, or outside with a leader line.
SeriesType	Supported series visualization types within a trend chart.
TitlePosition	Position of the chart title relative to the chart area.
TrendChartSeriesOptions	Discriminated union of all trend chart series option types.
ValueFormatInput	A value formatter accepted anywhere a chart renders a raw value as text (tooltips, data labels, pie segment labels). Either a built-in format type or a custom callback.

Variables

Variable	Description
ANIMATION_REFERENCE	Reference durations (in ms, at the default animation speed) for each transition kind.
DEFAULT_NUMBER_PRECISION	Default maximum number of decimal places applied when rendering numeric values as text.
SEGMENT_LABEL_FONT	Shared segment-label style constants. Every chart routes its segment labels through these so the appearance is identical across chart types and across the Canvas and SVG contexts. The cross-context inconsistency this fixes came from labels that omitted font, leaving each backend to fall back to its own default — always set an explicit font.
SEGMENT_LABEL_INSIDE_FILL	Fill for labels drawn inside a segment (on top of the filled shape).
SEGMENT_LABEL_OUTSIDE_FILL	Fill for labels drawn outside a segment (on the chart background).

Functions

Function	Description
applyHoverHighlight	Wires consistent hover behaviour (highlight transition + optional tooltip) onto an element. Safe to call repeatedly on the same persistent element across renders — prior listeners are disposed first so handlers never accumulate.
bin	Bins numeric values into a histogram. Without explicit thresholds, a "nice" uniform bin width is derived from the target bin count (Sturges' rule by default). Values outside the domain are dropped.
boxplotStats	Computes the box-plot five-number summary, splitting values beyond 1.5×IQR out as outliers.
computeStackOffset	Computes the stacked baseline offset for a series at a given data item. Positive and negative values stack independently so diverging stacks render correctly. Series earlier in the array sit closer to the baseline.
createArcDiagramChart	Factory function that creates a new ArcDiagramChart instance.
createAreaChart	Factory function that creates a new AreaChart instance.
createBarChart	Factory function that creates a new BarChart instance.
createBoxPlotChart	Factory function that creates a new BoxPlotChart.
createChordChart	Factory function that creates a new ChordChart instance.
createColorLegend	Factory function that creates a new ColorLegend.
createDataLabel	Creates a data label Text element (at opacity 0) positioned by its anchor.
createForceDirectedChart	Factory function that creates a new ForceDirectedChart instance.
createFunnelChart	Factory function that creates a new FunnelChart instance.
createGanttChart	Factory function that creates a new GanttChart instance.
createGaugeChart	Factory function that creates a new GaugeChart instance.
createHeatmapChart	Factory function that creates a new HeatmapChart instance.
createHistogramChart	Factory function that creates a new HistogramChart.
createLineChart	Factory function that creates a new LineChart instance.
createPackedCircleChart	Factory function that creates a new PackedCircleChart instance.
createPieChart	Factory function that creates a new PieChart instance.
createPolarAreaChart	Factory function that creates a new PolarAreaChart instance.
createPolarScatterChart	Factory function that creates a new PolarScatterChart instance.
createRadarChart	Factory function that creates a new RadarChart instance.
createRadialBarChart	Factory function that creates a new RadialBarChart instance.
createRealtimeChart	Factory function that creates a new RealtimeChart instance.
createRibbon	Factory function that creates a new Ribbon instance.
createSankeyChart	Factory function that creates a new SankeyChart instance.
createSankeyLink	Factory function that creates a new SankeyLinkPath instance.
createScatterChart	Factory function that creates a new ScatterChart instance.
createSegmentLabel	Creates a segment label Text with all style properties set explicitly (never inheriting the context default), guaranteeing identical rendering across chart types and Canvas/SVG contexts.
createStockChart	Factory function that creates a new StockChart instance.
createSunburstChart	Factory function that creates a new SunburstChart instance.
createTreemapChart	Factory function that creates a new TreemapChart instance.
createTrendChart	Factory function that creates a new TrendChart instance.
deviation	The population standard deviation of the values.
elementIsRibbon	Type guard that checks whether a value is a Ribbon instance.
elementIsSankeyLink	Type guard that checks whether a value is a SankeyLinkPath instance.
exitElement	Transitions an element to a terminal state (defaulting to fully transparent) and then destroys it, giving every chart a consistent exit animation. When animation is disabled the element is destroyed immediately.
formatNumber	Formats a numeric value as a localized string, capping the precision at precision decimal places (default DEFAULT_NUMBER_PRECISION). Integers render without decimals; fractional values are rounded to at most precision places with trailing zeros stripped. Non-numeric values fall back to String(value). This is the shared entry point every chart uses so labels, axes, tooltips, and tick marks share one consistent precision cap.
kde	Returns a Gaussian kernel density estimator f(x) for the values. The bandwidth defaults to Silverman's rule; pass one explicitly for tighter or smoother density curves.
linearRegression	Fits a simple least-squares linear regression to [x, y] points and reports its R².
mean	The arithmetic mean of the values (NaN when empty).
normalizeAnimation	Normalizes animation input into fully resolved ChartAnimationOptions.
normalizeAxis	Normalizes axis input into a full ChartAxisOptions object with both x and y.
normalizeAxisItem	Normalizes a single axis item input into fully resolved options.
normalizeCrosshair	Normalizes crosshair input into fully resolved ChartCrosshairOptions.
normalizeDataLabels	Normalizes a data label input into fully resolved ChartDataLabelsOptions.
normalizeGrid	Normalizes grid input into fully resolved ChartGridOptions.
normalizeLegend	Normalizes legend input into fully resolved ChartLegendOptions.
normalizePadding	Normalizes a padding input into a Padding object, or returns undefined if no input.
normalizeSegmentLabels	Normalizes a segment-label input into fully resolved ChartSegmentLabelsOptions.
normalizeTitle	Normalizes a title input into fully resolved ChartTitleOptions.
normalizeTooltip	Normalizes tooltip input into fully resolved ChartTooltipOptions.
normalizeYAxisItem	Normalizes a Y-axis item input into fully resolved options with position.
quantile	The p-quantile (0–1) of the values via linear interpolation between order statistics.
resolveAccessor	Normalises an Accessor into a function. Property keys read the field, functions are passed through, and any other value is treated as a constant.
resolveAnimation	Resolves chart animation options for a given reference duration, scaling by the configured speed and collapsing to 0/disabled when animation is turned off.
resolveDataLabelLayout	Resolves the anchored position and text alignment for a data label.
resolveEase	Resolves an ease name or function to an Ease function, defaulting to easeOutCubic.
resolveFormatLabel	Resolves an axis format type or custom formatter into a label formatting function.
resolveLineDash	Resolves a LineStyle into a lineDash array ([] for a solid line).
resolveRadialLabel	Computes both the inside (centroid) and outside (leader-line) label placements for a radial segment. Shared by the pie and polar-area charts so their inside/outside label behaviour — and the elbow leader line — stay identical. The outside textAlign flips by hemisphere so text reads away from the centre.
resolveSegmentLabelLayout	Resolves a segment's label into a ready-to-render layout (inside centroid or outside leader line), honouring visibility, an optional minimum-angle clutter guard, and position/font/colour options. Shared by the pie and polar-area charts so their label behaviour is identical.
resolveValueFormat	Resolves a value formatter into a function, always returning a usable formatter (falling back to String when no custom format is supplied). Convenience wrapper over resolveFormatLabel for the value-as-text sites that always need to print something.
rollup	Groups values by a key and reduces each group, returning a Map of key → reduced value.
stagger	Computes a per-element stagger delay so that a collection of entering elements animate in sequence rather than all at once. Returns 0 when there is nothing to stagger.