BarChart
Grouped, stacked, 100% stacked, and horizontal bar charts from typed data and series.
Quick Preview
Revenue Overview
Monthly revenue - Jan-Jul
Usage
import { BarChart } from "@giddaa-housing/ui/bar-chart";
import { ChartCard, ChartHeader, ChartTitle } from "@giddaa-housing/ui/chart";
<ChartCard>
<ChartHeader><ChartTitle>Revenue vs. target</ChartTitle></ChartHeader>
<BarChart
data={[
{ month: "Jan", actual: 38, target: 34 },
{ month: "Feb", actual: 48, target: 42 },
]}
categoryKey="month"
series={[
{ key: "actual", label: "Actual" },
{ key: "target", label: "Target" },
]}
formatValue={(value) => `₦${value}m`}
ariaLabel="Monthly revenue against target"
/>
</ChartCard>One row per category; each series names a numeric field. Axes, grid, tooltip,
keyboard navigation, and a legend for two or more series are automatic.
formatValue formats value ticks, labels, and tooltip values; formatCategory
formats category ticks and tooltip titles. Value axes always include zero, and
stacked negatives diverge below it. Host props such as initialWidth,
tooltipFooter, and renderTooltipBody are documented on Chart.
Examples
Default
A single-series legend is opt-in (legend). By default it starts in line with
the value-axis labels. valueDomain and valueTicks fix the axis.
Revenue Overview
Monthly revenue - Jan-Jul
Horizontal ranked list
Use orientation="horizontal" for ranked lists and long category labels.
Top Estates
Units sold this quarter
Stacked
layout="stacked" stacks related parts of a total. Only the exposed end of each
stack is rounded. Limit stacked or grouped charts to two or three series before
splitting into multiple charts.
Revenue by Channel
Online vs. offline - Jan-Jun
Grouped
Side-by-side bars (the default layout="grouped") work for direct comparisons
like actual vs. target.
Revenue vs. Target
Actual vs. target - Jan-Jun
100% stacked
layout="normalized" stacks each category to 100% for share-of-total
comparisons; tooltips show each value and its share.
Financing mix
Share of closed sales by quarter
Value labels
valueLabels prints each bar's value at its end. When stacked, it labels each
category total. Grouped charts with several series and normalized charts cannot
show value labels.
Revenue Overview
Values enabled
Tooltip totals
tooltipFooter adds rows under the series rows; ChartTooltipRow matches them.
Revenue by Channel
Online vs. offline - Jan-Jun
<BarChart
layout="stacked"
tooltipFooter={(points) => (
<ChartTooltipRow
label="Total"
value={points.reduce((sum, point) => sum + point.datum.value, 0)}
divider
emphasis
/>
)}
{...props}
/>Sizes
Bar charts inherit sm, md, or lg from ChartCard/SizeProvider, and the
plot height, tick type, gaps, and bar radius scale together.
SM
Inherited size scale
MD
Inherited size scale
LG
Inherited size scale
Extend the definition
createBarChartDefinition takes the same options and returns the TanStack
definition the component renders. Add marks and render it with Chart; see
Chart.
import { createBarChartDefinition } from "@giddaa-housing/ui/bar-chart";
import { Chart } from "@giddaa-housing/ui/chart";
const definition = createBarChartDefinition({ data, categoryKey: "month", series });
<Chart definition={definition} ariaLabel="Monthly revenue" />Props
| Prop/API | Type | Default | Description |
|---|---|---|---|
data | readonly T[] | required | One row per category. |
categoryKey | string or number field of T | required | Field identifying each category. Values must be unique. |
series | { key, label?, color? }[] | required | key names a numeric field; color overrides the palette slot. |
ariaLabel | string | required | Accessible chart name. |
layout | "grouped" | "stacked" | "normalized" | "grouped" | How several series share a category. |
orientation | "vertical" | "horizontal" | "vertical" | Bar direction. |
size | "sm" | "md" | "lg" | inherited, otherwise "md" | Plot height, type, gaps, and radius. |
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. |
valueTicks | number[] | rounded, spaced to the plot | Exact value-axis ticks. |
valueLabels | boolean | false | Value at each bar end, or each category total when stacked. |
formatValue | (value: number) => string | grouped number | Value ticks, labels, 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. |
createBarChartDefinition(options) | function | - | Same options plus hiddenSeries; returns an extensible TanStack definition. |
BarChartSeries, BarChartOptions, BarChartDatum, BarChartDefinition | types | - | Exported for typed series and builders. |
Accessibility
- Provide a meaningful
ariaLabel; focus the chart and use arrow keys to move between bars. - Value axes start at zero; a truncated baseline misrepresents magnitude.
- Keep the legend whenever more than one series renders; do not rely on color alone.
- Prefer horizontal bars when category labels are long or the chart is a ranked list.
- Avoid 3-D, skewed, or pill-shaped bars; the component uses flat rectangles with a small leading-edge radius.