LineChart
Line and area charts for change over an ordered category, with optional forecast or range bands.
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/API | Type | Default | Description |
|---|---|---|---|
data | readonly T[] | required | One row per category, in plotting order. |
categoryKey | string or number field of T | required | Field identifying each category. Values must be unique. |
series | { key, label?, color?, band? }[] | required | key names a numeric field; band is { lowerKey, upperKey }. |
ariaLabel | string | required | Accessible chart name. |
size | "sm" | "md" | "lg" | "xl" | "huge" | inherited, otherwise "md" | Plot height and mark scale (LINE_CHART_LAYOUT). |
points | boolean | true | Dot at every observation. Focused points always show one. |
legend | boolean | { align?, placement? } | shown for 2+ series | Series legend; items toggle their series. |
tooltip | boolean | true | Hover and keyboard tooltip. |
grid | boolean | true | Value grid lines. |
valueDomain | [number, number] | fitted, includes zero | Fixed value-axis extent. A line may zoom in; an area should keep zero. |
valueTicks | number[] | rounded, spaced to the plot | Exact value-axis ticks. |
formatValue | (value: number) => string | grouped number | Value ticks and tooltip values. |
formatCategory | (value: string | number) => string | String | Category ticks and tooltip titles. |
emptyMessage | ReactNode | "No data to display" | Shown when no valid values exist. |
| Chart host props | see 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, LineChartDefinition | types | - | 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
valueDomainzooms a line away from zero, say so in the chart description.