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

# Headline numbers

## Overview

Headline numbers display key summary metrics prominently at the top of your chart. They're ideal for highlighting the most important value in your data at a glance.

```tsx theme={null}
const config: GraphConfig = {
  headlineNumbers: {
    show: 'total',
    compareWith: 'previous',
    size: 'large',
  },
};
```

## Display mode

<ParamField path="headlineNumbers.show" type="'current' | 'average' | 'total' | 'conversion' | 'none'" default="none">
  How to calculate the headline number: - `'current'` - The last value in the series - `'average'` - The arithmetic mean
  of the series - `'total'` - The sum of all values in the series - `'conversion'` - The ratio between the first and
  last values (shown as a percentage) - `'none'` - Don't show any headline numbers
</ParamField>

### Current value

Show the most recent value in your data:

```tsx theme={null}
const config: GraphConfig = {
  type: 'line',
  data: {
    columns: [
      { key: 'month', label: 'Month' },
      { key: 'users', label: 'Users' },
    ],
    rows: [
      { month: 'Jan', users: 1000 },
      { month: 'Feb', users: 1200 },
      { month: 'Mar', users: 1450 },
    ],
  },
  headlineNumbers: {
    show: 'current', // Shows 1,450 (the March value)
  },
};
```

**Best for:** Time series showing current state, latest measurements

### Average

Show the mean of all values:

```tsx theme={null}
headlineNumbers: {
  show: 'average'; // Shows the arithmetic mean
}
```

**Best for:** Understanding typical values, smoothing out volatility

### Total

Show the sum of all values:

```tsx theme={null}
headlineNumbers: {
  show: 'total'; // Shows the sum
}
```

**Best for:** Cumulative data, total revenue, aggregate counts

### Conversion rate

Show the percentage change from first to last value:

```tsx theme={null}
const config: GraphConfig = {
  type: 'funnel',
  data: {
    columns: [
      { key: 'stage', label: 'Stage' },
      { key: 'count', label: 'Count' },
    ],
    rows: [
      { stage: 'Visitors', count: 10000 },
      { stage: 'Signups', count: 2500 },
      { stage: 'Purchases', count: 500 },
    ],
  },
  headlineNumbers: {
    show: 'conversion', // Shows 5% (500/10000)
  },
};
```

<Note>
  Conversion rate is designed for funnel charts and calculates the ratio between the first and last values as a
  percentage.
</Note>

**Best for:** Funnel conversions, efficiency metrics

## Comparison

<ParamField path="headlineNumbers.compareWith" type="'previous' | 'first' | 'none'" default="none" optional>
  Show a trend arrow comparing the headline value to another value: - `'previous'` - Compare to the previous value in
  the series - `'first'` - Compare to the first value in the series - `'none'` - Don't show a comparison
</ParamField>

### Compare with previous

Show how the headline value has changed from the previous data point:

```tsx theme={null}
const config: GraphConfig = {
  data: {
    columns: [
      { key: 'quarter', label: 'Quarter' },
      { key: 'revenue', label: 'Revenue' },
    ],
    rows: [
      { quarter: 'Q1', revenue: 100000 },
      { quarter: 'Q2', revenue: 120000 },
      { quarter: 'Q3', revenue: 135000 },
    ],
  },
  headlineNumbers: {
    show: 'current', // Show Q3 value (135,000)
    compareWith: 'previous', // Compare to Q2 (120,000)
    // Shows: 135,000 ↑ +12.5%
  },
};
```

### Compare with first

Show how the headline value has changed from the first data point:

```tsx theme={null}
headlineNumbers: {
  show: 'current',
  compareWith: 'first'
  // Compare current value to the very first value
}
```

**Best for:** Growth since start, year-over-year changes

## Size

<ParamField path="headlineNumbers.size" type="'auto' | 'small' | 'medium' | 'large'" default="auto" optional>
  Size of the headline metric: - `'auto'` - Automatically choose the appropriate size based on chart dimensions -
  `'small'` - Small font size - `'medium'` - Medium font size - `'large'` - Large font size
</ParamField>

```tsx theme={null}
headlineNumbers: {
  show: 'total',
  size: 'large'  // Extra prominent
}
```

## Multiple series

When your chart has multiple data series, a headline number is shown for each series:

```tsx theme={null}
const config: GraphConfig = {
  data: {
    columns: [
      { key: 'month', label: 'Month' },
      { key: 'productA', label: 'Product A' },
      { key: 'productB', label: 'Product B' },
    ],
    rows: [
      { month: 'Jan', productA: 100, productB: 150 },
      { month: 'Feb', productA: 120, productB: 160 },
    ],
  },
  headlineNumbers: {
    show: 'total', // Shows totals for both Product A and Product B
  },
};
```

## Complete example

```tsx theme={null}
const config: GraphConfig = {
  type: 'line',
  data: {
    columns: [
      { key: 'week', label: 'Week' },
      { key: 'signups', label: 'Signups' },
    ],
    rows: [
      { week: 'Week 1', signups: 45 },
      { week: 'Week 2', signups: 52 },
      { week: 'Week 3', signups: 48 },
      { week: 'Week 4', signups: 61 },
    ],
  },
  content: {
    title: 'Weekly signups',
  },
  headlineNumbers: {
    show: 'current', // Show current week (61)
    compareWith: 'previous', // Compare to last week (48)
    size: 'large', // Make it prominent
  },
  // Display shows: "61 ↑ +27.1%"
};
```