> ## 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 four 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                      |

## Geoms

There are five built-in geoms. Everything in the recipes below is one of these, sometimes layered:

| 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     |

## 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 (default for most geoms) |
| `'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
```

## 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, innerRadius })` | Bend the plane into a circle — turns bars into pie/donut wedges |

## 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: { interpolate: 'catmull-rom' } })`                              |
| **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: 'stack' })` + `coord.polar({ theta: 'y' })`                    |
| **Donut**               | `geom.bar({ position: 'stack' })` + `coord.polar({ theta: 'y', innerRadius: 0.5 })`  |
| **Radar**               | `geom.line()` + `coord.polar({ theta: 'x' })` + `scale.x.discrete()`                 |
| **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()`                           |
| **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.

## 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
* [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>