MAIDR JavaScript API
    Preparing search index...

    Interface RechartsAdapterConfig

    Configuration for the Recharts-to-MAIDR adapter.

    Supports three configuration modes:

    1. Simple mode — Set chartType and yKeys for a single chart type with one or more data series.
    2. Composed mode — Set layers for mixed chart types (e.g., bar + line).
    3. Subplot mode — Set subplots for multi-panel (faceted) figures made of a grid of Recharts charts.
    const config: RechartsAdapterConfig = {
      id: 'sales-chart',
      title: 'Sales by Quarter',
      data: [{ quarter: 'Q1', revenue: 100 }, { quarter: 'Q2', revenue: 200 }],
      chartType: 'bar',
      xKey: 'quarter',
      yKeys: ['revenue'],
      xLabel: 'Quarter',
      yLabel: 'Revenue ($)',
    };

    const config: RechartsAdapterConfig = {
      id: 'stacked-chart',
      title: 'Revenue by Product',
      data: [{ month: 'Jan', productA: 50, productB: 30 }],
      chartType: 'stacked_bar',
      xKey: 'month',
      yKeys: ['productA', 'productB'],
      fillKeys: ['Product A', 'Product B'],
      xLabel: 'Month',
      yLabel: 'Revenue',
    };

    const config: RechartsAdapterConfig = {
      id: 'hist-chart',
      title: 'Score Distribution',
      data: [{ bin: '0-10', count: 5, xMin: 0, xMax: 10 }],
      chartType: 'histogram',
      xKey: 'bin',
      yKeys: ['count'],
      binConfig: { xMinKey: 'xMin', xMaxKey: 'xMax' },
      xLabel: 'Score',
      yLabel: 'Frequency',
    };

    // Pass each band's OWN value, not the accumulated edge — MAIDR sums the
    // series to get the running total it announces.
    const config: RechartsAdapterConfig = {
      id: 'traffic-chart',
      title: 'Traffic by Source',
      data: [{ month: 'Jan', organic: 40, paid: 20 }],
      chartType: 'stacked_area',
      xKey: 'month',
      yKeys: ['organic', 'paid'],
      xLabel: 'Month',
      yLabel: 'Sessions',
    };

    // Each yKey holds the competitor's RANK in that period (1 is best), not
    // the underlying value. MAIDR inverts the pitch so rank 1 is the highest
    // note; handing it values instead would sonify the chart upside down.
    const config: RechartsAdapterConfig = {
      id: 'table-chart',
      title: 'League Position by Matchday',
      data: [{ matchday: 1, arsenal: 3, chelsea: 1 }],
      chartType: 'bump',
      xKey: 'matchday',
      yKeys: ['arsenal', 'chelsea'],
      xLabel: 'Matchday',
      yLabel: 'Position',
    };

    // The payload is a radar's — one value per spoke — because that is what a
    // reader navigates either way. The `<Pie>` drawing it takes its ANGLE from
    // a constant field so every wedge is the same width, and its RADIUS from
    // the measure, which is the field named here.
    const config: RechartsAdapterConfig = {
      id: 'nightingale-chart',
      title: 'Deaths by Month',
      data: [{ month: 'Jan', deaths: 120, slice: 1 }, { month: 'Feb', deaths: 84, slice: 1 }],
      chartType: 'polar_area',
      xKey: 'month',
      yKeys: ['deaths'],
      xLabel: 'Month',
      yLabel: 'Deaths',
    };

    // One `yKeys` entry per arm, and the per-arm keys line up with it the way
    // `fillKeys` does. Censoring marks a time where a subject left the study
    // without the event happening — the curve does not step there.
    const config: RechartsAdapterConfig = {
      id: 'km-chart',
      title: 'Overall Survival',
      data: [{ months: 0, treated: 1, treatedCensored: false }],
      chartType: 'survival',
      xKey: 'months',
      yKeys: ['treated'],
      survivalConfig: { censoredKeys: ['treatedCensored'] },
      xLabel: 'Months',
      yLabel: 'Survival probability',
    };

    // `errorKey` is the field the Recharts `<ErrorBar dataKey>` points at, so
    // it holds an OFFSET; the adapter turns it into the absolute bounds MAIDR
    // announces. Data that already holds bounds uses yMinKey/yMaxKey instead.
    const config: RechartsAdapterConfig = {
      id: 'yield-chart',
      title: 'Yield by Treatment',
      data: [{ treatment: 'Control', mean: 4.2, sd: 0.6 }],
      chartType: 'error_bar',
      xKey: 'treatment',
      yKeys: ['mean'],
      errorConfig: { errorKey: 'sd' },
      xLabel: 'Treatment',
      yLabel: 'Yield (t/ha)',
    };

    // `nullValue` is the <ReferenceLine> the chart draws: 1 for a ratio, 0 for
    // a difference. Without it MAIDR reports the estimate, the interval and the
    // weight, and makes no claim about significance.
    const config: RechartsAdapterConfig = {
      id: 'meta-chart',
      title: 'Effect of the intervention',
      data: [{ study: 'Silva 2018', or: 0.62, lo: 0.41, hi: 0.94, weight: 0.12 }],
      chartType: 'forest',
      xKey: 'study',
      yKeys: ['or'],
      orientation: Orientation.HORIZONTAL,
      errorConfig: { yMinKey: 'lo', yMaxKey: 'hi' },
      forestConfig: { weightKey: 'weight', pooledKey: 'pooled', nullValue: 1 },
      xLabel: 'Study',
      yLabel: 'Odds ratio',
    };

    // The labels are the payload on these charts — a reader told "x is 2.3,
    // y is 14.1" has been given the two numbers they can already see the shape
    // of, and withheld the gene they came for.
    const config: RechartsAdapterConfig = {
      id: 'volcano-chart',
      title: 'Differential Expression',
      data: [{ gene: 'TP53', log2fc: 2.4, negLog10P: 14.1 }],
      chartType: 'volcano',
      xKey: 'log2fc',
      yKeys: ['negLog10P'],
      volcanoConfig: { labelKey: 'gene', significance: 1.3, effect: 1 },
      xLabel: 'log2 fold change',
      yLabel: '-log10(p)',
    };

    // `data` is the `links` half of what <Sankey> is given; `flowConfig.nodes`
    // is the other half, and resolves the indices the links carry into names.
    // `'sankey'` takes exactly this config: the two differ in whether the node
    // set repeats at each stage, which is a fact about the data rather than
    // anything the adapter emits.
    const config: RechartsAdapterConfig = {
      id: 'flow-chart',
      title: 'Cohort Movement',
      data: [{ source: 0, target: 2, value: 34 }],
      chartType: 'alluvial',
      xKey: 'source',
      yKeys: ['value'],
      flowConfig: { targetKey: 'target', nodes: [{ name: 'Free' }, { name: 'Paid' }] },
      xLabel: 'Stage',
      yLabel: 'Users',
    };

    // Exactly two yKeys, the LEFT-hand side first and holding NEGATIVE values —
    // the sign is the side, and MAIDR pitches the magnitude so the biggest bar
    // on the left is not heard as the smallest note on the chart.
    const config: RechartsAdapterConfig = {
      id: 'pyramid-chart',
      title: 'Population by Age Band',
      data: [{ band: '0-9', men: -2_100_000, women: 2_000_000 }],
      chartType: 'diverging_bar',
      xKey: 'band',
      yKeys: ['men', 'women'],
      fillKeys: ['Men', 'Women'],
      orientation: Orientation.HORIZONTAL,
      xLabel: 'Age band',
      yLabel: 'People',
    };

    // The yKey holds each step's CONTRIBUTION; the adapter accumulates the
    // running totals, because a waterfall bar floats between the total before
    // the step and the total after it and neither number is in the data.
    const config: RechartsAdapterConfig = {
      id: 'bridge-chart',
      title: 'Revenue Bridge',
      data: [
        { step: 'Opening', change: 1200, restates: true },
        { step: 'New sales', change: 450 },
        { step: 'Churn', change: -180 },
        { step: 'Closing', restates: true },
      ],
      chartType: 'waterfall',
      xKey: 'step',
      yKeys: ['change'],
      waterfallConfig: { totalKey: 'restates' },
      xLabel: 'Step',
      yLabel: 'Revenue ($k)',
    };

    // Two yKeys, the starting end first, and `fillKeys` names them: those
    // names are what the comparison is about, and the legend is where a
    // sighted reader gets them.
    const config: RechartsAdapterConfig = {
      id: 'life-chart',
      title: 'Life Expectancy, 1990 against 2020',
      data: [{ country: 'Japan', then: 78.9, now: 84.6 }],
      chartType: 'dumbbell',
      xKey: 'country',
      yKeys: ['then', 'now'],
      fillKeys: ['1990', '2020'],
      xLabel: 'Country',
      yLabel: 'Years',
    };

    // One row per interval: `xKey` is its lane and the two `yKeys` its start
    // and end. Declare `lanes` so a lane with nothing booked still exists —
    // an empty row is a real statement about a schedule.
    const config: RechartsAdapterConfig = {
      id: 'plan-chart',
      title: 'Release Plan',
      data: [{ task: 'Design', from: 0, to: 5 }, { task: 'Build', from: 3, to: 12 }],
      chartType: 'gantt',
      xKey: 'task',
      yKeys: ['from', 'to'],
      ganttConfig: { lanes: ['Design', 'Build', 'Launch'], unit: 'days' },
      xLabel: 'Task',
      yLabel: 'Day',
    };

    // One data row, and everything the reading needs beyond its value comes
    // from the config: "73" is not the reading, "73 out of 100, 7 below
    // target, in the 'ok' band" is.
    const config: RechartsAdapterConfig = {
      id: 'nps-chart',
      title: 'Net Promoter Score',
      data: [{ measure: 'NPS', score: 73 }],
      chartType: 'gauge',
      xKey: 'measure',
      yKeys: ['score'],
      gaugeConfig: {
        min: 0,
        max: 100,
        target: 80,
        bands: [{ to: 40, label: 'poor' }, { to: 70, label: 'ok' }, { to: 100, label: 'good' }],
      },
    };

    Example: Treemap / sunburst / icicle

    // `data` is the nested array Recharts is given, not the adapter's usual
    // flat rows. `xKey` is the `<Treemap nameKey>` and the single `yKeys`
    // entry its `dataKey`; children live under `children`, as Recharts
    // requires. A `<SunburstChart data={{ name: 'World', children }}>` passes
    // that same `children` array here, since it draws every node but the root,
    // and an `'icicle'` takes the same nested array again.
    const config: RechartsAdapterConfig = {
      id: 'regions-chart',
      title: 'Population by Region',
      data: [
        { name: 'Europe', children: [{ name: 'France', people: 67.4 }] },
        { name: 'Asia', children: [{ name: 'Japan', people: 125.1 }] },
      ],
      chartType: 'treemap',
      xKey: 'name',
      yKeys: ['people'],
    };

    // `xKey` is the Recharts `<Pie nameKey>` (the slice label) and the single
    // `yKeys` entry is its `dataKey` (the slice magnitude).
    const config: RechartsAdapterConfig = {
      id: 'fruit-chart',
      title: 'Fruit Sales',
      data: [{ fruit: 'Apples', units: 30 }, { fruit: 'Bananas', units: 50 }],
      chartType: 'pie',
      xKey: 'fruit',
      yKeys: ['units'],
      xLabel: 'Fruit',
      yLabel: 'Units',
    };

    // `data` is the OBSERVATIONS with their raw values; the chart is drawn from
    // a normalised transpose of them, because a <Line> binds to one yAxisId.
    // MAIDR pitches each value against its own axis, so it must see the raw
    // numbers — handed the normalised ones, every axis would run 0 to 1.
    const config: RechartsAdapterConfig = {
      id: 'cars-chart',
      title: 'Cars by Specification',
      data: [{ car: 'Mazda RX4', mpg: 21, hp: 110, wt: 2.62 }],
      chartType: 'parallel',
      xKey: 'car',
      parallelConfig: {
        dimensions: ['mpg', 'hp', { label: 'Weight (1000 lb)', key: 'wt' }],
        labelKey: 'car',
      },
      xLabel: 'Variable',
      yLabel: 'Value',
    };

    // One row per KDE sample, tagged with its group. `densityKey` names the
    // density BEFORE the ridge offset: the offset is what keeps the curves from
    // overlapping on screen and says nothing about any group.
    const config: RechartsAdapterConfig = {
      id: 'temps-chart',
      title: 'Daily Temperature by Month',
      data: [{ month: 'Jan', temp: -4, density: 0.06, plotted: 11.06 }],
      chartType: 'ridgeline',
      xKey: 'temp',
      ridgelineConfig: { groupKey: 'month', valueKey: 'temp', densityKey: 'density' },
      xLabel: 'Temperature (C)',
      yLabel: 'Month',
    };

    // One row per occupied bin, its centre in DATA units. The lattice — rows
    // from the bottom up, each ordered left to right — is assembled here, since
    // a hex row staggers and a bin's index therefore is not its position.
    const config: RechartsAdapterConfig = {
      id: 'diamonds-chart',
      title: 'Carat against Price',
      data: [{ cx: 0.5, cy: 1200, count: 43 }],
      chartType: 'hexbin',
      xKey: 'cx',
      yKeys: ['cy'],
      hexbinConfig: { countKey: 'count' },
      xLabel: 'Carat',
      yLabel: 'Price ($)',
    };

    // One row per distribution, carrying the ladder computed from the sample.
    // `p` is the TAIL probability, so 0.25 is the rung spanning the middle half.
    const config: RechartsAdapterConfig = {
      id: 'latency-chart',
      title: 'Response Time by Region',
      data: [{
        region: 'East',
        median: 180,
        levels: [{ p: 0.25, lo: 150, hi: 240 }, { p: 0.125, lo: 130, hi: 310 }],
        high: [820, 910],
      }],
      chartType: 'boxen',
      xKey: 'region',
      boxenConfig: { upperOutliersKey: 'high' },
      xLabel: 'Region',
      yLabel: 'Milliseconds',
    };

    const config: RechartsAdapterConfig = {
      id: 'mixed-chart',
      title: 'Revenue and Trend',
      data: [{ month: 'Jan', revenue: 100, trend: 95 }],
      xKey: 'month',
      layers: [
        { yKey: 'revenue', chartType: 'bar', name: 'Revenue' },
        { yKey: 'trend', chartType: 'line', name: 'Trend' },
      ],
      xLabel: 'Month',
      yLabel: 'Value',
    };

    const config: RechartsAdapterConfig = {
      id: 'sales-by-region',
      title: 'Sales by Region',
      xKey: 'quarter',           // top-level fields are defaults for every panel
      yKeys: ['revenue'],
      xLabel: 'Quarter',
      yLabel: 'Revenue ($)',
      subplots: [[
        { title: 'East', chartType: 'bar', data: eastData },
        { title: 'West', chartType: 'bar', data: westData },
      ]],
    };
    interface RechartsAdapterConfig {
        id: string;
        title?: string;
        subtitle?: string;
        caption?: string;
        data?: Record<string, unknown>[];
        chartType?: RechartsChartType;
        categoryAxisReversed?: boolean;
        stepDirection?: StepDirection;
        categoryAxisReversedPerPanel?: boolean[];
        xKey: string;
        yKeys?: string[];
        layers?: RechartsLayerConfig[];
        subplots?: RechartsSubplotConfig[] | RechartsSubplotConfig[][];
        columns?: number;
        xLabel?: string;
        yLabel?: string;
        orientation?: Orientation;
        fillKeys?: string[];
        binConfig?: HistogramBinConfig;
        flowConfig?: FlowLinkConfig;
        volcanoConfig?: VolcanoPointConfig;
        errorConfig?: ErrorIntervalConfig;
        forestConfig?: ForestPlotConfig;
        survivalConfig?: SurvivalCurveConfig;
        waterfallConfig?: WaterfallStepConfig;
        ganttConfig?: GanttChartConfig;
        gaugeConfig?: GaugeDialConfig;
        parallelConfig?: ParallelAxesConfig;
        ridgelineConfig?: RidgelineCurveConfig;
        hexbinConfig?: HexbinLatticeConfig;
        boxenConfig?: BoxenLadderConfig;
        selectorOverride?: string;
    }

    Hierarchy (View Summary)

    Index

    Properties

    id title? subtitle? caption? data? chartType? categoryAxisReversed? stepDirection? categoryAxisReversedPerPanel? xKey yKeys? layers? subplots? columns? xLabel? yLabel? orientation? fillKeys? binConfig? flowConfig? volcanoConfig? errorConfig? forestConfig? survivalConfig? waterfallConfig? ganttConfig? gaugeConfig? parallelConfig? ridgelineConfig? hexbinConfig? boxenConfig? selectorOverride?

    Properties

    id: string

    Unique identifier for the chart (used for DOM IDs).

    title?: string

    Chart title displayed in text descriptions.

    subtitle?: string

    Chart subtitle.

    caption?: string

    Chart caption.

    data?: Record<string, unknown>[]

    Recharts data array. Each item is one data point with named fields. Required in simple/composed mode. In subplot mode it acts as the default data for panels that do not provide their own data, and may be omitted when every panel does.

    chartType?: RechartsChartType

    Chart type for simple mode (single chart type with one or more series). Mutually exclusive with layers.

    categoryAxisReversed?: boolean

    Whether the axis carrying the categories is drawn from its far end.

    Not a prop an author sets: MaidrRecharts derives it by reading reversed off the <XAxis> / <YAxis> inside its own children, which is where Recharts states it and where the converter cannot otherwise see it (#1017).

    stepDirection?: StepDirection

    Which way a step curve's riser goes: 'hv' holds the level and jumps at the next sample (<Line type="stepAfter">), 'vh' jumps at the current one (type="stepBefore").

    Read for 'step' and for the area types, whose trace carries a step the same way. MaidrRecharts fills it in from the <Line> / <Area> inside its own children when a step chart does not declare one, so an author usually need not.

    Left undefined rather than defaulted when nothing says. Every curve Recharts draws has a name — hv, vh, or mid for the centred type="step" — so a default here would be substituting one of them for a config that named none, and an undeclared direction is the one case StepTrace is written to expect.

    categoryAxisReversedPerPanel?: boolean[]

    The same answer per panel, in the grid's row-major order, in subplot mode.

    A panel has its own chart and so its own axes: one verdict for the whole grid would apply the first panel's answer to every other. Derived by MaidrRecharts from each panel's own child element.

    xKey: string

    Key in data objects for x-axis values.

    yKeys?: string[]

    Keys in data objects for y-axis values (simple mode). Each key creates a separate data series. Mutually exclusive with layers.

    layers?: RechartsLayerConfig[]

    Layer configurations for composed charts (composed mode). Each layer defines a chart type and data key. Mutually exclusive with chartType/yKeys.

    subplots?: RechartsSubplotConfig[] | RechartsSubplotConfig[][]

    Panel configurations for multi-panel (faceted) figures (subplot mode). Mutually exclusive with the top-level chartType and layers.

    A 2D array describes the panel grid directly in row-major visual reading order (subplots[0][0] is the top-left panel). A flat array is chunked into rows of columns panels (one single row when columns is omitted). Rows may be ragged but never empty.

    When rendering through <MaidrRecharts>, pass one Recharts chart per panel as children in the same row-major order — each child is wrapped in a generated .maidr-panel-<row>-<col> div used for per-panel highlight scoping. See RechartsSubplotConfig.panelSelector for the custom-DOM escape hatch.

    columns?: number

    Number of panels per row when subplots is a flat array. Ignored when subplots is already a 2D grid.

    xLabel?: string

    X-axis label.

    yLabel?: string

    Y-axis label.

    orientation?: Orientation

    Bar/box chart orientation. Defaults to vertical.

    fillKeys?: string[]

    Display names for each series in stacked/dodged/normalized/diverging bar charts. Maps 1:1 with yKeys — the i-th fillKey names the i-th yKey. When omitted, the yKey strings are used as fill labels.

    A dumbbell reads them as the names of its two ends. They are the content of that comparison: announced as "start" and "end", a chart of life expectancy in 1990 against 2020 tells the reader which dot they are on and not which year it is.

    binConfig?: HistogramBinConfig

    Histogram bin range configuration.

    Required when chartType is 'histogram', unless every bin's xKey label is itself a number — then each bin is read as a zero-width bin at its label. A label such as '0-10' places nothing, and a histogram carrying those without this config is refused rather than announced with a bin range nothing stated.

    flowConfig?: FlowLinkConfig

    Flow link configuration. Required when chartType is 'alluvial' or 'sankey'.

    volcanoConfig?: VolcanoPointConfig

    Point labels and cutoffs for a volcano or Manhattan plot. Used when chartType is 'volcano' or 'manhattan'.

    errorConfig?: ErrorIntervalConfig

    Interval configuration. Used when chartType is 'error_bar' or 'forest'.

    forestConfig?: ForestPlotConfig

    Forest plot configuration. Used when chartType is 'forest'.

    survivalConfig?: SurvivalCurveConfig

    Survival curve configuration. Used when chartType is 'survival'.

    waterfallConfig?: WaterfallStepConfig

    Waterfall step configuration. Used when chartType is 'waterfall'.

    ganttConfig?: GanttChartConfig

    Gantt lane configuration. Used when chartType is 'gantt'.

    gaugeConfig?: GaugeDialConfig

    Gauge range, target and bands. Required when chartType is 'gauge'.

    parallelConfig?: ParallelAxesConfig

    Axis order and raw value keys for a parallel coordinates plot. Required when chartType is 'parallel'.

    ridgelineConfig?: RidgelineCurveConfig

    Group, value and density keys for a ridgeline plot. Required when chartType is 'ridgeline'.

    hexbinConfig?: HexbinLatticeConfig

    Bin centre, count and lattice row keys for a hexbin plot. Used when chartType is 'hexbin'.

    boxenConfig?: BoxenLadderConfig

    Median, ladder and outlier keys for a boxen plot. Used when chartType is 'boxen'.

    selectorOverride?: string

    Custom CSS selector override for SVG highlighting.

    By default the adapter generates selectors from Recharts' built-in class names. For multi-series charts, CSS selectors cannot reliably distinguish between series, so highlighting is disabled.

    To enable highlighting for multi-series charts, add a custom className to each Recharts component and pass the selector here:

    <Bar className="revenue-bar" dataKey="revenue" />
    // then set selectorOverride: '.revenue-bar .recharts-bar-rectangle'

    Settings

    Member Visibility

    On This Page

    Properties