Components · API · Chartlyx

ChartContainer

<ChartContainer<T>>

The Cartesian root component. Measures its DOM size via ResizeObserver, builds x/y scales, resolves accessor functions, and provides everything to descendants via context.

Prop	Type	Default	Description
`data *`	`readonly T[]`	-	Rows to plot. Generic over your row shape `T`.
`xScaleType *`	`"linear" \| "time" \| "band"`	-	Type of x-scale to build.
`yScaleType *`	`"linear" \| "time" \| "band"`	-	Type of y-scale to build.
`xKey`	`KeysOfType<T, ScaleInput<XS>>`	-	Field name on `T` for the x value. Mutually exclusive with `x`.
`x`	`(d: T) => ScaleInput<XS>`	-	Accessor function for the x value. Mutually exclusive with `xKey`.
`yKey`	`KeysOfType<T, ScaleInput<YS>>`	-	Field name on `T` for the y value. Mutually exclusive with `y`.
`y`	`(d: T) => ScaleInput<YS>`	-	Accessor function for the y value. Mutually exclusive with `yKey`.
`margin`	`Partial<Margin>`	`DEFAULT_MARGIN`	Overrides the built-in margins. Merged with defaults.
`minHeight`	`number`	`300`	Fallback height before `ResizeObserver` reports a real size.
`yDomain`	`[number, number]`	-	Explicit y-domain. Required for stacked charts; otherwise inferred from data.
`children`	`ReactNode`	-	Shapes, axes, grid, tooltip: anything that reads chart context.

Line

<Line<T>>

Renders a single <path> connecting the data points. Undefined or NaN values create gaps rather than breaking the path.

Prop	Type	Default	Description
`stroke`	`string`	`"currentColor"`	Line color.
`strokeWidth`	`number`	`2`	Line width in pixels.
`curve`	`CurveType`	`"linear"`	Interpolation: `linear`, `monotone`, or `step`.
`animate`	`boolean`	`false`	Enables the built-in mount animation.
`label`	`ShapeLabelRender<T>`	-	Optional per-point label render prop.
`y`	`(d: T) => number`	-	Override the container y-accessor for this shape (composed charts).
`yKey`	`KeysOfType<T, number>`	-	Field-name form of `y`. Mutually exclusive.

Area

<Area<T>>

Filled polygon between the line and the plot bottom. Pair with <LinearGradient> for fading fills.

Prop	Type	Default	Description
`fill`	`string`	`"currentColor"`	Fill color or gradient reference (`url(#id)`).
`fillOpacity`	`number`	`1`	Opacity of the fill (0–1).
`stroke`	`string`	`"none"`	Optional stroke around the area outline.
`strokeWidth`	`number`	`0`	Stroke width in pixels.
`curve`	`CurveType`	`"linear"`	Interpolation for the top edge.
`animate`	`boolean`	`false`	Enables the built-in mount animation.
`label`	`ShapeLabelRender<T>`	-	Optional per-point label render prop.
`y`	`(d: T) => number`	-	Override the container y-accessor.
`yKey`	`KeysOfType<T, number>`	-	Field-name form of `y`.

Bar

<Bar<T>>

One rectangle per data row. Uses xScale.bandwidth() for width, so requires a band x-scale. Falls back to a 20px fixed width otherwise.

Prop	Type	Default	Description
`fill`	`string`	`"currentColor"`	Bar fill.
`fillOpacity`	`number`	`1`	Fill opacity.
`stroke`	`string`	`"none"`	Bar stroke.
`strokeWidth`	`number`	`0`	Stroke width.
`radius`	`number`	`0`	Corner radius (SVG `rx`).
`baseline`	`number`	`0`	Y-value bars start from. Clamped to the plot area.
`animate`	`boolean`	`false`	Enables the built-in mount animation.
`label`	`ShapeLabelRender<T>`	-	Optional per-bar label render prop.
`y`	`(d: T) => number`	-	Override the container y-accessor.
`yKey`	`KeysOfType<T, number>`	-	Field-name form of `y`.

Scatter

<Scatter<T>>

One <circle> per data point, positioned at (xScale(x), yScale(y)).

Prop	Type	Default	Description
`fill`	`string`	`"currentColor"`	Dot fill.
`fillOpacity`	`number`	`1`	Fill opacity.
`stroke`	`string`	`"none"`	Dot stroke.
`strokeWidth`	`number`	`0`	Stroke width.
`radius`	`number`	`4`	Dot radius in pixels.
`animate`	`boolean`	`false`	Enables the built-in mount animation.
`label`	`ShapeLabelRender<T>`	-	Optional per-point label render prop.
`y`	`(d: T) => number`	-	Override the container y-accessor.
`yKey`	`KeysOfType<T, number>`	-	Field-name form of `y`.

