# CartesianChart

> The cartesian engine.

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

The cartesian engine. Line, area and column series share one plot, one
value axis (plus an optional right axis), the legend, tooltip, keyboard
exploration, annotations, entry animation and the zoom brush.
`LineChart`, `AreaChart`, `BarChart` and `ComboChart` are presets of it.

## Import

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

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

## Usage

```tsx
<CartesianChart
  title="Ventas por servicio"
  categories={weekdays}
  series={[
      { id: "cortes", name: "Cortes", kind: "column", data: cuts },
      { id: "barba", name: "Barba", kind: "column", data: beard },
    ]}
  valueFormat="currency"
  height={300}
  labels={spanishLabels}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `categories` * | `readonly XValue[]` |  | One entry per data point: strings, numbers or dates. |
| `series` * | `readonly CartesianSeries[]` |  |  |
| `title` * | `string` |  | Accessible name of the chart (`aria-label` of the drawing). |
| `description` | `string` |  | Extra sentence for the hidden data table caption. |
| `height` | `number \| "fill"` | `300` | 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`). |
| `orientation` | `"horizontal" \| "vertical"` | `"vertical"` | "horizontal" lays categories top to bottom (bar charts). |
| `stack` | `"normal" \| "none" \| "percent"` | `"none"` | Stacks every area and column series. |
| `curve` | `"linear" \| "smooth" \| "step" \| "step-before" \| "step-after"` | `"linear"` |  |
| `markers` | `boolean` | `false` | Dots on every line point. Hovered points are always marked. |
| `dataLabels` | `boolean` | `false` | Values printed on the marks. |
| `lineGradient` | `boolean` | `false` | Strokes lines with a gradient from each series color to the next palette color. |
| `transition` | `boolean` | `false` | Eases lines and areas between data updates (live data); off by default. |
| `maxPoints` | `number \| false` | `DEFAULT_MAX_POINTS` | 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. |
| `gradient` | `boolean` | `true` | Gradient fill under areas (default true). |
| `barRadius` | `number` | `6` | Corner radius at the value end of bars, 6 by default. |
| `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). |
| `xScale` | `"time" \| "auto" \| "band"` | `"auto"` | "time" spaces dates by real elapsed time; "auto" picks it when every category is a Date and no series is a column. |
| `yAxis` | `ValueAxisOptions` |  |  |
| `rightAxis` | `ValueAxisOptions` |  | Secondary axis for series with `axis: "right"`. |
| `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`. |
| `grid` | `boolean` | `true` | Background gridlines (default true). |
| `legend` | `boolean \| "top" \| "bottom"` |  | Legend placement, or false to hide it. Defaults to "top" with two or more series. |
| `tooltip` | `boolean` | `true` | Shared tooltip (default true). |
| `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`. |
| `brush` | `boolean` | `false` | Drag-to-zoom on the plot plus an overview brush with a reset button. |
| `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` | `false` |  |
| `animate` | `boolean` | `true` | Entry animation (default true; always off with prefers-reduced-motion). |
| `initialHidden` | `readonly string[]` |  | Series hidden at first; the legend can show them. |
| `labels` | `Partial<ChartLabels>` |  |  |
| `className` | `string` |  |  |

`*` marks a required prop.

## Storybook stories

- [Default](/storybook/?path=/story/charts-primitives-cartesianchart--default)
- [Stacked](/storybook/?path=/story/charts-primitives-cartesianchart--stacked)
- [Horizontal](/storybook/?path=/story/charts-primitives-cartesianchart--horizontal)
- [Columns And Line On Right Axis](/storybook/?path=/story/charts-primitives-cartesianchart--columns-and-line-on-right-axis)
- [Area With Goal](/storybook/?path=/story/charts-primitives-cartesianchart--area-with-goal)
- [With Brush](/storybook/?path=/story/charts-primitives-cartesianchart--with-brush)
- [Loading](/storybook/?path=/story/charts-primitives-cartesianchart--loading)
- [Empty](/storybook/?path=/story/charts-primitives-cartesianchart--empty)

## Source

`packages/ui/src/charts/core/cartesian/cartesian-chart.tsx`