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

# Data labels

Data labels print each observation's value directly on the observation. Unlike the other topics in this section, they're **not** a `config` field — they're a per-layer option on a [geom](/sdk-next/concepts/geoms), because a label attaches to a specific observation.

```tsx theme={null}
geom.bar({
  dataLabels: { showDataLabels: true },
});
```

## Options

<ParamField path="showDataLabels" type="boolean" default="false">
  Turn labels on for this layer.
</ParamField>

<ParamField path="format" type="'absolute' | 'percentage'" default="absolute">
  Show the raw value, or its share of the total.
</ParamField>

<ParamField path="position" type="'auto' | 'inside' | 'outside'" default="auto">
  Where the label sits relative to the observation. `'auto'` lets the engine
  fit, flip or drop labels as space allows; `'inside'` and `'outside'` render
  exactly as asked.
</ParamField>

<ParamField path="justify" type="'start' | 'center' | 'end' | 'panel-start' | 'panel-end'">
  Anchor along the observation's value axis. `'end'` is the value tip whatever
  the orientation. Only consulted when `position` is explicit.
</ParamField>

<ParamField path="align" type="'start' | 'center' | 'end'">
  Anchor across the observation's other axis. Only consulted when `position` is
  explicit.
</ParamField>

<ParamField path="offset" type="number">
  Gap in pixels between the observation's edge and the label. Defaults to 4 for
  bars and wedges, 12 for points and lines.
</ParamField>

<ParamField path="showStackTotals" type="boolean" default="false">
  On stacked bars, print the stack total at the end of each stack.
</ParamField>

<ParamField path="showCategoryLabels" type="boolean" default="false">
  On polar bars (pie/donut) prepend the category to the value ("North · 35%").
  On cartesian bars, emit a second category label per bar.
</ParamField>

## Examples

Percentage labels on a pie's wedges, with the category name:

```tsx theme={null}
geom.bar({
  position: 'stack',
  dataLabels: {
    showDataLabels: true,
    format: 'percentage',
    showCategoryLabels: true,
  },
});
```

Totals at the top of each stacked column:

```tsx theme={null}
geom.bar({
  position: 'stack',
  dataLabels: { showDataLabels: true, showStackTotals: true },
});
```

## Related

* [Geoms & layers](/sdk-next/concepts/geoms) — where layer options live
* [Number format](/sdk-next/config/number-format) — how label values are formatted