GraphSX Reference
GraphSX has two entry points. Use a standalone <Plot> for one scientific plot. Use <Graph> as a figure canvas for diagrams, subplots, mixed plot-and-diagram figures, and port-to-port links.
style={{ ... }} or through reusable style libraries: define <Style id="wire" stroke="#111" />, then apply it with useStyle="wire". Plot-specific boxes can also use dedicated props such as frameStyle, boxStyle, textStyle, and labelStyle.Top-Level Documents
<Graph>
Auto-sized figure canvas for nodes, links, paths, reusable shapes, repeats, and nested plots.
<Plot>
Fixed-size plot figure with axes, ticks, data, lines, markers, legends, annotations, and optional animation.
Coordinates, Ports, And Addresses
at Places Things
In Graph, at uses figure screen units. It can be a literal point, a referenced port, or a referenced port plus vector arithmetic. Inside a Plot, annotation at uses data units by default; use atUnit="screen" for plot-pixel placement.
// Graph placement
<Rect id="A" at={[80, 120]} size={[100, 60]} />
<Rect id="B" at={A.right + [80, -20]} size={[100, 60]} />
<Rect id="C" at={B.top} anchor="bottom" size={[80, 40]} />
// Plot annotation placement
<Circle id="m" at={[2, 4]} r={5} />
<Text at={[2, 4]} label="peak" />
<Rect id="note" at={[430, 86]} atUnit="screen" size={[90, 28]} />from / to Connect Ports
Link connects ports by quoted address in both Graph and plot annotations. This keeps links semantic: "A.right" means a port address, while {A.right} means a coordinate expression and is used for placement. Plot annotation shapes can expose ports just like graph nodes.
// Graph links
<Link from="A.right" to="B.left" />
<Link from="P1.child.out" to="P2.in" headArrow />
// Plot annotation links
<Rect id="note" at={[3.2, 7.8]} size={[80, 28]}>
<Port id="tip" left />
</Rect>
<Circle id="peak" at={[3, 7]} r={5} />
<Link from="note.tip" to="peak.top" headArrow />Repeat Syntax
Linear Repeat
Repeat expands its children count times. The variable named by as is available inside braces and backtick strings. step offsets repeated graph children.
<Repeat count={4} as="i" step={[90, 0]}>
<Rect id={`box${i}`} at={[80, 120]} size={[60, 40]} label={`$A_${i}$`} />
</Repeat>Links Inside Repeat
Links can be generated too. Use backtick strings when a port address depends on the repeat index.
<Repeat count={3} as="i">
<Link from={`box${i}.right`} to={`box${i+1}.left`} />
</Repeat>Nested Repeat
Nested repeats are useful for grids. Give each level a different variable name.
<Repeat count={3} as="row" step={[0, 80]}>
<Repeat count={4} as="col" step={[90, 0]}>
<Rect id={`n${row}_${col}`} at={[60, 60]} size={[52, 36]} />
</Repeat>
</Repeat>Routing And Layout
Routing
route controls link geometry. Use straight for direct segments, orthogonal for right-angle turns, bypass for residual-style side detours, and auto for simple obstacle-aware orthogonal routing. Straight routes can use a signed offset for connected parallel detours. Per-link props override graph defaults.
<Graph route="orthogonal" corner={8}>
<Link from="A.right" to="B.left" />
<Link from="A.right" to="B.left" route="straight" offset={12} />
<Link from="A.top" to="B.left" route="bypass" side="left" offset={48} />
<Link from="B.bottom" to="C.top" route="auto" grid={20} padding={18} />
</Graph>Layout
Explicit at positions always win. When positions are omitted, layout="row" places nodes in source order, while layout="dag" uses links to rank connected nodes.
<Graph layout="dag" direction="right" rankGap={180} nodeGap={80}>
<Rect id="A" size={[90, 50]} />
<Rect id="B" size={[90, 50]} />
<Rect id="C" size={[90, 50]} />
<Link from="A.right" to="B.left" />
<Link from="A.right" to="C.left" />
</Graph>Ports And Angles
Side ports provide default routing directions. Custom ports can set angle, which gives orthogonal and auto routes a preferred direction as they leave or enter the shape.
<Port id="tap" at={[60, 20]} angle={35} />
<Link from="A.tap" to="B.left" route="orthogonal" />Data Tag
Literal Data
Use points for explicit pairs, or separate x and y arrays when that is clearer.
<Data id="raw" points={[[0, 1], [1, 2], [2, 4]]} />
<Data id="xy" x={[0, 1, 2]} y={[1, 2, 4]} />
<Line data="raw" fmt=".-" />Function Data
A string y expression generates sampled data over domain. The default variable is x, and the sampled domain value is stored as the point's x field. Constants and math helpers include pi, sin, cos, exp, sqrt, and pow.
<Data id="sin" y="sin(x)" domain={[0, 2*pi]} samples={160} />
<Line data="sin" label="$\sin(x)$" />Parametric Data
When both x and y are expressions, GraphSX samples a parameter and stores the evaluated expressions as fields named x and y. The default variable is t; override it with variable.
<Data
id="heart"
x="16 * pow(sin(t), 3)"
y="13*cos(t) - 5*cos(2*t) - 2*cos(3*t) - cos(4*t)"
domain={[0, 2*pi]}
samples={420}
/>Parameters
params declares extra symbols used in generated data. This makes expressions explicit and gives animation a known starting value. Parameter values can also be complex strings such as "1j".
<Data
id="fit"
y="a * exp(-b*x)"
params={{ a: 2.6, b: 0.28 }}
domain={[0, 10]}
/>Complex Values And Maps
Generated data may store complex x or y values. Plot coordinates use the real part by default. Use xMap and yMap on a series to project stored point fields into plotted coordinates.
<Data id="phase" y="exp(1j*t)" variable="t" domain={[0, 2*pi]} />
<Line data="phase" xMap="real(y)" yMap="imag(y)" />
<Data id="root" y="sqrt(x)" domain={[-1, 1]} />
<Line data="root" yMap="imag(y)" />Animation
Animated Series
Animation belongs to the rendered series. The series references a Data object, then animates one or more declared data parameters.
<Data id="wave" y="sin(x - phase)" params={{ phase: 0 }} domain={[0, 2*pi]} />
<Line
data="wave"
animate={{ phase: [0, 2*pi], duration: 2.6 }}
/>How It Updates
The plot is rendered once with animation metadata. During playback, GraphSX regenerates the affected series data for the current frame and updates that SVG series, leaving unrelated page DOM alone.
Multiple Parameters
Each animated series owns its own parameter values. Different lines can animate the same parameter name independently because the values are scoped to their data source and series.
<Line data="waveA" animate={{ phase: [0, 2*pi] }} />
<Line data="waveB" animate={{ phase: [pi, 3*pi] }} />Supported Tags And Children
| Tag | Where | Allowed Children | Key Props | Purpose |
|---|---|---|---|---|
Graph | Top level | Style, Shape, Rect, Circle, Point, Anchor, Plot, Link, Path, Repeat | route, layout, direction, x, y, gap, rankGap, nodeGap, grid, padding, corner | General diagram and figure canvas. |
Rect | Graph, Shape, plot annotations | Port | id, at, x, y, size, w, h, label, corner, anchor, origin, rotate, flipX, flipY, style, useStyle | Rectangle node with default side ports. |
Circle | Graph, Shape, plot annotations | Port | id, at, x, y, r, label, anchor, origin, rotate, flipX, flipY, style, useStyle | Circle node with default side ports. |
Point, Anchor | Graph, Shape | Port | id, at, x, y, label, r, style, useStyle | Shapeless anchor with default center port. |
Plot | Top level, Graph | Port in graph use; plot children such as Data, Axis, Line, Legend, annotation tags | id, at, width, height, padding, xDomain, yDomain, frame, frameStyle, box, style | Standalone plot or placed subplot panel. |
Port, Leg | Nodes, shapes, nested graph plots | None | id, left, right, top, bottom, side, at, x, y, angle, target, label, r, style, useStyle | Defines a connection point. |
Link | Graph, Shape, plot annotations | None | from, to, route, side, offset, grid, padding, corner, headArrow, tailArrow, arrowSize, style, useStyle | Connects quoted port addresses such as "A.right". |
Path | Graph, Shape, plot annotations | None | id, points, d, at, corner, closed, headArrow, tailArrow, arrowSize, rotate, flipX, flipY, style, useStyle | Explicit geometry from points or SVG d. |
Shape | Graph, libraries | Graph node tags, Port, Link, Path, Repeat | id, from, groupBox, plus user-defined props forwarded to children | Reusable composite shape definition. |
Repeat | Graph, Shape | Any repeatable graph or shape child | count, as, step | Expands repeated nodes, links, and paths with an index variable. |
Style | Graph, Plot, libraries | None | id, plus SVG style props such as fill, stroke, strokeWidth, opacity, strokeDasharray | Reusable style referenced by useStyle. |
Data | Plot | None | id, points, x, y, domain, samples, params, variable | Named data from points, x/y arrays, generated functions, or parametric expressions. |
Axis | Plot | Ticks | x, y, label, ticks, grid, labelGap, tickLabelGap, tickSize, style, labelStyle | X or Y axis with labels, ticks, and grid. |
Ticks | Axis | None | values, labels, grid, labelGap, tickLabelGap, tickSize, style, labelStyle | Explicit tick values and optional labels. |
Line, Curve | Plot | None | data, points, x, y, xMap, yMap, fmt, label, animate, stroke, strokeWidth, fill, r, style, useStyle | Draws data as connected series. |
Mark, Point, Scatter | Plot | None | data, at, points, x, y, xMap, yMap, r, label, animate, fill, stroke, style, useStyle | Draws data as markers. |
Text, Label | Plot | None | at, label, fontSize, anchor, baseline, rotate, style, useStyle | Text or KaTeX label at data coordinates. |
Legend | Plot | None | position, box, padding, margin, fontSize, textStyle, boxStyle | Legend generated from labeled series. |
rect/Rec/rec for Rect, circle/Circ/circ for Circle, point, anchor, path, Dataset, XAxis, YAxis, ticks, Series, and legend. New examples should prefer the canonical form.Data, y="..." samples the variable x by default and stores that sampled value as the point's x. Parametric data uses both x="..." and y="...", samples t by default, and stores the evaluated expressions as fields named x and y. Complex expressions use numeric imaginary literals such as 1j; bare j is a normal parameter name.Common Patterns
Placed Subplot
<Graph>
<Plot id="p" at={[0, 0]} width={360} height={240} frame box>
<Port id="out" right />
<Axis x ticks />
<Axis y ticks />
<Line points={[[0, 0], [1, 1]]} />
</Plot>
</Graph>Generated Function Data
<Plot width={560} height={340} xDomain={[0, 2*pi]} yDomain={[-1, 1]} box>
<Data id="sin" y="sin(x)" domain={[0, 2*pi]} samples={160} />
<Line data="sin" label="$\sin(x)$" />
</Plot>Reusable Shape
<Shape id="Tensor" groupBox={false}>
<Rect id="box" size={[56, 56]} label={label} />
<Port id="left" target="box.left" />
</Shape>
<Tensor id="A0" label="$A$" />