Chart
The chart host, card chrome, legend, tooltip, and theme shared by every Giddaa chart, with a native TanStack Charts escape hatch.
Quick Preview
Revenue by channel
Collections, January–June
Composition
Every chart component (BarChart, LineChart, PieChart, …) is a thin React
wrapper that builds a typed definition and renders it through Chart. Frame any
of them with the card chrome from this module.
ChartCard
├── ChartHeader
│ ├── ChartTitle
│ └── ChartDescription
├── ChartMetric
│ ├── ChartValue
│ └── ChartTrend
│ ├── ChartTrendChip
│ │ └── ChartTrendValue
│ └── ChartTrendCaption
├── <BarChart /> · <LineChart /> · … · <Chart definition={…} />
└── ChartFooterUsage
Data describes observations; series describe numeric fields, labels, and optional colors. Default colors follow Giddaa's palette. Axes, grids, tooltips, keyboard interaction, and a legend for multiple series are automatic.
import { BarChart } from "@giddaa-housing/ui/bar-chart";
import { ChartCard, ChartHeader, ChartTitle } from "@giddaa-housing/ui/chart";
const revenue = [
{ month: "Jan", online: 30, offline: 14 },
{ month: "Feb", online: 38, offline: 18 },
];
<ChartCard>
<ChartHeader><ChartTitle>Revenue by channel</ChartTitle></ChartHeader>
<BarChart
data={revenue}
categoryKey="month"
series={[
{ key: "online", label: "Online" },
{ key: "offline", label: "Offline", color: "var(--color-chart-2)" },
]}
ariaLabel="Monthly revenue by channel"
/>
</ChartCard>series.key must name a numeric field; categoryKey must name a string or
numeric field. Categories and series keys must be unique; aggregate duplicate
categories first. Null, undefined, and nonfinite values are omitted, not converted
to zero. Zero and negative values remain valid. Empty data shows a customizable
emptyMessage. Readability drops past three series; consider splitting larger
comparisons.
ChartCard provides size (sm, md, lg) to everything inside it, so the
title, metric, and plot scale together. Each chart can still set its own size.
Examples
Metric and trend
ChartMetric pairs a headline ChartValue with a ChartTrend. The trend chip
colors itself from direction (up is success, down is danger), and
ChartFooter pins a sparkline or note to the bottom of the card. Use
layout="inline" on the metric and orientation="vertical" on the trend for a
compact side-by-side figure.
Booked homes
1.28k
12.5%vs last month
Vacant units
42
3.1%vs last month
<ChartCard>
<ChartTitle>Booked homes</ChartTitle>
<ChartMetric>
<ChartValue>1.28k</ChartValue>
<ChartTrend direction="up">
<ChartTrendChip><ChartTrendValue>12.5%</ChartTrendValue></ChartTrendChip>
<ChartTrendCaption>vs last month</ChartTrendCaption>
</ChartTrend>
</ChartMetric>
<ChartFooter>
<Sparkline data={bookedHomes} ariaLabel="Booked homes, trending up" />
</ChartFooter>
</ChartCard>Legend alignment and placement
Series legends are buttons: click one to hide or show its series (the last visible
series stays). Hidden series keep their colors, and the value axis refits.
align: "start" lines the legend up with the value-axis labels, "center"
centers it over the chart, and "end" ends it at the plot's right edge. Use
placement: "bottom" to put it under the category axis. A single-series legend is
opt-in with legend or legend={{ … }}; legend={false} hides it.
Revenue vs. Target
Actual vs. target - Jan-Jun
<BarChart {...props} legend={{ align: "end", placement: "bottom" }} />For custom layouts, ChartSeriesLegend renders the same toggle buttons, and
useSeriesVisibility(keys) returns { hidden, toggle } to drive it. Pass
[...hidden] to a definition builder's hiddenSeries.
Tooltip rows and totals
Every chart uses the Giddaa tooltip panel. tooltipFooter adds content under the
rows. ChartTooltipRow is the same label/value row the panel draws for each
series: set label, value, and an optional marker color, add divider for a
rule above it and emphasis for a heavier value. Use it for totals, targets, or a
change from last period. For full control, pass renderTooltipBody and compose
ChartTooltipPanel or your own React content.
Revenue by Channel
Online vs. offline - Jan-Jun
import { ChartTooltipRow } from "@giddaa-housing/ui/chart";
<BarChart
layout="stacked"
tooltipFooter={(points) => (
<ChartTooltipRow
label="Total"
value={points.reduce((sum, point) => sum + point.datum.value, 0)}
divider
emphasis
/>
)}
{...props}
/>Custom colors
Every chart defaults to the four categorical Figma slots, chart-1…chart-4.
chart-5 (CHART_OTHER_COLOR) is the neutral for an "Other" remainder. Beyond
four, series and slices get lighter tints of the same slots, mixed toward the card
surface so they follow light and dark themes. The tints are not part of the Figma
palette; where you can, fold the long tail into "Other" or pick colors
deliberately. Override any series with series[].color, or any slice with a color
field named by colorKey. chartColor(index) returns the default for custom
compositions.
Collections
Series colors set per series
Listings by area
Tints extend the palette; “Other” sets its own color
import { CHART_OTHER_COLOR } from "@giddaa-housing/ui/chart";
<BarChart series={[{ key: "overdue", label: "Overdue", color: "var(--color-fg-danger)" }]} {...props} />
<PieChart data={[{ area: "Other", count: 6, color: CHART_OTHER_COLOR }]} colorKey="color" {...props} />Tuning axes, bins, and color scales
Every chart works with only its data props: ranges fit the data, ticks are rounded and spaced to the chart's height, and histograms pick about ten readable bins. The defaults are safe, not tailored. A few optional props make a chart noticeably easier to read; reach for them whenever you know something about the data the chart cannot.
| Prop | Default | Use it when |
|---|---|---|
valueDomain | fitted to the data, includes zero | The metric has natural bounds (0–100%, a 1–5 rating); several charts sit side by side and must share a scale; or the fitted top leaves awkward headroom. |
valueTicks | rounded, spaced to the plot height | The chart is short (sm, line xl) and three clean ticks read better than five; or values should land on meaningful lines such as a target or 25/50/75%. |
formatValue, formatCategory | plain numbers, String | Always, for money and units: ₦8.7M reads faster than 8700000. The same formatter runs on ticks, labels, and tooltips. |
Histogram.bins | about 10, rounded | A count is fine for a first look. Pass exact boundaries when intervals mean something (weeks, ₦10m price bands) or must stay identical across periods. |
Histogram.domain | data extent, rounded | Fix the range so this month and last month bin identically, or cut a long tail you report separately. |
HeatmapChart.domain | zero to the largest value | Tiers are fifths of the domain. Set it for fixed thresholds (a 0–100 score), and so colors mean the same thing every period. |
ComboChart.rightValueDomain, rightValueTicks | fitted | Percentages on the right axis: [0, 1] with [0, 0.5, 1]. |
Keep zero in the range for bars and areas, because their length encodes the value.
A line may zoom in with valueDomain when small changes matter; say so in the
description.
Rent collected
Defaults: fitted range, raw numbers
Rent collected
valueDomain, valueTicks, and formatValue
Server rendering and sizing
Charts render on the server and in the browser with the same markup. A server
cannot measure the card, so it lays each chart out at initialWidth (400px by
default, about the plot inside a max-w-md card) and the browser redraws it at
the container's real width after hydration. On a server-rendered page where the
chart usually sits in a wider layout, pass a closer initialWidth to keep that
first adjustment small. Height is always explicit: it comes from size, or
height when you set it, so the page never shifts vertically.
<BarChart {...props} initialWidth={680} />Containers in grid and flex layouts need min-width: 0 to let a chart shrink;
ChartCard already sets it. Keep definitions deterministic (resolved data,
explicit locales in formatters) so server and browser output agree.
Extend a standard chart
Each chart module exports the builder its component uses, named
create<Name>Definition (createBarChartDefinition, createLineChartDefinition,
…). It takes the same options as the component, minus the HTML legends, and
returns a plain TanStack definition. Spread it, add marks, and render it with
Chart.
Revenue against target
The dashed line marks the ₦50m target.
import { createBarChartDefinition } from "@giddaa-housing/ui/bar-chart";
import { Chart } from "@giddaa-housing/ui/chart";
import { defineChart, ruleY } from "@tanstack/charts";
const base = createBarChartDefinition({
data: revenue,
categoryKey: "month",
series: [{ key: "online", label: "Online" }],
});
const definition = defineChart({
...base,
marks: [...base.marks, ruleY([50], { y: (value) => value })],
});
<Chart definition={definition} ariaLabel="Revenue against target" />Treat definitions as immutable. Build them outside the component for static data,
or memoize them against the data and options they capture. Bar and line
interaction data contains category, series (the field key), label, value,
and row (the original observation). Read datum.value for a segment's value,
for consistent formatting across orientations and layouts.
Author a unique visualization
Occupancy trend
A native TanStack definition with Giddaa's chart host.
Import marks and scales directly from @tanstack/charts, then pass your
definition to Giddaa's Chart. Static and responsive definitions are supported.
Definitions can override theme fields; unspecified fields inherit Giddaa defaults
(CHART_THEME). Declare @tanstack/charts in the consuming application's
dependencies when importing it.
import { Chart } from "@giddaa-housing/ui/chart";
import { defineChart, lineY } from "@tanstack/charts";
import { scaleLinear } from "@tanstack/charts/scales/linear";
import { scalePoint } from "@tanstack/charts/scales/point";
import { tooltip } from "@tanstack/charts/tooltip";
const definition = defineChart({
marks: [lineY(rows, { x: "month", y: "occupancy", points: true })],
scales: { x: { scale: scalePoint }, y: { scale: scaleLinear().domain([0, 100]) } },
tooltip,
});
<Chart definition={definition} ariaLabel="Occupancy, January to April" />The host forwards TanStack callbacks (onSelect, onFocusChange,
onFocusGroupChange, onRender), width, accessibility description, and renderer
options. Charts render as static SVG; only the tooltip moves, gliding between
points (reduced-motion users get it instantly). Set motion on a definition to
animate marks yourself, or tooltip.motion: false to keep the tooltip immediate.
Pass a native TanStack renderer, such as Canvas, for very large datasets.
Props
Chart
The host every chart renders through. Every chart component accepts these props
too, except definition.
| Prop/API | Type | Default | Description |
|---|---|---|---|
definition | DomChartDefinition | required | A TanStack definition, from a create*Definition builder or defineChart. |
ariaLabel | string | required | Accessible chart name. |
ariaDescription | string | - | Longer accessible description. |
size | "sm" | "md" | "lg" | inherited, otherwise "md" | Sets the default height. |
height | number | from size | Plot height in pixels. |
width | number | container width | Fixed width; omit to fill the container. |
initialWidth | number | 400 | Width used for server markup until the browser measures the container. |
tooltipFooter | (points) => ReactNode | - | Content under the tooltip rows, e.g. ChartTooltipRow. |
renderTooltipBody | (context) => ReactNode | Giddaa panel | Full tooltip body; receives content, points, and defaultBody. |
renderer | ChartRenderer | SVG, tooltip-only motion | Native TanStack renderer. |
onSelect, onFocusChange, onFocusGroupChange, onRender | callbacks | - | Forwarded TanStack interaction callbacks. |
className, style | - | - | Applied to the chart element. |
Card chrome
| Prop/API | Type | Default | Description |
|---|---|---|---|
ChartCard size | "sm" | "md" | "lg" | inherited, otherwise "md" | Card padding and gap; provided to everything inside. |
ChartHeader | div props | - | Stacks title and description. |
ChartTitle / ChartDescription | h3 / p props + size | inherited | Card heading and supporting text. |
ChartMetric layout | "stacked" | "inline" | "stacked" | Value above the trend, or beside it. |
ChartValue | p props + size | inherited | Headline figure, tabular numerals. |
ChartTrend direction | "up" | "down" | "up" | Sentiment for the chip inside it. |
ChartTrend orientation | "horizontal" | "vertical" | "horizontal" | Chip and caption side by side or stacked. |
ChartTrendChip showIcon | boolean | true | Arrow icon before the value; direction and size inherit from ChartTrend. |
ChartTrendValue / ChartTrendCaption | span props | - | Change figure and its comparison caption. |
ChartFooter | div props | - | Bottom-aligned slot for a sparkline or note. |
Legend, tooltip, and theme
| Prop/API | Type | Default | Description |
|---|---|---|---|
legend (series charts) | boolean | ChartLegendOptions | shown for 2+ series | { align?: "start" | "center" | "end", placement?: "top" | "bottom" }. |
ChartSeriesLegend | items, align?, hidden?, onToggle? | - | HTML series legend; items are { key, label, color, marker? }. |
useSeriesVisibility(keys) | hook | - | Returns { hidden, toggle }; keeps at least one series visible. |
ChartTooltipRow | label, value?, color?, divider?, emphasis? | - | One tooltip row for footers and custom bodies. |
ChartTooltipPanel | content, footer?, className? | - | The Giddaa tooltip body, for renderTooltipBody. |
CHART_PALETTE, chartColor(index) | constants | - | Categorical slots chart-1…chart-4, then tints. |
CHART_OTHER_COLOR | string | var(--color-chart-5) | Neutral for an "Other" remainder. |
CHART_THEME, CHART_LEGEND | constants | - | Theme and legend geometry applied by the host. |
CHART_LAYOUT, LINE_CHART_LAYOUT, PIE_CHART_LAYOUT | size tables | - | Heights and mark sizes for custom compositions. |
emptyMessage (any chart) | ReactNode | "No data to display" | Shown instead of the plot when no valid values exist. |
Accessibility
- Provide a meaningful
ariaLabel, and anariaDescriptionwhen context helps. - Focus the chart and use arrow keys to inspect observations; tooltips show the same values for pointer and keyboard interaction.
- Multiple series receive a labeled legend; do not rely on color alone.
- Give
ChartCardanaria-label(or a visibleChartTitle) so the region is named. ChartTrendChippairs color with an arrow; keepChartTrendCaptionso the comparison is stated in text.- For detailed data access, compose the chart with an accessible table.