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

# Geoms & layers

A **geom** is what a chart draws for its data — a line, a bar, a point. Each geom is a **layer** in the spec; add several and they stack into one chart. Geoms are the visible half of the grammar: [mappings](/sdk-next/concepts/mappings) and [scales](/sdk-next/concepts/scales) decide *where* things go, geoms decide *what* is drawn there.

## The built-in geoms

| Geom           | Draws                                          | Reads                                        |
| -------------- | ---------------------------------------------- | -------------------------------------------- |
| `geom.point()` | A point per observation                        | `x`, `y`, `color`, `size`, `alpha`           |
| `geom.line()`  | A path connecting observations                 | `x`, `y`, `color`, `strokeWidth`, `lineType` |
| `geom.area()`  | A filled band under a line                     | `x`, `y`, `color`                            |
| `geom.bar()`   | A rectangle (or arc, in polar) per observation | `x`, `y`, `color`                            |
| `geom.rule()`  | A single reference line across the panel       | `x` or `y`                                   |

Each is a factory that returns a layer. Call it with options to configure the layer, and geom-specific `params` to style what it draws:

```tsx theme={null}
geom.line({ params: { interpolate: 'catmull-rom', showFill: true } });
geom.bar({ position: 'stack', params: { width: 0.8, borderRadius: 4 } });
geom.point({ params: { size: 6 } });
```

The `params` available depend on the geom — see each [chart type](/sdk-next/graph-types/index) page, or the reference for the full list.

## Layers

Every `geom.*()` you pipe in adds a layer, drawn in order — later layers sit on top. Layers share the spec-level [mapping](/sdk-next/concepts/mappings) unless one overrides it. This is how decorated and combo charts are built:

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

## Common layer options

Beyond `params`, every geom accepts these options:

| Option        | Purpose                                                                                            |
| ------------- | -------------------------------------------------------------------------------------------------- |
| `aes`         | A [layer-local mapping](/sdk-next/concepts/mappings#where-a-mapping-lives), merged over the spec's |
| `position`    | How overlapping observations arrange — see below                                                   |
| `stat`        | A [statistical transform](/sdk-next/advanced/statistics) for this layer (count, mean, smooth)      |
| `yScaleType`  | Bind the layer to the `'primary'` or `'secondary'` y-axis                                          |
| `dataLabels`  | Show [value labels](/sdk-next/config/data-labels) on each observation                              |
| `transforms`  | [Transforms](/sdk-next/advanced/transforms) applied to this layer's view of the data               |
| `interactive` | Set `false` to exclude the layer from hover hit-testing                                            |

## Position modes

When several observations share the same x (because `color` or `group` splits the data), a layer's `position` decides how they arrange:

| Position                 | Effect                                          |
| ------------------------ | ----------------------------------------------- |
| `'identity'` *(default)* | Draw at the raw value; observations may overlap |
| `'stack'`                | Stack observations end to end                   |
| `'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
geom.area({ position: 'stack' }); // stacked area
```

## Next

* [Scales](/sdk-next/concepts/scales) — map values to positions, colors and sizes
* [Statistics](/sdk-next/advanced/statistics) — summarise a layer before drawing it
* [Chart types](/sdk-next/graph-types/index) — geoms assembled into recipes