vizonomy-d3

Typed, headless D3-based chart components for React. Currently includes a stacked BarChart and a useBarChart hook.

Installation

npm install vizonomy-d3
# or
yarn add vizonomy-d3

BarChart

Stacked bar chart supporting vertical/horizontal orientation, legend, grid, tooltips, totals, custom formatters, and event callbacks.

Usage

import { BarChart, type StackedBarChartDataPoint, type BarChartSeries } from 'vizonomy-d3';

const data: StackedBarChartDataPoint[] = [
  { id: 'jan', label: 'Jan', values: { sales: 100, marketing: 50 } },
  { id: 'feb', label: 'Feb', values: { sales: 150, marketing: 75 } },
];

const series: BarChartSeries[] = [
  { key: 'sales', label: 'Sales', color: '#3b82f6' },
  { key: 'marketing', label: 'Marketing', color: '#ef4444' },
];

export default function Example() {
  return (
    <BarChart
      data={data}
      series={series}
      title="Monthly Performance"
      xAxisLabel="Month"
      yAxisLabel="Amount ($K)"
      width={600}
      height={400}
      showLegend
      showGrid
      showTooltip
    />
  );
}

Props

See TypeScript definitions for full details (BarChartProps). Key props:

• orientation: 'vertical' | 'horizontal'
• showLegend/showGrid/showTooltip/showTotals: booleans
• styleProps: typography and colors for title, axes, grid, totals
• formatCategoryLabel/formatValueLabel/formatTotalLabel: formatting overrides
• onBarClick/onBarHover: interaction callbacks

Formatting

You can localize and format labels and values:

<BarChart
  {...baseProps}
  formatCategoryLabel={(label) => label.toUpperCase()}
  formatValueLabel={(v) => Intl.NumberFormat('en', { notation: 'compact' }).format(v)}
  formatTotalLabel={(t) => `${t} total`}
/>

Hook

useBarChart exposes measurements, scales, stacked data, and tooltip state for fully custom SVG rendering.

Props

BarChartProps

| Prop | Type | Default | Description | | --- | --- | --- | --- | | data | StackedBarChartDataPoint[] | — | Data points. Each has an id, label, and values map of series key to number. | | series | BarChartSeries[] | — | Series config: key, label, color per stacked segment. | | width | number | 800 | SVG width. | | height | number | 400 | SVG height. | | margin | { top: number; right: number; bottom: number; left: number } | { top: 20, right: 20, bottom: 60, left: 40 } | Outer margins; affects inner plotting area. | | title | string | — | Optional chart title rendered above the SVG. | | xAxisLabel | string | — | Axis label (bottom for vertical, bottom numbers for horizontal). | | xAxisLabelOffset | number | 0 | Extra pixel offset for the X axis label position. Positive moves it farther from the axis. | | yAxisLabel | string | — | Axis label (left for vertical, left categories for horizontal). | | yAxisLabelOffset | number | 0 | Extra pixel offset for the Y axis label position. Positive moves it farther from the axis. | | orientation | 'vertical' | 'horizontal' | 'vertical' | Switches category/value axes. | | showLegend | boolean | true | Show legend below the chart. | | legendItemGap | number | 0 | Extra horizontal spacing in pixels between legend items. | | legendItemWidth | number | auto | Minimum width per legend item; if 0 or omitted, width is auto-calculated from label. | | showGrid | boolean | true | Draw grid lines along the numeric axis. | | showTooltip | boolean | true | Enable hover tooltip. | | showTotals | boolean | false | Render total labels at the end of each bar. | | barPadding | number | 0.1 | Band scale padding between categories. | | styleProps | BarChartStyleProps | see below | Typography/colors for title, axes, grid, totals, background. | | formatCategoryLabel | (label: string) => string | identity | Formatter for category labels (ticks, legend). | | formatValueLabel | (value: number) => string | locale d3.format(',') | Formatter for numeric values (ticks, tooltip). | | formatTotalLabel | (total: number) => string | formatValueLabel | Formatter for total labels when showTotals is true. | | onBarClick | (dataPoint, seriesKey) => void | — | Click handler per stacked rect. | | onBarHover | (dataPoint: StackedBarChartDataPoint | null, seriesKey?: string) => void | — | Hover enter/leave callback; on leave receives null. |

BarChartStyleProps and defaults

| Key | Default | | --- | --- | | titleColor | #000000 | | titleFontSize | 18 | | titleFontWeight | 600 | | titleFontFamily | Inter, sans-serif | | axisTextColor | #6b7280 | | axisTextFontSize | 12 | | axisTextFontFamily | Inter, sans-serif | | gridLineColor | #e5e7eb | | gridLineStrokeWidth | 1 | | backgroundColor | transparent | | totalTextColor | #295e84 | | totalTextFontSize | 12 | | totalTextFontFamily | Inter, sans-serif |

Data types

type StackedBarChartDataPoint = {
  id: string;
  label: string;
  values: Record<string, number>;
  total?: number; // computed internally
};

type BarChartSeries = {
  key: string;   // must match keys in data.values
  label: string; // shown in legend and tooltips
  color: string; // fill color
};

Licensing

MIT