Chart Components API — 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/api/charts

Charts API Reference

A machine-readable index of every Semiotic Chart component. Each entry includes the import statement, a description, and the key props. For full documentation with live examples, follow the link to the individual chart page.

XY Charts

Continuous data plotted on x/y axes. All XY charts wrap StreamXYFrame.

LineChart

Full docs →

Visualizes trends and time series as connected lines.

import { LineChart } from "semiotic"

Prop	Type	Required	Default	Description
`data`	array	Yes	—	Array of data points or array of line objects with coordinates.
`xAccessor`	string \| function	—	`"x"`	Field name or function to access x values.
`yAccessor`	string \| function	—	`"y"`	Field name or function to access y values.
`lineBy`	string \| function	—	—	Group data into multiple lines by field or function.
`colorBy`	string \| function	—	—	Determine line color by field or function.
`curve`	string	—	`"linear"`	Interpolation: "linear", "monotoneX", "step", "basis", etc.
`showPoints`	boolean	—	`false`	Show data points on the line.
`fillArea`	boolean	—	`false`	Fill the area under the line.
`frameProps`	object	—	—	Escape hatch to pass any StreamXYFrame prop.

AreaChart

Full docs →

Filled area under a line -- emphasizes volume over time.

import { AreaChart } from "semiotic"

Prop	Type	Required	Default	Description
`data`	array	Yes	—	Array of data points, optionally grouped by category.
`xAccessor`	string \| function	—	`"x"`	Field name or function to access x values.
`yAccessor`	string \| function	—	`"y"`	Field name or function to access y values.
`areaBy`	string \| function	—	—	Group data into multiple areas by field or function.
`colorBy`	string \| function	—	—	Determine area color by field or function.
`curve`	string	—	`"monotoneX"`	Interpolation: "linear", "monotoneX", "step", etc.
`areaOpacity`	number	—	`0.7`	Opacity of the filled area.
`frameProps`	object	—	—	Escape hatch to pass any StreamXYFrame prop.

StackedAreaChart

Full docs →

Stacked filled areas showing part-to-whole composition over a continuous axis.

import { StackedAreaChart } from "semiotic"

Prop	Type	Required	Default	Description
`data`	array	Yes	—	Array of data points, grouped by category.
`xAccessor`	string \| function	—	`"x"`	Field name or function to access x values.
`yAccessor`	string \| function	—	`"y"`	Field name or function to access y values.
`areaBy`	string \| function	—	—	Group data into multiple stacked areas.
`colorBy`	string \| function	—	—	Determine area color for each stack.
`normalize`	boolean	—	`false`	Normalize to 100% stacked (proportional) areas.
`frameProps`	object	—	—	Escape hatch to pass any StreamXYFrame prop.

Scatterplot

Full docs →

Point-based XY visualization for exploring correlations.

import { Scatterplot } from "semiotic"

Prop	Type	Required	Default	Description
`data`	array	Yes	—	Array of data points with x and y properties.
`xAccessor`	string \| function	—	`"x"`	Field name or function to access x values.
`yAccessor`	string \| function	—	`"y"`	Field name or function to access y values.
`colorBy`	string \| function	—	—	Determine point color by field or function.
`sizeBy`	string \| function	—	—	Determine point size by field or function.
`sizeRange`	[number, number]	—	`[3, 15]`	Min and max radius when sizeBy is specified.
`pointRadius`	number	—	`5`	Default point radius when sizeBy is not specified.
`frameProps`	object	—	—	Escape hatch to pass any StreamXYFrame prop.

BubbleChart

Full docs →

Scatterplot with a third dimension encoded as bubble size.

import { BubbleChart } from "semiotic"

Prop	Type	Required	Default	Description
`data`	array	Yes	—	Array of data points with x, y, and size properties.
`xAccessor`	string \| function	—	`"x"`	Field name or function to access x values.
`yAccessor`	string \| function	—	`"y"`	Field name or function to access y values.
`sizeBy`	string \| function	Yes	—	Field name or function to determine bubble size (required).
`sizeRange`	[number, number]	—	`[5, 40]`	Min and max radius for bubbles.
`colorBy`	string \| function	—	—	Determine bubble color by field or function.
`bubbleOpacity`	number	—	`0.6`	Opacity of the bubbles.
`frameProps`	object	—	—	Escape hatch to pass any StreamXYFrame prop.

