Chart

The chart host, card chrome, legend, tooltip, and theme shared by every Giddaa chart, with a native TanStack Charts escape hatch.

stable

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={…} />
└── ChartFooter

Usage

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.

PropDefaultUse it when
valueDomainfitted to the data, includes zeroThe 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.
valueTicksrounded, spaced to the plot heightThe 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, formatCategoryplain numbers, StringAlways, for money and units: ₦8.7M reads faster than 8700000. The same formatter runs on ticks, labels, and tooltips.
Histogram.binsabout 10, roundedA 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.domaindata extent, roundedFix the range so this month and last month bin identically, or cut a long tail you report separately.
HeatmapChart.domainzero to the largest valueTiers 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, rightValueTicksfittedPercentages 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/APITypeDefaultDescription
definitionDomChartDefinitionrequiredA TanStack definition, from a create*Definition builder or defineChart.
ariaLabelstringrequiredAccessible chart name.
ariaDescriptionstring-Longer accessible description.
size"sm" | "md" | "lg"inherited, otherwise "md"Sets the default height.
heightnumberfrom sizePlot height in pixels.
widthnumbercontainer widthFixed width; omit to fill the container.
initialWidthnumber400Width used for server markup until the browser measures the container.
tooltipFooter(points) => ReactNode-Content under the tooltip rows, e.g. ChartTooltipRow.
renderTooltipBody(context) => ReactNodeGiddaa panelFull tooltip body; receives content, points, and defaultBody.
rendererChartRendererSVG, tooltip-only motionNative TanStack renderer.
onSelect, onFocusChange, onFocusGroupChange, onRendercallbacks-Forwarded TanStack interaction callbacks.
className, style--Applied to the chart element.

Card chrome

Prop/APITypeDefaultDescription
ChartCard size"sm" | "md" | "lg"inherited, otherwise "md"Card padding and gap; provided to everything inside.
ChartHeaderdiv props-Stacks title and description.
ChartTitle / ChartDescriptionh3 / p props + sizeinheritedCard heading and supporting text.
ChartMetric layout"stacked" | "inline""stacked"Value above the trend, or beside it.
ChartValuep props + sizeinheritedHeadline 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 showIconbooleantrueArrow icon before the value; direction and size inherit from ChartTrend.
ChartTrendValue / ChartTrendCaptionspan props-Change figure and its comparison caption.
ChartFooterdiv props-Bottom-aligned slot for a sparkline or note.

Legend, tooltip, and theme

Prop/APITypeDefaultDescription
legend (series charts)boolean | ChartLegendOptionsshown for 2+ series{ align?: "start" | "center" | "end", placement?: "top" | "bottom" }.
ChartSeriesLegenditems, align?, hidden?, onToggle?-HTML series legend; items are { key, label, color, marker? }.
useSeriesVisibility(keys)hook-Returns { hidden, toggle }; keeps at least one series visible.
ChartTooltipRowlabel, value?, color?, divider?, emphasis?-One tooltip row for footers and custom bodies.
ChartTooltipPanelcontent, footer?, className?-The Giddaa tooltip body, for renderTooltipBody.
CHART_PALETTE, chartColor(index)constants-Categorical slots chart-1…chart-4, then tints.
CHART_OTHER_COLORstringvar(--color-chart-5)Neutral for an "Other" remainder.
CHART_THEME, CHART_LEGENDconstants-Theme and legend geometry applied by the host.
CHART_LAYOUT, LINE_CHART_LAYOUT, PIE_CHART_LAYOUTsize 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 an ariaDescription when 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 ChartCard an aria-label (or a visible ChartTitle) so the region is named.
  • ChartTrendChip pairs color with an arrow; keep ChartTrendCaption so the comparison is stated in text.
  • For detailed data access, compose the chart with an accessible table.

On this page