Core concepts

ChartContainer

The Cartesian entry point. It does four things:

1. Measures its own DOM size via ResizeObserver.
2. Builds x and y scales from your data and props.
3. Resolves xKey / yKey shortcuts into accessor functions.
4. Provides everything above to descendants through React context.

You can specify axes by field name (xKey) or by function (x). Field-name form is fully typed against your row shape.

// Two equivalent ways to specify axes:
<ChartContainer xKey="date" xScaleType="time" ... />
<ChartContainer x={(d) => d.date} xScaleType="time" ... />

Scales

A scale is a function that maps data values to pixel positions. Chartlyx wraps three D3 scale types, chosen by the xScaleType / yScaleType props:

The domain is inferred from your data automatically; pass an explicit yDomain to override (required for stacked charts).

The context

Every Cartesian shape reads its data through React context, not props. This means adding a <Line> or <Bar> never involves re-passing data, xScale, etc. For custom components, use the useChartContext hook:

import { useChartContext } from "chartlyx";

function CustomMarker() {
  const { data, xAccessor, yAccessor, xScale, yScale } = useChartContext();
  return data.map((d, i) => (
    <circle
      key={i}
      cx={xScale(xAccessor(d))}
      cy={yScale(yAccessor(d))}
      r={6}
      fill="tomato"
    />
  ));
}

Margins & sizing

Chartlyx bakes margins directly into the scale ranges, so the plot area automatically excludes room for axes and labels. Override with the margin prop:

<ChartContainer
  margin={{ top: 20, right: 24, bottom: 34, left: 52 }}
  ...
>

The default is { top: 10, right: 10, bottom: 30, left: 40 } (exported as DEFAULT_MARGIN). Bump left if you have long y-axis labels, or bottom for angled x-axis text.

Render-prop pattern

Every customizable output in Chartlyx (tooltip contents, per-point labels, pie centroid text) is a render prop. You pass a function, Chartlyx calls it with typed positional data, and you return JSX.

<Line<Row>
  label={({ x, y, datum, index }) =>
    index === data.length - 1
      ? <text x={x} y={y - 8} fill="#5eead4">${datum.revenue}</text>
      : null
  }
/>

Return null to skip. There is no mini-language to learn: it is just React.