Heatmap

Full docs →

Grid of colored cells encoding value intensity.

import { Heatmap } from "semiotic"

Prop	Type	Required	Default	Description
`data`	array	Yes	—	Array of data points with x, y, and value properties.
`xAccessor`	string \| function	—	`"x"`	Field name or function to access x values.
`yAccessor`	string \| function	—	`"y"`	Field name or function to access y values.
`valueAccessor`	string \| function	—	`"value"`	Field name or function to access cell values for color encoding.
`colorScheme`	string	—	`"blues"`	"blues", "reds", "greens", "viridis", or "custom".
`showValues`	boolean	—	`false`	Show values as text labels in cells.
`frameProps`	object	—	—	Escape hatch to pass any StreamXYFrame prop.

Categorical Charts

Discrete/ordinal data. All categorical charts wrap StreamOrdinalFrame.

BarChart

Full docs →

Rectangular bars proportional to category values.

import { BarChart } from "semiotic"

Prop	Type	Required	Default	Description
`data`	array	Yes	—	Array of data points with category and value fields.
`categoryAccessor`	string \| function	—	`"category"`	Field name or function to access category values.
`valueAccessor`	string \| function	—	`"value"`	Field name or function to access numeric values.
`orientation`	"vertical" \| "horizontal"	—	`"vertical"`	Chart orientation.
`colorBy`	string \| function	—	—	Determine bar color by field or function.
`sort`	boolean \| string \| function	—	`false`	Sort bars: true, "asc", "desc", or custom comparator.
`frameProps`	object	—	—	Escape hatch to pass any StreamOrdinalFrame prop.

StackedBarChart

Full docs →

Bars subdivided into stacked segments for part-to-whole comparison.

import { StackedBarChart } from "semiotic"

Prop	Type	Required	Default	Description
`data`	array	Yes	—	Array of data points with category, subcategory, and value fields.
`categoryAccessor`	string \| function	—	`"category"`	Field name or function to access category values.
`stackBy`	string \| function	Yes	—	Field name or function for subcategory stacking.
`valueAccessor`	string \| function	—	`"value"`	Field name or function to access numeric values.
`orientation`	"vertical" \| "horizontal"	—	`"vertical"`	Chart orientation.
`normalize`	boolean	—	`false`	Normalize to 100% (percentage stacked).
`frameProps`	object	—	—	Escape hatch to pass any StreamOrdinalFrame prop.

LikertChart

Full docs →

Likert scale survey responses as diverging bars (horizontal) or stacked 100% bars (vertical).

import { LikertChart } from "semiotic"

Prop	Type	Required	Default	Description
`levels`	string[]	—	—	Ordered labels, negative → positive (default: 5-point scale)
`categoryAccessor`	string	—	—	Question/item field (default: "question")
`valueAccessor`	string	—	—	Integer score field for raw mode (default: "score")
`levelAccessor`	string	—	—	Level name field for pre-aggregated mode
`countAccessor`	string	—	—	Count field for pre-aggregated mode (default: "count")
`orientation`	string	—	—	"horizontal" (diverging, default) or "vertical" (stacked 100%)

SwarmPlot

Full docs →

Individual data points arranged to avoid overlap within categories.

import { SwarmPlot } from "semiotic"

Prop	Type	Required	Default	Description
`data`	array	Yes	—	Array of data points with category and value fields.
`categoryAccessor`	string \| function	—	`"category"`	Field name or function to access category values.
`valueAccessor`	string \| function	—	`"value"`	Field name or function to access numeric values.
`orientation`	"vertical" \| "horizontal"	—	`"vertical"`	Chart orientation.
`colorBy`	string \| function	—	—	Determine point color by field or function.
`sizeBy`	string \| function	—	—	Determine point size by field or function.
`pointRadius`	number	—	`4`	Default point radius.
`frameProps`	object	—	—	Escape hatch to pass any StreamOrdinalFrame prop.

BoxPlot

Full docs →

Statistical summary (quartiles, median, outliers) per category.

import { BoxPlot } from "semiotic"

Prop	Type	Required	Default	Description
`data`	array	Yes	—	Array of data points; multiple points per category compute quartiles.
`categoryAccessor`	string \| function	—	`"category"`	Field name or function to access category values.
`valueAccessor`	string \| function	—	`"value"`	Field name or function to access numeric values.
`orientation`	"vertical" \| "horizontal"	—	`"vertical"`	Chart orientation.
`colorBy`	string \| function	—	—	Determine box color by field or function.
`showOutliers`	boolean	—	`true`	Show outlier points beyond the whiskers.
`frameProps`	object	—	—	Escape hatch to pass any StreamOrdinalFrame prop.