StackedBar

<StackedBar<T>>

Wraps d3-shape.stack(). Only the top segment gets the corner radius so intra-bar gaps stay flush.

Prop	Type	Default	Description
`keys *`	`readonly KeysOfType<T, number>[]`	-	Numeric fields on `T` to stack, in draw order.
`colors`	`readonly string[]`	`DEFAULT_STACK_COLORS`	Palette. Cycles via `pickColor` if keys > colors.
`radius`	`number`	`0`	Corner radius applied only to the top segment.
`stroke`	`string`	`"none"`	Per-segment stroke.
`strokeWidth`	`number`	`0`	Stroke width.
`animate`	`boolean`	`false`	Enables the built-in mount animation.

StackedArea

<StackedArea<T>>

Same stacking mechanic as StackedBar but drawn as <path> segments with an optional curve.

Prop	Type	Default	Description
`keys *`	`readonly KeysOfType<T, number>[]`	-	Numeric fields on `T` to stack.
`colors`	`readonly string[]`	`DEFAULT_STACK_COLORS`	Palette.
`curve`	`CurveType`	`"linear"`	Interpolation between accumulated points.
`stroke`	`string`	`"none"`	Per-series stroke.
`strokeWidth`	`number`	`0`	Stroke width.
`fillOpacity`	`number`	`1`	Opacity applied to each series fill.
`animate`	`boolean`	`false`	Enables the built-in mount animation.

XAxis

<XAxis />

Horizontal axis rendered at the bottom of the plot area. Tick values come from xScale.ticks() for linear/time scales, or xScale.domain() for band scales.

Prop	Type	Default	Description
`tickCount`	`number`	-	Suggested tick count for linear/time scales. Ignored for band.
`tickFormatter`	`TickFormatter`	-	Function to format each tick’s display text.
`label`	`string`	-	Optional axis title.
`labelOffset`	`number`	-	Distance from axis to title in pixels.
`stroke`	`string`	-	Axis line and tick stroke color.
`textFill`	`string`	-	Tick text color, independent of `stroke`.
`labelFill`	`string`	-	Axis title text color.

YAxis

<YAxis />

Vertical axis on the left. Same props as XAxis; the axis title is rotated −90°.

Prop	Type	Default	Description
`tickCount`	`number`	-	Suggested tick count for linear/time scales.
`tickFormatter`	`TickFormatter`	-	Function to format each tick.
`label`	`string`	-	Optional axis title.
`labelOffset`	`number`	-	Distance from axis to title.
`stroke`	`string`	-	Axis line and tick color.
`textFill`	`string`	-	Tick text color.
`labelFill`	`string`	-	Axis title text color.

CartesianGrid

<CartesianGrid />

Background guide lines. Place before shapes so lines paint underneath.

Prop	Type	Default	Description
`horizontal`	`boolean`	`true`	Draw horizontal grid lines.
`vertical`	`boolean`	`true`	Draw vertical grid lines.
`xTickCount`	`number`	`5`	Suggested vertical-line count for linear/time x-scales.
`yTickCount`	`number`	`5`	Suggested horizontal-line count for linear/time y-scales.
`stroke`	`string`	-	Grid line color.
`strokeWidth`	`number`	-	Grid line width.
`strokeOpacity`	`number`	-	Grid line opacity.
`dashArray`	`string`	-	SVG `stroke-dasharray`. Use `"none"` for solid.

LinearGradient

<LinearGradient />

