Ridgeline Marks

ridgelineY draws horizontal profiles above categorical y baselines. ridgelineX transposes the contract and extends vertical profiles to the right of categorical x baselines.

import { ridgelineY } from '@tanstack/charts/ridgeline'

const mark = ridgelineY(profileRows, {
  x: 'x',
  y: 'category',
  height: 'height',
  overlap: 0.8,
  color: 'category',
})

Both marks are also exported from @tanstack/charts and @tanstack/charts/universal.

Prepared profiles

The mark lays out prepared profile samples. It does not bin observations, estimate a density, or normalize values. Keep those decisions visible with transforms or application data preparation.

const bins = binX(rows, {
  value: 'rating',
  by: 'season',
  thresholds: boundaries,
  outputs: { count: { reduce: 'count' } },
})
const profiles = normalize(bins, {
  value: 'count',
  by: 'season',
  basis: 'max',
  as: 'height',
})

defineChart({
  marks: [
    ridgelineY(profiles, {
      x: 'x',
      y: 'season',
      height: 'height',
      overlap: 0.78,
      color: 'season',
    }),
  ],
  scales: {
    x: { scale: scaleLinear().domain([4, 10]) },
    y: {
      scale: scalePoint<number>().domain(seasons).padding(0.78),
      reverse: true,
    },
  },
})

height must be finite and within [0, 1]. Nullish and nonfinite profile positions or heights create gaps. Sort samples into the intended profile order before passing them to the mark.

Signatures

function ridgelineY<TDatum>(
  source: Iterable<TDatum>,
  options: RidgelineYOptions<TDatum>,
): ChartMark<TDatum>

function ridgelineX<TDatum>(
  source: Iterable<TDatum>,
  options: RidgelineXOptions<TDatum>,
): ChartMark<TDatum>

The profile position is numeric or temporal. The category is a numeric or string ChartKey.

The public type surface includes RidgelinePosition, RidgelineCurve, RidgelineStateStyle, RidgelineYOptions, and RidgelineXOptions.

Options

overlap must be positive and finite. A value of 1 reaches the next category baseline, values below 1 leave space, and values above 1 overlap adjacent profiles.

Category scale and padding

The categorical axis must resolve to a point or band scale. Ridge displacement uses the smallest step in the complete configured domain, including categories without profile rows. This keeps geometry stable when a category is empty.

Point-scale padding controls room outside the first and last baseline. Set its padding to at least overlap when peaks must remain inside the plot. Use reverse: true on a y scale when the first authored category should appear at the bottom.

Categories paint in first-occurrence order; each category's area paints before all outlines. Source order therefore controls which profile is on top when overlap exceeds 1.

Identity and interaction

Each valid sample contributes one semantic interaction point even though the mark paints both an area and an outline. The point retains the exact source datum and index. ridgelineY reports the profile position as xValue and the category as yValue; ridgelineX transposes them.

Profile areas and outlines share the same points, focus affinity, state opacity, and keyed motion. Use an explicit key when positions repeat within a category.