DotPlot

Full docs →

Minimal Cleveland dot plot for precise value comparison across categories.

import { DotPlot } from "semiotic"

Prop	Type	Required	Default	Description
`data`	array	Yes	—	Array of data points with category and value fields.
`categoryAccessor`	string \| function	—	`"category"`	Field name or function to access category values.
`valueAccessor`	string \| function	—	`"value"`	Field name or function to access numeric values.
`orientation`	"vertical" \| "horizontal"	—	`"horizontal"`	Chart orientation (horizontal is typical for dot plots).
`colorBy`	string \| function	—	—	Determine dot color by field or function.
`sort`	boolean \| string \| function	—	`true`	Sort by value: true, "asc", "desc", or custom comparator.
`dotRadius`	number	—	`5`	Radius of the dots.
`frameProps`	object	—	—	Escape hatch to pass any StreamOrdinalFrame prop.

PieChart

Full docs →

Proportional slices in a circle for part-to-whole comparison.

import { PieChart } from "semiotic"

Prop	Type	Required	Default	Description
`data`	array	Yes	—	Array of data points with category and value fields.
`categoryAccessor`	string \| function	—	`"category"`	Field name or function to access slice labels.
`valueAccessor`	string \| function	—	`"value"`	Field name or function to access slice values.
`colorBy`	string \| function	—	—	Determine slice color by field or function.
`startAngle`	number	—	`0`	Starting angle in degrees.
`frameProps`	object	—	—	Escape hatch to pass any StreamOrdinalFrame prop.

DonutChart

Full docs →

Pie chart with a center hole, supports center content.

import { DonutChart } from "semiotic"

Prop	Type	Required	Default	Description
`data`	array	Yes	—	Array of data points with category and value fields.
`categoryAccessor`	string \| function	—	`"category"`	Field name or function to access slice labels.
`valueAccessor`	string \| function	—	`"value"`	Field name or function to access slice values.
`innerRadius`	number	—	`60`	Inner radius of the donut hole in pixels.
`centerContent`	ReactNode	—	—	Content rendered in the center of the donut.
`colorBy`	string \| function	—	—	Determine slice color by field or function.
`frameProps`	object	—	—	Escape hatch to pass any StreamOrdinalFrame prop.

GroupedBarChart

Full docs →

Side-by-side bars for comparing sub-categories within categories.

import { GroupedBarChart } from "semiotic"

Prop	Type	Required	Default	Description
`data`	array	Yes	—	Array of data points with category, group, and value fields.
`categoryAccessor`	string \| function	—	`"category"`	Field name or function to access category values.
`groupBy`	string \| function	Yes	—	Field name or function for sub-category grouping.
`valueAccessor`	string \| function	—	`"value"`	Field name or function to access numeric values.
`orientation`	"vertical" \| "horizontal"	—	`"vertical"`	Chart orientation.
`colorBy`	string \| function	—	—	Determine bar color by field or function.
`frameProps`	object	—	—	Escape hatch to pass any StreamOrdinalFrame prop.

Network Charts

Relational and hierarchical data. All network charts wrap StreamNetworkFrame.

ForceDirectedGraph

Full docs →

Force-simulated network layout for exploring relationships between nodes.

import { ForceDirectedGraph } from "semiotic"

Prop	Type	Required	Default	Description
`nodes`	array	Yes	—	Array of node objects with an id property.
`edges`	array	Yes	—	Array of edge objects with source and target properties.
`nodeIDAccessor`	string \| function	—	`"id"`	Field name or function to access node IDs.
`colorBy`	string \| function	—	—	Determine node color by field or function.
`nodeSize`	number \| string \| function	—	`8`	Fixed size, field name, or function for node radius.
`nodeSizeRange`	[number, number]	—	`[5, 20]`	Min and max radius for dynamic node sizing.
`showLabels`	boolean	—	`false`	Show text labels on each node.
`frameProps`	object	—	—	Escape hatch to pass any StreamNetworkFrame prop.

ChordDiagram

Full docs →

Circular layout showing flow magnitude between entities.

