# BarChart

> Columns (`orientation="vertical"`, default) or horizontal bars.

Source: https://ui.jcsoftdev.com/docs/components/bar-chart

Columns (`orientation="vertical"`, default) or horizontal bars. Several
series are grouped side by side, or piled with `stack`. Bars are rounded at
their value end only, negative values grow downwards (or to the left).

Also: floating `ranges`, `stackGroup` piles side by side, `categoryGroups`
labels under the axis, a `reversed` value axis (`yAxis.reversed`), SVG
`pattern` fills per series, per-bar `colors` / `distributed`, and
`onCategoryClick` for drill-down.

## Import

```ts
import { BarChart } from "@jcsoftdev/ui/charts";
```

Single-component entry points tree-shake to just this component: `@jcsoftdev/ui/charts/bar-chart`.

## Usage

```tsx
<BarChart
  title="Citas por barbero esta semana"
  categories={barbers}
  series={[{ id: "citas", name: "Citas", data: appointmentsThisWeek }]}
  valueFormat="integer"
  orientation="vertical"
  stack="none"
  barRadius={6}
  height={300}
  dataLabels={false}
  grid
  tooltip
  loading={false}
  animate
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `series` * | `readonly BarSeries[]` |  |  |
| `distributed` | `boolean` | `false` | One palette color per bar instead of one per series (single-series charts). |
| `legend` | `boolean \| "top" \| "bottom"` |  | Legend placement, or false to hide it. Defaults to "top" with two or more series. |
| `title` * | `string` |  | Accessible name of the chart (`aria-label` of the drawing). |
| `animate` | `boolean` |  | Entry animation (default true; always off with prefers-reduced-motion). |
| `className` | `string` |  |  |
| `grid` | `boolean` |  | Background gridlines (default true). |
| `tooltip` | `boolean` |  | Shared tooltip (default true). |
| `orientation` | `"horizontal" \| "vertical"` |  | "horizontal" lays categories top to bottom (bar charts). |
| `barRadius` | `number` |  | Corner radius at the value end of bars, 6 by default. |
| `categories` * | `readonly XValue[]` |  | One entry per data point: strings, numbers or dates. |
| `description` | `string` |  | Extra sentence for the hidden data table caption. |
| `height` | `number \| "fill"` |  | Height of the plot in pixels, 300 by default. |
| `aspectRatio` | `number` |  | Width / height ratio; sizes the plot from the container width (wins over a pixel `height`). |
| `stack` | `"normal" \| "none" \| "percent"` |  | Stacks every area and column series. |
| `dataLabels` | `boolean` |  | Values printed on the marks. |
| `lineGradient` | `boolean` |  | Strokes lines with a gradient from each series color to the next palette color. |
| `transition` | `boolean` |  | Eases lines and areas between data updates (live data); off by default. |
| `maxPoints` | `number \| false` |  | Series with more points than this are reduced with LTTB, 2000 by default; `false` draws every point. |
| `syncId` | `string` |  | Charts with the same id share hover (crosshair and tooltip) and the zoom window. |
| `onPointClick` | `((point: CartesianPointEvent) => void)` |  | Called with the category (and nearest series) under the pointer when the plot is clicked or Enter is pressed. |
| `valueFormat` | `ValueFormat` |  | Format of values in tooltips, labels and the data table. |
| `xFormat` | `((value: XValue) => string)` |  | Label of a category on the axis and in the tooltip (dates get Spanish defaults). |
| `yAxis` | `ValueAxisOptions` |  |  |
| `axes` | `readonly CartesianAxisSpec[]` |  | Any number of value axes. `yAxis` and `rightAxis` are shorthand for the ids "left" and "right"; more entries stack outward on their `side` (right by default) and series pick one with `axis`. |
| `annotations` | `readonly ChartAnnotation[]` |  |  |
| `categoryLabelRotation` | `number` |  | Tilts the category labels (degrees, e.g. -45) so long names fit; vertical charts only. |
| `categoryGroups` | `readonly CategoryGroup[]` |  | Second tier of labels under the category axis (vertical charts); counts must add up to the categories. |
| `onCategoryClick` | `((index: number) => void)` |  | Click (or Enter on the focused plot) on a category; receives its index in `categories`. |
| `overlay` | `CartesianOverlay` |  | Extra layers over the plot, e.g. the ruler and ink tools of `useChartInk`. Vertical charts only. |
| `rangeSelect` | `{ value: readonly [number, number] \| null; onChange: (range: readonly [number, number] \| null) => void; }` |  |  |
| `loading` | `boolean` |  |  |
| `initialHidden` | `readonly string[]` |  | Series hidden at first; the legend can show them. |
| `labels` | `Partial<ChartLabels>` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-barchart--default)
- [Grouped](/storybook/?path=/story/charts-barchart--grouped)
- [Stacked](/storybook/?path=/story/charts-barchart--stacked)
- [Stacked 100%](/storybook/?path=/story/charts-barchart--stacked-percent)
- [Horizontal (top services)](/storybook/?path=/story/charts-barchart--horizontal)
- [Horizontal Stacked](/storybook/?path=/story/charts-barchart--horizontal-stacked)
- [Negative Values](/storybook/?path=/story/charts-barchart--negative-values)
- [Annotation (weekly goal)](/storybook/?path=/story/charts-barchart--with-goal)
- [Data Labels](/storybook/?path=/story/charts-barchart--data-labels)
- [Custom Data Labels](/storybook/?path=/story/charts-barchart--custom-data-labels)
- [Distributed (a color per bar)](/storybook/?path=/story/charts-barchart--distributed)
- [Rotated Labels](/storybook/?path=/story/charts-barchart--rotated-labels)
- [Range column (shifts)](/storybook/?path=/story/charts-barchart--range-column)
- [Range bar (service duration)](/storybook/?path=/story/charts-barchart--range-bar)
- [Grouped stacked (income vs costs)](/storybook/?path=/story/charts-barchart--grouped-stacked)
- [Group labels (quarters)](/storybook/?path=/story/charts-barchart--group-labels)
- [Reversed value axis](/storybook/?path=/story/charts-barchart--reversed)
- [Patterns (color-blind friendly)](/storybook/?path=/story/charts-barchart--patterned)
- [Patterned Stacked](/storybook/?path=/story/charts-barchart--patterned-stacked)
- [Drilldown](/storybook/?path=/story/charts-barchart--drilldown)
- [Race (animated re-sort)](/storybook/?path=/story/charts-barchart--race)
- [Loading](/storybook/?path=/story/charts-barchart--loading)
- [Empty](/storybook/?path=/story/charts-barchart--empty)
- [Fill Parent](/storybook/?path=/story/charts-barchart--fill-parent)
- [Narrow](/storybook/?path=/story/charts-barchart--narrow)

## Source

`packages/ui/src/charts/bar-chart/bar-chart.tsx`