Convenience wrapper for SVG <defs> gradients. Reference the resulting gradient from any fill or stroke as url(#id).

Prop	Type	Default	Description
`id *`	`string`	-	DOM id used to reference the gradient.
`from *`	`string`	-	First stop color.
`to *`	`string`	-	Last stop color.
`fromOpacity`	`number`	`1`	Opacity of the first stop.
`toOpacity`	`number`	`0`	Opacity of the last stop.
`direction`	`"vertical" \| "horizontal"`	`"vertical"`	Gradient direction.

Tooltip

<Tooltip<T>>

Nearest-point hover tooltip. Place as the last child of <ChartContainer> so its invisible overlay ends up on top and catches pointer events cleanly.

Prop	Type	Default	Description
`children *`	`TooltipRender<T>`	-	Render function called with `{ x, y, datum, index }`.
`showIndicator`	`boolean`	`true`	Draw the guide line + dot at the active point.
`indicatorStroke`	`string`	-	Color of the guide line.
`indicatorOpacity`	`number`	-	Opacity of the guide line.
`dotRadius`	`number`	-	Indicator dot radius in pixels.
`dotFill`	`string`	-	Indicator dot color.

Legend

<Legend />

A standalone SVG legend with color chips. Place inside any chart, or wrap in its own <svg> next to the chart.

Prop	Type	Default	Description
`items *`	`readonly LegendItem[]`	-	Array of `{ label, color, shape? }`.
`direction`	`"row" \| "column"`	`"row"`	Layout direction.
`gap`	`number`	-	Space between items in pixels.
`fontSize`	`number`	-	Text size in pixels.
`color`	`string`	-	Label text color.
`chipSize`	`number`	-	Color chip size in pixels.

PolarChartContainer

<PolarChartContainer<T>>

Polar root component for pie, donut, and radar charts. Measures its own size, computes cx, cy, and outer radius, and manages active-slice state for tooltips.

Prop	Type	Default	Description
`data *`	`readonly T[]`	-	Rows to plot.
`valueKey`	`KeysOfType<T, number>`	-	Numeric field for pie/donut slice sizes. Omit for Radar.
`value`	`(d: T) => number`	-	Accessor form of `valueKey`.
`innerRadius`	`number`	`0`	`0` = pie, positive = donut.
`padding`	`number`	`20`	Gap between container edge and chart.
`minHeight`	`number`	-	Fallback height before ResizeObserver reports a real size.
`children`	`ReactNode`	-	Pie, Radar, RadarGrid, RadarAxes, PolarTooltip.

Pie

<Pie<T>>

Pie or donut chart. Slice sweep angles are computed by d3.pie() with .sort(null), preserving data order. Hovering a slice sets the container’s active index for <PolarTooltip>.

Prop	Type	Default	Description
`colors`	`readonly string[]`	`DEFAULT_STACK_COLORS`	Palette cycled per slice.
`stroke`	`string`	`"white"`	Border between slices.
`strokeWidth`	`number`	`2`	Slice border width.
`label`	`PieLabelRender<T>`	-	Per-slice label render prop. Receives `centroid`, angles, datum.

Radar

<Radar<T>>

Closed polygon connecting one row’s values across N numeric axes. Multiple <Radar> children with different rowIndex props overlay for comparisons.

Prop	Type	Default	Description
`axes *`	`readonly KeysOfType<T, number>[]`	-	Ordered list of numeric fields, one per axis.
`maxValue`	`number`	-	Upper bound for radial scaling. If omitted, computed from data.
`fill`	`string`	-	Polygon fill.
`fillOpacity`	`number`	-	Fill opacity.
`stroke`	`string`	-	Polygon stroke.
`strokeWidth`	`number`	-	Stroke width.
`showPoints`	`boolean`	-	Draw a dot at each axis intersection.
`pointRadius`	`number`	-	Radius of the intersection dots.
`rowIndex`	`number`	`0`	Which data row to plot.
`colorByIndex`	`number`	-	When set, picks fill/stroke from `DEFAULT_STACK_COLORS` by index.

RadarGrid

<RadarGrid />

Concentric background rings. Place first inside PolarChartContainer so it paints behind spokes and polygons.

Prop	Type	Default	Description
`axesCount *`	`number`	-	Number of axes on the chart (drives polygon shape).
`rings`	`number`	`5`	How many concentric rings to draw.
`stroke`	`string`	`"#e5e7eb"`	Ring stroke color.
`strokeWidth`	`number`	`1`	Ring stroke width.
`fill`	`string`	`"none"`	Fill applied to each ring.
`shape`	`"polygon" \| "circle"`	`"polygon"`	Ring shape.

RadarAxes

<RadarAxes />

Spokes from center to outer radius, plus labels beyond each endpoint. Text anchor flips based on angular position so labels never crowd the center.

Prop	Type	Default	Description
`axes *`	`readonly string[]`	-	Axis labels, one per spoke.
`stroke`	`string`	`"#9ca3af"`	Spoke color.
`strokeWidth`	`number`	`1`	Spoke width.
`labelFill`	`string`	`"#374151"`	Label text color.
`labelFontSize`	`number`	`11`	Label text size.
`labelOffset`	`number`	`12`	Distance from spoke tip to label in pixels.

PolarTooltip

<PolarTooltip<T>>

Hover tooltip driven by the polar container’s activeIndex state. Renders nothing when no slice or polygon is hovered.

Prop	Type	Default	Description
`children *`	`PolarTooltipRender<T>`	-	Render function called with `{ datum, index, cx, cy, radius, innerRadius }`.