import { ChordDiagram } from "semiotic"

Prop	Type	Required	Default	Description
`edges`	array	Yes	—	Array of edge objects with source, target, and value properties.
`nodes`	array	—	`(inferred)`	Array of node objects. Inferred from edges if not provided.
`sourceAccessor`	string \| function	—	`"source"`	Field name or function to access source node.
`targetAccessor`	string \| function	—	`"target"`	Field name or function to access target node.
`valueAccessor`	string \| function	—	`"value"`	Field name or function to access edge value (chord width).
`colorBy`	string \| function	—	—	Determine node color by field or function.
`showLabels`	boolean	—	`true`	Show labels around the circumference.
`frameProps`	object	—	—	Escape hatch to pass any StreamNetworkFrame prop.

SankeyDiagram

Full docs →

Flow diagram with proportional ribbons connecting stages.

import { SankeyDiagram } from "semiotic"

Prop	Type	Required	Default	Description
`edges`	array	Yes	—	Array of edge objects with source, target, and value properties.
`nodes`	array	—	`(inferred)`	Array of node objects. Inferred from edges if not provided.
`sourceAccessor`	string \| function	—	`"source"`	Field name or function to access source node.
`targetAccessor`	string \| function	—	`"target"`	Field name or function to access target node.
`valueAccessor`	string \| function	—	`"value"`	Field name or function to access edge value (flow width).
`orientation`	"horizontal" \| "vertical"	—	`"horizontal"`	Layout orientation.
`nodeAlign`	"justify" \| "left" \| "right" \| "center"	—	`"justify"`	Node alignment strategy.
`showLabels`	boolean	—	`true`	Show node labels.
`frameProps`	object	—	—	Escape hatch to pass any StreamNetworkFrame prop.

TreeDiagram

Full docs →

Hierarchical layout: tree, cluster, treemap, circlepack, or partition.

import { TreeDiagram } from "semiotic"

Prop	Type	Required	Default	Description
`data`	object	Yes	—	Hierarchical data object with a children property.
`layout`	string	—	`"tree"`	"tree", "cluster", "partition", "treemap", or "circlepack".
`orientation`	"vertical" \| "horizontal" \| "radial"	—	`"vertical"`	Projection orientation.
`childrenAccessor`	string \| function	—	`"children"`	Field name or function to access children array.
`valueAccessor`	string \| function	—	`"value"`	Field name or function to access node value (for treemap/circlepack sizing).
`colorBy`	string \| function	—	—	Determine node color by field or function.
`showLabels`	boolean	—	`true`	Show node labels.
`frameProps`	object	—	—	Escape hatch to pass any StreamNetworkFrame prop.

Treemap

Full docs →

Space-filling rectangular hierarchy visualization.

import { Treemap } from "semiotic"

Prop	Type	Required	Default	Description
`data`	object	Yes	—	Hierarchical data object with a children property.
`childrenAccessor`	string \| function	—	`"children"`	Field name or function to access children array.
`valueAccessor`	string \| function	—	`"value"`	Field name or function to access node value for sizing.
`colorBy`	string \| function	—	—	Determine rectangle color by field or function.
`colorByDepth`	boolean	—	`false`	Color nodes by their depth in the hierarchy.
`showLabels`	boolean	—	`true`	Show text labels on rectangles.
`frameProps`	object	—	—	Escape hatch to pass any StreamNetworkFrame prop.

CirclePack

Full docs →

Nested circles representing hierarchical data.

import { CirclePack } from "semiotic"

Prop	Type	Required	Default	Description
`data`	object	Yes	—	Hierarchical data object with a children property.
`childrenAccessor`	string \| function	—	`"children"`	Field name or function to access children array.
`valueAccessor`	string \| function	—	`"value"`	Field name or function to access node value for sizing.
`colorBy`	string \| function	—	—	Determine circle color by field or function.
`colorByDepth`	boolean	—	`false`	Color nodes by their depth in the hierarchy.
`circleOpacity`	number	—	`0.7`	Opacity of the circles.
`showLabels`	boolean	—	`true`	Show text labels on circles.
`frameProps`	object	—	—	Escape hatch to pass any StreamNetworkFrame prop.

Realtime Charts

Canvas-rendered charts optimized for streaming data. All realtime charts wrap StreamXYFrame.

RealtimeLineChart

Full docs →

Continuously updating line from streaming data.

