BarChart

Grouped, stacked, 100% stacked, and horizontal bar charts from typed data and series.

stable

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/APITypeDefaultDescription
datareadonly T[]requiredOne row per category.
categoryKeystring or number field of TrequiredField identifying each category. Values must be unique.
series{ key, label?, color? }[]requiredkey names a numeric field; color overrides the palette slot.
ariaLabelstringrequiredAccessible 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.
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.
valueTicksnumber[]rounded, spaced to the plotExact value-axis ticks.
valueLabelsbooleanfalseValue at each bar end, or each category total when stacked.
formatValue(value: number) => stringgrouped numberValue ticks, labels, 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.
createBarChartDefinition(options)function-Same options plus hiddenSeries; returns an extensible TanStack definition.
BarChartSeries, BarChartOptions, BarChartDatum, BarChartDefinitiontypes-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.

On this page