# Stat
Package: @mantine/core
Import: import { Stat } from '@mantine/core';
Description: Display a key metric with a label, formatted value, trend and countdown

## Usage

`Stat` displays a single metric: a label, a formatted value and an optional trend indicator:

```tsx
import { Stat } from '@mantine/core';

function Demo() {
  return (
    <Stat
      label="Active users"
      value={92410}
      thousandSeparator size="md" diff={12.4} withDiffIcon={true} animate={false} loading={false}
    />
  );
}
```


## Value formatting

Numeric values are formatted with [NumberFormatter](https://alpha.mantine.dev/llms/core-number-formatter.md) and support the same formatting props.
Numeric strings are formatted the same way, other strings are rendered as is.
Use `prefix` and `suffix` to add units or currency:

```tsx
import { Group, Stat } from '@mantine/core';

function Demo() {
  return (
    <Group gap={50}>
      <Stat
        label="Revenue"
        value={1340.5}
        prefix="$"
        decimalScale={2}
        fixedDecimalScale
        thousandSeparator
      />
      <Stat label="Conversion" value={4.28} suffix="%" />
      <Stat label="Storage used" value={82} suffix="/ 100 GB" />
    </Group>
  );
}
```


To fully control value rendering, pass a `formatter` function.
Formatting props and `animate` are ignored when `formatter` is set:

```tsx
import { Stat } from '@mantine/core';

function Demo() {
  return (
    <Stat
      label="Temperature"
      value={21.5}
      formatter={(value) => `${value} °C`}
    />
  );
}
```

## Trend indicator

Set `diff` prop to display a trend delta below the value. Positive values are green,
negative values are red, zero is dimmed. The delta is formatted as a signed percentage:

```tsx
import { Group, Stat } from '@mantine/core';

function Demo() {
  return (
    <Group gap={50}>
      <Stat label="Revenue" value={92410} thousandSeparator diff={12.4} />
      <Stat label="Churn" value={1240} thousandSeparator diff={-8.2} />
      <Stat label="Stable" value={512} diff={0} withDiffIcon={false} />
    </Group>
  );
}
```


Use `diffFormatter` to change the delta text and `withDiffIcon={false}` to hide the arrow:

```tsx
import { Stat } from '@mantine/core';

function Demo() {
  return (
    <Stat
      label="New customers"
      value={482}
      diff={38}
      diffFormatter={(diff) => `${diff > 0 ? '+' : ''}${diff} this week`}
    />
  );
}
```

## Icon

Use `icon` prop to display an icon next to the value:

```tsx
import { CoinsIcon, DownloadSimpleIcon, UsersIcon } from '@phosphor-icons/react';
import { Group, Stat } from '@mantine/core';

function Demo() {
  return (
    <Group gap={50}>
      <Stat label="Users" value={92410} thousandSeparator diff={12.4} icon={<UsersIcon size={28} />} />
      <Stat
        label="Revenue"
        value={1340.5}
        prefix="$"
        decimalScale={2}
        fixedDecimalScale
        thousandSeparator
        diff={4.1}
        icon={<CoinsIcon size={28} />}
      />
      <Stat label="Downloads" value={18320} thousandSeparator icon={<DownloadSimpleIcon size={28} />} />
    </Group>
  );
}
```


## Loading state

Set `loading` prop to display a [Skeleton](https://alpha.mantine.dev/llms/core-skeleton.md) instead of the value and hide the trend indicator:

```tsx
import { Group, Stat } from '@mantine/core';

function Demo() {
  return (
    <Group gap={50}>
      <Stat label="Active users" value={92410} thousandSeparator loading />
      <Stat
        label="Revenue"
        value={1340.5}
        prefix="$"
        decimalScale={2}
        fixedDecimalScale
        thousandSeparator
        loading
      />
    </Group>
  );
}
```


## Animated value

Set `animate` prop to animate numeric value changes with [RollingNumber](https://alpha.mantine.dev/llms/core-rolling-number.md):

```tsx
import { useState } from 'react';
import { Button, Stack, Stat } from '@mantine/core';

function Demo() {
  const [value, setValue] = useState(92410);

  return (
    <Stack align="flex-start">
      <Stat label="Active users" value={value} thousandSeparator animate />
      <Button onClick={() => setValue(Math.round(Math.random() * 100000))}>
        Update value
      </Button>
    </Stack>
  );
}
```


## Countdown

`Stat.Countdown` displays a live countdown to a target time. `value` is a `Date`
or a timestamp in milliseconds, keep it stable between renders: a new value restarts the countdown.

`format` prop accepts dayjs-style tokens:

* Units absent from the format roll into the leading token: `mm:ss` displays 62 minutes as `62:00`
* `S` displays tenths of a second, `SS` hundredths and `SSS` milliseconds
* Literal characters are escaped with square brackets, for example `D[d] HH:mm:ss`

```tsx
import { useState } from 'react';
import { Group, Stat } from '@mantine/core';

function Demo() {
  const [targets] = useState(() => ({
    sale: Date.now() + 1000 * 60 * 60 * 3,
    launch: Date.now() + 1000 * 60 * 60 * 26,
    round: Date.now() + 1000 * 60,
  }));

  return (
    <Group gap={50}>
      <Stat.Countdown label="Sale ends in" value={targets.sale} />
      <Stat.Countdown label="Launch in" value={targets.launch} format="D[d] HH:mm:ss" />
      <Stat.Countdown label="Round ends" value={targets.round} format="mm:ss.SSS" />
    </Group>
  );
}
```


`onFinish` is called once when the target time is reached, `onTick` is called on every
tick with the remaining time in milliseconds:

```tsx
import { useState } from 'react';
import { Stat } from '@mantine/core';

function Demo() {
  const [target] = useState(() => Date.now() + 1000 * 60 * 15);

  return (
    <Stat.Countdown
      label="Offer expires in"
      value={target}
      format="mm:ss"
      onFinish={() => console.log('Countdown finished')}
      onTick={(remainingMs) => console.log(remainingMs)}
    />
  );
}
```

## Color

Set `color` prop to change the value color:

```tsx
import { Stat } from '@mantine/core';

function Demo() {
  return <Stat label="Active users" value={92410} thousandSeparator color="blue" />;
}
```

## Compound components

For full control over the layout, use compound components instead of the shorthand props.
`Stat.Icon` is always placed next to the value, other components are rendered in the order they are declared:

```tsx
import { Stat } from '@mantine/core';

function Demo() {
  return (
    <Stat>
      <Stat.Value prefix="$">1,340.50</Stat.Value>
      <Stat.Label>Total revenue</Stat.Label>
      <Stat.Diff value={12.4} />
    </Stat>
  );
}
```


## Example: dashboard stat row

Compose several `Stat` components in a [SimpleGrid](https://alpha.mantine.dev/llms/core-simple-grid.md) to build a stat row:

```tsx
import { CoinsIcon, ShoppingCartIcon, UsersIcon } from '@phosphor-icons/react';
import { Paper, SimpleGrid, Stat } from '@mantine/core';

function Demo() {
  return (
    <SimpleGrid cols={{ base: 1, sm: 3 }} w="100%">
      <Paper withBorder p="md" radius="md">
        <Stat label="Active users" value={92410} thousandSeparator diff={12.4} icon={<UsersIcon size={26} />} />
      </Paper>
      <Paper withBorder p="md" radius="md">
        <Stat label="Revenue" value={1340.5} prefix="$" decimalScale={2} fixedDecimalScale thousandSeparator diff={-4.1} icon={<CoinsIcon size={26} />} />
      </Paper>
      <Paper withBorder p="md" radius="md">
        <Stat label="Orders" value={2847} thousandSeparator diff={0.8} icon={<ShoppingCartIcon size={26} />} />
      </Paper>
    </SimpleGrid>
  );
}
```



#### Props

**Stat props**

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| animate | boolean | false | If set, value changes are animated with `RollingNumber` (only applies to numeric values) |
| animationDuration | number | 600 | Animation duration in milliseconds, applied when `animate` is set |
| children | React.ReactNode | - | Custom content, replaces the default composition built from shorthand props |
| color | MantineColor | - | Key of `theme.colors` or any valid CSS color to set the value color |
| decimalScale | number | - | Limits the number of digits displayed after the decimal point |
| decimalSeparator | string | '.' | Character used as a decimal separator |
| diff | number | - | Trend delta. Positive renders an up indicator, negative a down indicator, both colored. With the default formatter a delta that rounds to `0%` is neutral |
| diffFormatter | (diff: number) => ReactNode | - | A function to format the rendered delta. By default the delta is rounded to at most 1 decimal and rendered as a signed percentage, for example `+12.4%` |
| diffLabels | StatDiffLabels | - | Visually hidden direction texts announced after the delta, used to localize the default `increase`, `decrease` and `no change` |
| fixedDecimalScale | boolean | false | If set, trailing zeros are added to match `decimalScale` |
| formatter | (value: string \| number) => ReactNode | - | A function to fully customize the value rendering, overrides `decimalScale`, separators and animation |
| icon | React.ReactNode | - | Leading icon or illustration displayed next to the value |
| label | React.ReactNode | - | Caption displayed above the value |
| loading | boolean | false | If set, a `Skeleton` is displayed in place of the value, the diff is hidden and `aria-busy` is set on the root |
| prefix | React.ReactNode | - | Content rendered before the value (units, icons, currency) |
| size | MantineSize | 'md' | Controls label, value, diff and icon sizes and the gap between the icon and the body |
| suffix | React.ReactNode | - | Content rendered after the value (units, icons, `%`) |
| thousandSeparator | string \| boolean | - | Character used to separate thousands, set to `true` for `,` |
| value | string \| number | - | The metric value. Numbers and numeric strings are formatted with `NumberFormatter`, other strings (`'12k'`, `'N/A'`) are rendered as is |
| withDiffIcon | boolean | true | If set, the up/down arrow is displayed next to the delta |

**Stat.Label props**

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| children | React.ReactNode | - | Label content |

**Stat.Value props**

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| children | React.ReactNode | - | Value content |
| prefix | React.ReactNode | - | Content rendered before the value |
| suffix | React.ReactNode | - | Content rendered after the value |

**Stat.Diff props**

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| children | React.ReactNode | - | Custom content, replaces the formatted delta |
| formatter | (value: number) => ReactNode | - | A function to format the delta text. By default the delta is rounded to at most 1 decimal and rendered as a signed percentage, for example `+12.4%` |
| labels | StatDiffLabels | - | Visually hidden direction texts announced after the delta, used to localize the default `increase`, `decrease` and `no change` |
| value | number | - | Trend delta value. Its sign selects the direction: positive → up, negative → down, zero → neutral. With the default formatter the sign of the rounded delta is used, so a delta that rounds to `0%` is neutral |
| withIcon | boolean | true | If set, the up/down arrow is displayed next to the delta |

**Stat.Icon props**

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| children | React.ReactNode | - | Icon content |

**Stat.Countdown props**

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| color | MantineColor | - | Key of `theme.colors` or any valid CSS color to set the value color |
| format | string | 'HH:mm:ss' | dayjs-style format for the remaining time (`D`, `H`, `m`, `s`, `S`). Larger units roll into the leading token, `S` is tenths, `SS` hundredths and `SSS` milliseconds. Literals can be escaped with square brackets |
| icon | React.ReactNode | - | Leading icon or illustration displayed next to the value |
| label | React.ReactNode | - | Caption displayed above the value |
| onFinish | () => void | - | Called once when the target time is reached |
| onTick | (remainingMs: number) => void | - | Called on every tick with the remaining time in milliseconds |
| prefix | React.ReactNode | - | Content rendered before the value (units, icons, currency) |
| size | MantineSize | 'md' | Controls label, value, diff and icon sizes and the gap between the icon and the body |
| suffix | React.ReactNode | - | Content rendered after the value (units, icons, `%`) |
| value | number \| Date | - | Target time to count down to, a `Date` or a timestamp in milliseconds. Keep it stable between renders (`useState` or `useMemo`), a new target restarts the countdown |


#### Styles API

Stat component supports Styles API. With Styles API, you can customize styles of any inner element. Follow the documentation to learn how to use CSS modules, CSS variables and inline styles to get full control over component styles.

**Stat selectors**

| Selector | Static selector | Description |
|----------|----------------|-------------|
| root | .mantine-Stat-root | Root element |
| icon | .mantine-Stat-icon | Leading icon wrapper |
| body | .mantine-Stat-body | Wrapper around the label, value and diff |
| label | .mantine-Stat-label | Caption displayed above the value |
| value | .mantine-Stat-value | Wrapper around the value, prefix and suffix |
| prefix | .mantine-Stat-prefix | Content rendered before the value |
| suffix | .mantine-Stat-suffix | Content rendered after the value |
| diff | .mantine-Stat-diff | Trend delta element |
| diffIcon | .mantine-Stat-diffIcon | Up/down arrow icon displayed in the diff |

**Stat CSS variables**

| Selector | Variable | Description |
|----------|----------|-------------|
| root | --stat-gap | Controls gap between the icon and the body |
| root | --stat-value-fz | Controls value `font-size` |
| root | --stat-label-fz | Controls label `font-size` |
| root | --stat-diff-fz | Controls diff `font-size` |
| root | --stat-icon-size | Controls icon wrapper width and height |

**Stat data attributes**

| Selector | Attribute | Condition | Value |
|----------|-----------|-----------|-------|
| root | data-loading | `loading` prop is set | - |
| diff | data-direction | - | `up` for positive values, `down` for negative values, `none` for zero (or a delta that rounds to `0%` with the default formatter) |
