Number Value
ProOne headline figure with its change beside it: a caret that points up or down, in green or red.
Playground
Installation
Number Value comes with WunderUI Core and Pro, in the package from your plan. See the plans.
Then import what you need:
import { NumberValue } from "@wunderui/react"Then use it:
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 for
- Trend Chip for only the change, as a small pill next to your own number
- Meter for a figure measured against a limit, such as storage used
- Badge for a short status or count in a label
Value
The value is a finished string, so the unit comes with it: $48,200, 1,284 users, 4m 12s. The component does not format numbers.
Change
The change label is any string. Include its sign, because the caret is decorative and the text has to carry the direction.
Behavior and motion
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
The figure shows the full form with a change. Without a delta and a trend only the value remains.
- data-slot="number-value"
A flex row with the figure and, beside it, the change. It is not interactive and holds no state: you pass the finished strings.
- 1
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.
- 2Optional
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.
- 3Optional
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.
- Do
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.
- Do
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.
- Do
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
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
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
One table. NumberValue is a plain component, so this table lists every prop.
A flex row with the figure and, beside it, the change. It is not interactive and holds no state: you pass the finished strings.
| Prop | Type | Default | Description |
|---|---|---|---|
| value required | string | — | The figure as a finished string with its unit, for example or . It is not formatted for you. |
| delta | string | — | The change label beside the figure, for example or . It shows only together with . |
| 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. |
| className | string | — | Extra classes for the row, for example a different gap or . |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("number-value")The full library index for assistants is at /llms.txt.