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

## Overview

Data labels display numeric values directly on chart elements like bars, columns, lines and pie slices. They make it easier to read exact values without relying on tooltips or axes.

```tsx theme={null}
const config: GraphConfig = {
  dataLabels: {
    showDataLabels: true,
    dataLabelFormat: 'absolute',
  },
};
```

## Show data labels

<ParamField path="dataLabels.showDataLabels" type="boolean" default="false">
  Whether to show numeric data labels on the chart. When `true`, values appear directly on bars, columns, line points
  and pie slices.
</ParamField>

```tsx theme={null}
const config: GraphConfig = {
  type: 'column',
  data: {
    columns: [
      { key: 'product', label: 'Product' },
      { key: 'sales', label: 'Sales' },
    ],
    rows: [
      { product: 'A', sales: 100 },
      { product: 'B', sales: 150 },
      { product: 'C', sales: 120 },
    ],
  },
  dataLabels: {
    showDataLabels: true, // Show "100", "150", "120" on top of columns
  },
};
```

<Note>
  Data labels respect the number formatting configured in `appearance.numberFormat`, including decimal places and
  abbreviations.
</Note>

## Label format

<ParamField path="dataLabels.dataLabelFormat" type="'absolute' | 'percentage'" default="absolute">
  Format to use for the data labels: - `'absolute'` - Show the actual value from the data - `'percentage'` - Show values
  as percentages (calculated differently for each graph type)
</ParamField>

### Absolute values

Show the actual numeric values:

```tsx theme={null}
dataLabels: {
  showDataLabels: true,
  dataLabelFormat: 'absolute'  // Shows: 100, 150, 120
}
```

### Percentage values

Show values as percentages. The calculation method depends on the chart type:

**For stacked charts:**

* Shows each segment as a percentage of the total stack

**For pie/donut charts:**

* Shows each slice as a percentage of the total

**For other charts:**

* Shows each value as a percentage of the total sum

```tsx theme={null}
const config: GraphConfig = {
  type: 'columnStacked',
  dataLabels: {
    showDataLabels: true,
    dataLabelFormat: 'percentage', // Shows each segment as % of total
  },
};
```

## Stack totals

<ParamField path="dataLabels.showStackTotals" type="boolean" default="false">
  Whether to show total values above stacked bar or column stacks. Only applicable to stacked bar and column charts.
</ParamField>

```tsx theme={null}
const config: GraphConfig = {
  type: 'columnStacked',
  data: {
    columns: [
      { key: 'quarter', label: 'Quarter' },
      { key: 'online', label: 'Online' },
      { key: 'retail', label: 'Retail' },
    ],
    rows: [
      { quarter: 'Q1', online: 100, retail: 50 },
      { quarter: 'Q2', online: 120, retail: 60 },
      { quarter: 'Q3', online: 140, retail: 55 },
    ],
  },
  dataLabels: {
    showStackTotals: true, // Shows "150", "180", "195" above each stack
  },
};
```

<Tip>
  `showStackTotals` and `showDataLabels` can be used together. This shows both the individual segment values and the
  total for each stack.
</Tip>

## Category labels

<ParamField path="dataLabels.showCategoryLabels" type="boolean" default="false">
  Whether to show category names on pie and donut charts. Only applicable to pie and donut chart types. When `true`,
  category names appear next to each slice.
</ParamField>

```tsx theme={null}
const config: GraphConfig = {
  type: 'pie',
  data: {
    columns: [
      { key: 'department', label: 'Department' },
      { key: 'budget', label: 'Budget' },
    ],
    rows: [
      { department: 'Marketing', budget: 50000 },
      { department: 'Sales', budget: 75000 },
      { department: 'Engineering', budget: 120000 },
    ],
  },
  dataLabels: {
    showCategoryLabels: true, // Shows "Marketing", "Sales", "Engineering"
  },
};
```

## Combining data labels

You can combine different data label options for comprehensive labelling:

### Stacked chart with totals and segment labels

```tsx theme={null}
const config: GraphConfig = {
  type: 'barStacked',
  dataLabels: {
    showDataLabels: true, // Show values on each segment
    dataLabelFormat: 'absolute', // Show actual values (not percentages)
    showStackTotals: true, // Also show the total for each bar
  },
};
```

### Pie chart with categories and percentages

```tsx theme={null}
const config: GraphConfig = {
  type: 'pie',
  dataLabels: {
    showDataLabels: true, // Show values on each slice
    dataLabelFormat: 'percentage', // Show as percentages
    showCategoryLabels: true, // Also show category names
  },
};
```

## Chart type compatibility

Different data label options work with different chart types:

| Option                          | Compatible chart types                                               |
| ------------------------------- | -------------------------------------------------------------------- |
| `showDataLabels`                | All chart types except table                                         |
| `dataLabelFormat: 'percentage'` | All chart types except table                                         |
| `showStackTotals`               | `barStacked`, `barStackedFill`, `columnStacked`, `columnStackedFill` |
| `showCategoryLabels`            | `pie`, `donut`                                                       |

## Complete example

```tsx theme={null}
const config: GraphConfig = {
  type: 'columnStacked',
  data: {
    columns: [
      { key: 'month', label: 'Month' },
      { key: 'new', label: 'New customers' },
      { key: 'returning', label: 'Returning customers' },
    ],
    rows: [
      { month: 'Jan', new: 45, returning: 120 },
      { month: 'Feb', new: 52, returning: 135 },
      { month: 'Mar', new: 48, returning: 142 },
    ],
  },
  dataLabels: {
    showDataLabels: true, // Show segment values
    dataLabelFormat: 'absolute', // Show actual numbers
    showStackTotals: true, // Show totals above stacks
  },
  appearance: {
    numberFormat: {
      decimalPlaces: 0, // No decimals for data labels
      abbreviation: 'none', // Don't abbreviate
    },
  },
};
```