Holochart

Area ​

Overview ​

An area chart fills the space under a line. Use it to show how a quantity changes over time when its size matters, how parts add up to a total (stacked areas), how shares of a total evolve (100% stacked areas), or the range between two bounds (bands). An area chart is a scatter trace with fill set, or several scatter traces that share a stackgroup.

fill can also close a line into a shape ('toself') or fill between two traces ('tonexty'), so the same attribute draws confidence bands, ranges, and arbitrary polygons.

Pick a different chart when:

  • you compare several series that don't add up to anything: use a line chart. Overlapping filled areas hide each other;
  • the x values are a few categories, not an ordered variable: use a stacked bar chart;
  • the exact values of the upper series in a stack matter: they are hard to read, because each band starts where the one below ends. Consider small multiples of lines instead.

Minimal example ​

ts
import { createChart } from '@mk7s/holochart';

const chart = createChart(document.getElementById('chart')!, {
  data: [
    {
      type: 'scatter',
      mode: 'lines',
      fill: 'tozeroy',
      x: ['2025-01-01', '2025-01-02', '2025-01-03', '2025-01-04'],
      y: [5.2, 7.9, 6.1, 8.4],
    },
  ],
});

fill: 'tozeroy' fills from the line down to y = 0. Without a fillcolor, the fill takes the line color at half opacity. The live example draws a year of daily values:

Loading example…
area/basic

Data format ​

  • x and y: the line's points, drawn in array order, exactly as for a line chart.
  • fill picks what is filled:
    • 'tozeroy' / 'tozerox': down to y = 0 (or across to x = 0).
    • 'tonexty' / 'tonextx': to the previous trace on the same subplot, joining the end points with straight lines. Without a previous trace, they act like 'tozeroy' / 'tozerox'.
    • 'toself': joins the last point to the first and fills the closed shape.
    • 'tonext': fills between this trace and the previous one when one encloses the other, such as a ring. Without a previous trace it acts like 'toself'.
  • "Previous trace" means the previous visible scatter trace on the same subplot that is in the same stackgroup (or, for unstacked traces, the previous unstacked one). Hiding a trace from the legend re-links the fill to the trace before it.
  • null or NaN values break the line. Fills to zero or to the next trace bridge the gap with a straight edge; 'toself' fills each line segment on its own.
  • stackgroup: 'name' stacks traces: see Stacked areas. Stacked values are matched by position (x, or y for orientation: 'h'); see Stack gaps for traces that lack some positions. Stacking needs a numeric (linear or log) value axis.

Variations ​

Stacked areas ​

Traces with the same stackgroup add up: each trace's y values are drawn on top of the traces before it in the group. Stacking turns on fill: 'tonexty' and makes mode default to 'lines', so stackgroup is often the only attribute you need. Each fill is drawn just above the previous trace's fill and below its line, so every boundary stays visible. Hovering a stacked point shows the trace's own value, not the running total.

Loading example…
area/stacked

100% stacked ​

groupnorm: 'percent' scales each position's total to 100 ('fraction' scales it to 1), so the chart shows shares instead of amounts. Set it on the first trace of the group; the first trace that sets it decides for the whole group. Add yaxis.ticksuffix: '%' for the tick labels.

Loading example…
area/percent

Range band ​

To shade the range between a lower and an upper bound, add the lower bound first with line.width: 0, then the upper bound with fill: 'tonexty' and a semi-transparent fillcolor such as 'rgba(239, 85, 59, 0.2)'. Put both in one legendgroup and hide one of their legend entries, so a single click toggles the band. This replaces the older error band workaround.

Loading example…
area/band

Streamgraph ​

A streamgraph is a stack centered on zero. Make the group's first trace an invisible baseline at minus half the total for each x: fill: 'none', line.width: 0, showlegend: false, and hoverinfo: 'skip'. The series stack on top of it. line.shape: 'spline' smooths the bands, and the fills follow the smoothed lines.

Loading example…
area/streamgraph

Gradient fills ​

