# Number Value

A large number with its change beside it: caret up or down, green or red.

- Category: Data & Tables
- Page: https://wunderui.com/components/number-value
- Tier: Core and Pro

## Install

Number Value ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { NumberValue } from "@wunderui/react"
```

## Minimal usage

Then use it:

```tsx
import { NumberValue } from "@/components/ui/number-value"

export function Revenue() {
  return <NumberValue value="$48,200" delta="+4.2%" trend="up" />
}
```

Expected result: You see $48,200 in bold with a green caret pointing up and +4.2% beside it.

## When to use

### Use Number Value for

- A headline figure with its change in a KPI card, a dashboard header or a summary row
- A metric where you want the change to read in the same line as the number
- Figures with units, such as a price, a count of users or a duration

### Use something else

- [Trend Chip](https://wunderui.com/components/trend-chip) for only the change, as a small pill next to your own number
- [Meter](https://wunderui.com/components/meter) for a figure measured against a limit, such as storage used
- [Badge](https://wunderui.com/components/badge) for a short status or count in a label

## Behavior

What the component renders and how it reads.

- **Static:** NumberValue is not interactive: no focus, no hover state, no handlers. Wrap it in your own link or button where the figure should open something.
- **Change appears with both props:** The caret and label render only when both delta and trend are set. With neither, you get the value alone, the Trend none variant in Figma.
- **Direction and colour:** The trend turns the caret up or down, and the good flag picks the colour: success green when true, error red when false. It matches the Sentiment axis in Figma.
- **Alignment:** The row aligns to the bottom of the figure, and the change label sits on its baseline with 4 px of padding below, so caret and label read as one line with the number.
- **Reading:** A screen reader reads the value and then the label as plain text, for example $48,200 +4.2%, and the caret is hidden. Put the period in visible text next to the component.
- **Numbers:** The digits are tabular, so an updating value keeps its width per digit. Use the English comma format in the string you pass, such as 1,284.
- **Motion:** None. The figure and the change appear as they are and do not animate when they change.
- **Reduced motion:** There is no motion, so reduced motion changes nothing.

## Anatomy

- `NumberValue`: A flex row with the figure and, beside it, the change. It is not interactive and holds no state: you pass the finished strings.
- `Value`: The figure at 24 px bold with tabular digits, so a changing number does not shake the layout. It shows your value string as you pass it, with its unit.
- `Caret`: A filled triangle pointing up or down with the trend. It is decorative and appears only when both the delta and the trend are set.
- `Change label`: The delta text at 12 px semibold, on the baseline of the figure. Green by default, red when the trend is marked not good.

## Best practices

### Do

- Pass the value as a finished string with its unit: $48,200 or 1,284 users. The component does not format numbers, so the unit has to come with it.
- Keep direction and meaning apart. The trend sets which way the caret points and the good flag sets the colour: falling churn is down and good, a rising ticket count is up and not good.
- Give the delta its sign and unit, such as +4.2% or -0.4%. The caret is decorative, so the text has to carry the direction for people who cannot see it.
- Put a label above the value, such as Revenue, and the period below it. NumberValue shows the figure and its change only.

### Don't

- Don't pass a delta without a trend, or a trend without a delta. The change shows only when both are set.
- Don't rely on colour alone. Green and red do not reach everyone, so the sign in the label and the direction of the caret say the same thing.
- Don't use it for a chart or a long list of figures. It is one headline number; for a pill with a percentage use Trend Chip.

## API reference

### NumberValue

| Prop | Type | Default | Description |
|---|---|---|---|
| value* | string |  | The figure as a finished string with its unit, for example `$48,200` or `1,284 users`. It is not formatted for you. |
| className | string |  | Extra classes for the row, for example a different gap or `justify-center`. |
| delta | string |  | The change label beside the figure, for example `+4.2%` or `+$1,204.60`. It shows only together with `trend`. |
| trend | "up" \| "down" |  | Which way the caret points. Leave it out for a figure without a change. |
| trendGood | boolean | true | Whether the change is good, which makes it green, or bad, which makes it red. It does not change the direction of the caret. Defaults to true. |

## Examples

### Value: currency, count, percentage or duration

### Change: percentage, amount, both or a comparison

## In context

### KPI cards: four figures with their change

A fall in churn is good, so it points down and stays green. A rise in open tickets points up and is red.

### Store overview: the same figures for the period you choose

The three figures change with the period. The refund rate rises in the shortest period, which is bad, and falls in the longer ones, which is good.

## For AI agents

`get_component("number-value")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