import { RealtimeLineChart } from "semiotic"

Prop	Type	Required	Default	Description
`data`	array	—	`[]`	Controlled data array with time and value fields.
`timeAccessor`	string \| function	—	`"time"`	Field name or function to access the time value.
`valueAccessor`	string \| function	—	`"value"`	Field name or function to access the numeric value.
`size`	[number, number]	—	`[500, 300]`	Chart dimensions as [width, height].
`windowMode`	"sliding" \| "growing"	—	`"sliding"`	"sliding" discards old points beyond windowSize; "growing" keeps all.
`windowSize`	number	—	`200`	Ring buffer capacity in sliding mode.
`stroke`	string	—	`"#007bff"`	Line color.
`enableHover`	boolean \| object	—	—	Enable hover annotations.

RealtimeHistogram

Full docs →

Binned bar chart that updates as new data arrives.

import { RealtimeHistogram } from "semiotic"

Prop	Type	Required	Default	Description
`binSize`	number	Yes	—	Time interval for binning data points into bars.
`data`	array	—	`[]`	Controlled data array with time and value fields.
`timeAccessor`	string \| function	—	`"time"`	Field name or function to access the time value.
`valueAccessor`	string \| function	—	`"value"`	Field name or function to access the numeric value.
`size`	[number, number]	—	`[500, 300]`	Chart dimensions as [width, height].
`windowMode`	"sliding" \| "growing"	—	`"sliding"`	Data retention strategy.
`categoryAccessor`	string \| function	—	—	Category accessor for stacked bars.
`fill`	string	—	—	Bar fill color in non-stacked mode.
`enableHover`	boolean \| object	—	—	Enable hover annotations on bars.

RealtimeSwarmChart

Full docs →

Streaming scatter/swarm dots for monitoring individual events.

import { RealtimeSwarmChart } from "semiotic"

Prop	Type	Required	Default	Description
`data`	array	—	`[]`	Controlled data array with time and value fields.
`timeAccessor`	string \| function	—	`"time"`	Field name or function to access the time value.
`valueAccessor`	string \| function	—	`"value"`	Field name or function to access the numeric value.
`size`	[number, number]	—	`[500, 300]`	Chart dimensions as [width, height].
`windowMode`	"sliding" \| "growing"	—	`"sliding"`	Data retention strategy.
`categoryAccessor`	string \| function	—	—	Category accessor for color-coding dots by group.
`radius`	number	—	—	Dot radius in pixels.
`fill`	string	—	—	Dot fill color when no categoryAccessor is set.
`enableHover`	boolean \| object	—	—	Enable hover annotations on dots.

RealtimeWaterfallChart

Full docs →

Cumulative delta bars that update with streaming data.

import { RealtimeWaterfallChart } from "semiotic"

Prop	Type	Required	Default	Description
`data`	array	—	`[]`	Controlled data array. Positive values = gains, negative = losses.
`timeAccessor`	string \| function	—	`"time"`	Field name or function to access the time value.
`valueAccessor`	string \| function	—	`"value"`	Field name or function to access the delta value.
`size`	[number, number]	—	`[500, 300]`	Chart dimensions as [width, height].
`windowMode`	"sliding" \| "growing"	—	`"sliding"`	Data retention strategy.
`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.
`enableHover`	boolean \| object	—	—	Enable hover annotations on bars.

RealtimeHeatmap

Full docs →

Streaming 2D heatmap with grid binning and configurable aggregation.

import { RealtimeHeatmap } from "semiotic"

Prop	Type	Required	Default	Description
`data`	array	—	`[]`	Controlled data array with x/y coordinates.
`timeAccessor`	string \| function	—	`"time"`	Field name or function to access the x-axis value.
`valueAccessor`	string \| function	—	`"value"`	Field name or function to access the y-axis value.
`size`	[number, number]	—	`[500, 300]`	Chart dimensions as [width, height].
`windowMode`	"sliding" \| "growing"	—	`"sliding"`	Data retention strategy.
`heatmapXBins`	number	—	`20`	Number of bins along the x-axis.
`heatmapYBins`	number	—	`20`	Number of bins along the y-axis.
`aggregation`	"count" \| "sum" \| "mean"	—	`"count"`	How values are aggregated per cell.
`decay`	DecayConfig	—	—	Opacity decay for older data cells.
`enableHover`	boolean \| object	—	—	Enable hover annotations on cells.