fillgradient draws a colorscale instead of fillcolor. type: 'vertical' runs the colorscale along y and 'horizontal' along x, from start to stop (data values; by default the fill's own extent). 'radial' runs from the center of the fill's bounding box outwards. Use rgba stops to fade to transparent.

Loading example…
area/gradient

Pattern fills ​

fillpattern hatches the fill with lines or dots (shape, size, solidity, colors and fillmode), drawn in fillcolor by default. Tiles are sized in screen pixels, so the pattern keeps its spacing when you zoom. See Patterns & textures.

Loading example…
area/pattern

Closed shapes ​

fill: 'toself' closes the line into a shape. Edges may cross: fills use the nonzero rule, like SVG, so the center of a pentagram is filled. A null in the data starts a new shape within the same trace.

Loading example…
area/toself

Horizontal stacks ​

orientation: 'h' stacks x values instead of y values and implies fill: 'tonextx'. It suits profiles over a vertical variable such as altitude or depth. As with groupnorm, the first trace of the group that sets orientation decides.

Loading example…
area/stacked-horizontal

Stack gaps ​

When a stacked trace lacks some x positions that other traces of its group have, stackgaps: 'infer zero' (the default) counts it as 0 there, and 'interpolate' interpolates linearly between its neighbors (constant beyond its ends). Set it on the first trace of the group.

Loading example…
area/stackgaps

Styling ​

  • fillcolor: any CSS color. The default is the line color (else the marker color) at half opacity. Use an rgba color to control the transparency yourself.
  • fillgradient: { type, colorscale, start, stop }, drawn instead of fillcolor (which still colors hover labels).
  • fillpattern: { shape, fillmode, fgcolor, bgcolor, fgopacity, size, solidity }, a hatch pattern drawn instead of fillcolor and of a gradient.
  • line.color, line.width, line.dash, and line.shape, as on the line page. The fill follows the drawn line, including splines and steps. line.width: 0 draws the fill alone.
  • mode: 'lines+markers' adds markers on top of the fill.
  • In the legend, a filled trace shows a filled (or patterned) swatch with a border in the line color.
  • opacity fades the whole trace, fill included, and zorder changes the drawing order.

Interactivity ​

  • Hover. Stacked traces report their own value at the hovered point, not the stacked total; hovermode: 'x unified' lists every band at the hovered x, which reads well for stacks. With groupnorm, the value is the normalized one.
  • Hovering fills. hoveron: 'fills' makes the filled area itself hoverable; the label shows the trace name. It is the default for 'toself' and 'tonext' fills without markers or text, and 'points+fills' enables both. Fill hover works in hovermode: 'closest' only, and only when no point is under the pointer.
  • Legend. Click to hide a trace: the fills of later traces in the stack re-link to the trace below it. Group bounds with legendgroup so one click toggles a band.
  • Zoom, pan, and events work as for line charts.

3D-native options ​

Holochart extensions (full bundle), see Extrusion & 2.5D:

  • depth on a filled trace (fill: 'tozeroy', 'tonexty', 'toself', …): the fill becomes a slab that many px thick (or a percentage of the plot area's width). The line, markers, labels and error bars are drawn on its front face. 0 (default) draws the trace flat.
  • material: Plotly's lighting model (default), flat, or a three.js material type.
  • layout.view3d: the plot area in perspective; hover on the points stays exact on the front face.
Loading example…
area/depth

Every filled trace uses the same depth range, so stacked areas form one slab in layers, each lit on its front and its top wall:

Loading example…
area/depth-stacked

The slab is exactly the region the flat fill covers — holes, and self-intersecting toself shapes filled by the nonzero rule — with walls only on its outline:

Loading example…
area/depth-toself

The slab takes fillcolor; fillgradient and fillpattern are drawn flat, and bevel doesn't apply to fills.

Performance notes ​

  • Fills are triangulated once. Zoom and pan only change a transform for straight and step lines, so they stay as fast as the lines themselves. Spline fills are re-tessellated with their line when the zoom changes a lot.
  • Fills use the full-resolution path: line.simplify decimates the line but not the fill.
  • Fills whose edges cross, such as a 'tozeroy' fill that crosses y = 0 or a band whose bounds cross, use an exact nonzero fill on the CPU. It is slower than the default triangulation, so expect a larger first-draw cost for very large crossing fills. 'toself' always uses the nonzero rule.
  • extendTraces works on filled traces, but the fill is rebuilt in full on each append, and stacked traces fall back to a full recompute. For fast streams, keep the window short with maxPoints.

Accessibility notes ​

  • Screen readers: the chart is a <canvas>, and the DOM mirror that describes it to assistive technology is not built yet (planned for M2, see the accessibility guide). Add a caption or aria-label that states the trend or the composition, and a table of the key values.
  • Keyboard: Tab moves into the plot area; ← / → then step through the points and ↑ / ↓ move to the trace above or below, each stop showing its hover label. See the keys.
  • Color: adjacent bands in a stack need enough contrast between them. Label bands directly where you can, keep the number of stacked series small, and keep the lines between bands visible. Fill patterns (fillpattern) tell bands apart in grayscale printing.

Attribute reference ​

Area charts use the scatter trace. See the scatter attribute reference, especially fill, fillcolor, fillgradient, fillpattern, stackgroup, groupnorm, stackgaps, and hoveron.

  • Line: the same trace without a fill, for comparing series that don't add up
  • Bar: stacked bars for totals over a few categories
  • Scatter: the underlying trace type

Plotly migration notes ​

  • Plotly area charts are scatter traces with fill or stackgroup, so figures carry over: fill, fillcolor, fillgradient, stackgroup, orientation, groupnorm, stackgaps, and hoveron follow Plotly's semantics, with the differences below.
  • scattergl traces with fill become scatter.
  • fillpattern follows Plotly (see the pattern differences).
  • Not supported yet: scattermode: 'group'.
  • Drawing order: Plotly moves a trace down in the drawing order when it fills to a trace that is not directly before it. Holochart keeps zorder and trace order, and only places each 'tonext…' fill just above the fill of the trace it fills to.
  • Spline lines whose first and last points coincide are not smoothed as closed curves.
  • Fill hover (hoveron: 'fills') works in hovermode: 'closest' only.

Released under the MIT License.

Copyright © 2026 Holochart contributors