> ## Documentation Index
> Fetch the complete documentation index at: https://docs.graphy.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

A chart type is a **recipe** you compose — a geom, a coordinate system, a position mode, and the scales you declare. A vertical bar chart and a pie chart use the *same* `geom.bar()`; they differ only in coordinate system.

## The building blocks

Every spec is assembled from five kinds of ingredient:

| Ingredient | Builder | What it does |
| - | - | - |
| **Mapping** | `mapping({ ... })` / `createSpec({ ... })` | Binds data columns to aesthetics (`x`, `y`, `color`, `size`, …) |
| **Geom** | `geom.*()` | The shape drawn for each observation |
| **Scale** | `scale.*()` | Turns data values into positions, colors and sizes |
| **Coord** | `coord.*()` | The coordinate system the geom is drawn in |
| **Styles** | `styles({ ... })` with `style.*` | Paint: color, opacity, borders, corner radius, stroke width, marker size |

A geom's `params` are **geometry** — the bar's band width, the line's curve family, how a path handles nulls. Everything a mark is painted with lives in the stylesheet: see [Styling](/sdk-next/config/styling).

## Geoms

There are six built-in geoms. Everything in the recipes below is one of these, sometimes layered. A plugin can contribute more — see [custom geoms](/sdk-next/extending/custom-geoms):

| Geom | Draws | Typical use |
| - | - | - |
| `geom.point()` | A point per observation | Scatter, bubble, dot plots |
| `geom.line()` | A path connecting observations | Line charts, trends |
| `geom.area()` | A filled band under a line | Area charts |
| `geom.bar()` | A rectangle (or arc, in polar) per observation | Columns, bars, pie, donut |
| `geom.rule()` | A single reference line across the panel | Goal lines, thresholds |
| `geom.tile()` | A cell filling its band on both axes | Heatmaps, matrices, waffles |

## Position modes

When a geom maps `color` (or `group`), multiple observations share an x value. The layer's `position` decides how they arrange:

| Position | Effect |
| - | - |
| `'identity'` | Draw at the raw value; observations may overlap |
| `'stack'` | Stack observations on top of each other |
| `'fill'` | Stack, then normalise each stack to 100% |
| `'dodge'` | Place observations side by side within the band |

```tsx theme={null}
geom.bar({ position: 'stack' }); // stacked columns
geom.bar({ position: 'dodge' }); // grouped columns
```

Each geom brings its own default, so a multi-series layer arranges sensibly before you say anything:

| Geom | Default position |
| - | - |
| `geom.bar()` | `'dodge'` |
| `geom.area()` | `'stack'` |
| `geom.point()`, `geom.line()`, `geom.rule()`, `geom.tile()` | `'identity'` |

## Coordinate systems

| Coord | Effect |
| - | - |
| `coord.cartesian()` | Standard x–y plane (the default) |
| `coord.flip()` | Swap the axes — turns columns into horizontal bars |
| `coord.polar({ theta, startAngle, innerRadius })` | Bend the plane into a circle — turns bars into pie/donut wedges |

`startAngle` is in degrees and defaults to `0`; `innerRadius` is a `0`–`1` fraction of the outer radius and defaults to `0`.

## Common recipes

Reach for these as starting points. Each is a `pipe(createSpec(...), ...)` chain; the scales are elided for brevity but always required for mapped position aesthetics.

| Chart | Recipe |
| - | - |
| **Line** | `geom.line()` |
| **Smooth line** | `geom.line({ params: { curve: 'smooth' } })` |
| **Area** | `geom.area()` |
| **Stacked area** | `geom.area({ position: 'stack' })`, `color` mapped |
| **Column** (vertical) | `geom.bar()` + `scale.x.discrete()` |
| **Bar** (horizontal) | `geom.bar()` + `coord.flip()` |
| **Stacked column** | `geom.bar({ position: 'stack' })`, `color` mapped |
| **100% stacked column** | `geom.bar({ position: 'fill' })`, `color` mapped |
| **Grouped column** | `geom.bar({ position: 'dodge' })`, `color` mapped |
| **Pie** | `geom.bar({ position: 'fill' })` + `coord.polar({ theta: 'y' })` |
| **Donut** | `geom.bar({ position: 'fill' })` + `coord.polar({ theta: 'y', innerRadius: 0.5 })` |
| **Radar** | `geom.line()` + `coord.polar({ theta: 'x' })` + `scale.x.discrete()` + `scale.y({ domainMin: 0 })` |
| **Rose / coxcomb** | `geom.bar()` + `coord.polar({ theta: 'x' })` + `scale.x.discrete()` |
| **Radial bar** | `geom.bar({ position: 'stack' })` + `coord.polar({ theta: 'y', innerRadius: 0.15 })` |
| **Scatter** | `geom.point()` + `scale.x.continuous()` + `scale.y.continuous()` |
| **Bubble** | `geom.point()` + `size` mapped + `scale.size.continuous()` |
| **Heatmap** | `geom.tile()` + a category on `x` and `y` + `scale.color.continuous()` |
| **Waffle** | `geom.tile()` over a 10×10 grid + `scale.color.discrete()` |
| **Combo** | `geom.bar()` + `geom.line()` layered, the line on `ySecondary` |

## Layers

A geom is a **layer**. Add several to one spec and they draw over each other, sharing the spec-level mapping unless a layer overrides it. This is how combos and decorated lines are built:

```tsx theme={null}
const spec = pipe(
  createSpec({ x: 'month', y: 'revenue' }),
  geom.line(), // the trend
  geom.point(), // a dot on every vertex
  scale.x(),
  scale.y()
);
```

Layers are drawn in the order you pipe them — later geoms sit on top. Give a layer an `id` and a stylesheet entry can scope to it with `{ layer: 'trend' }`, which is how one series in a stack of layers reads differently from the rest.

Every recipe here also gets an entrance animation when it mounts, tuned through the renderer's [`animation` prop](/sdk-next/rendering/interactivity#animation).

## Guides for each type

The pages in this section walk through a specific chart type end to end — data shape, spec, and the options that matter most.

* [Line](/sdk-next/graph-types/line) — trends over a continuous or ordered x-axis
* [Bar & column](/sdk-next/graph-types/bar) — vertical columns for comparing categories, horizontal bars for ranking
* [Area](/sdk-next/graph-types/area) — filled trends, stacked or plain
* [Pie & donut](/sdk-next/graph-types/pie) — parts of a whole
* [Radar & radial](/sdk-next/graph-types/radial) — categories compared around a circle
* [Scatter & bubble](/sdk-next/graph-types/scatter) — correlation and three-variable plots
* [Heatmap & waffle](/sdk-next/graph-types/heatmap) — a value per cell of a category × category grid
* [Combo](/sdk-next/graph-types/combo) — two metrics on dual axes

<Note>
  Don't see the chart you need? Because charts are composed from these
  ingredients, most are a small tweak to a recipe above — swap the geom, add
  `coord.flip()`, or change the `position`.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.