LineChart

Line and area charts for change over an ordered category, with optional forecast or range bands.

stable

Quick Preview

Occupancy

Units let · Jan–Jun

Usage

import { AreaChart, LineChart } from "@giddaa-housing/ui/line-chart";

<LineChart
  data={listings}
  categoryKey="month"
  series={[{ key: "closed", label: "Listings closed" }]}
  ariaLabel="Listings closed per month"
/>

<AreaChart
  data={revenue}
  categoryKey="month"
  series={[{ key: "revenue", label: "Revenue" }]}
  ariaLabel="Revenue trend"
/>

LineChart and AreaChart take the same data, categoryKey, and series as BarChart. Categories are plotted in input order, so sort them first. A missing value breaks the line rather than bridging it. AreaChart adds a 15% wash down to zero; area legends use square markers, line legends use line markers.

Line and area charts have their own size scale: sm, md, and lg (inherited from ChartCard) plus xl and huge for hero trend panels. They are shorter than bar charts at the same size.

Examples

Single line

Occupancy

Units let · Jan–Jun

Multiple lines

Each line is named by the legend, never by color alone.

Listings closed

By neighbourhood · Jan–Jun

Area

formatValue formats both the tooltip and the value axis.

Revenue trend

Monthly revenue · Jan–Jun

Multiple areas

Overlapping washes for related series.

Collections by channel

Online vs. offline · Jan–Jun

Forecast band

A series with band: { lowerKey, upperKey } shades the range between two numeric fields behind its line, for a forecast interval or a min–max range. Missing bounds break the band, so leave them null for actuals.

Inquiry forecast

Actuals to Jun · forecast with 80% range

<LineChart
  data={forecast}
  categoryKey="month"
  series={[{ key: "inquiries", label: "Inquiries", band: { lowerKey: "low", upperKey: "high" } }]}
  size="huge"
  ariaLabel="Monthly inquiries with a forecast range"
/>

Props

LineChart and AreaChart share every prop.

Prop/APITypeDefaultDescription
datareadonly T[]requiredOne row per category, in plotting order.
categoryKeystring or number field of TrequiredField identifying each category. Values must be unique.
series{ key, label?, color?, band? }[]requiredkey names a numeric field; band is { lowerKey, upperKey }.
ariaLabelstringrequiredAccessible chart name.
size"sm" | "md" | "lg" | "xl" | "huge"inherited, otherwise "md"Plot height and mark scale (LINE_CHART_LAYOUT).
pointsbooleantrueDot at every observation. Focused points always show one.
legendboolean | { align?, placement? }shown for 2+ seriesSeries legend; items toggle their series.
tooltipbooleantrueHover and keyboard tooltip.
gridbooleantrueValue grid lines.
valueDomain[number, number]fitted, includes zeroFixed value-axis extent. A line may zoom in; an area should keep zero.
valueTicksnumber[]rounded, spaced to the plotExact value-axis ticks.
formatValue(value: number) => stringgrouped numberValue ticks and tooltip values.
formatCategory(value: string | number) => stringStringCategory ticks and tooltip titles.
emptyMessageReactNode"No data to display"Shown when no valid values exist.
Chart host propssee Chart-height, initialWidth, ariaDescription, tooltipFooter, renderTooltipBody, callbacks, className, style.
createLineChartDefinition(options), createAreaChartDefinition(options)functions-Same options plus hiddenSeries; return extensible TanStack definitions.
LineChartSeries, LineChartOptions, AreaChartOptions, LineChartDatum, LineChartDefinitiontypes-Exported for typed series and builders.

Accessibility

  • Provide a meaningful ariaLabel; focus the chart and use arrow keys to move between observations.
  • Lines and areas need an ordered category; do not connect nominal categories.
  • Keep the legend whenever more than one series renders; do not rely on color alone.
  • If valueDomain zooms a line away from zero, say so in the chart description.

On this page