# Number Value **Category**: react **URL**: https://ui.darkcode.dev/en/docs/react/components/number-value **Source**: https://raw.githubusercontent.com/DarkCode-Developers/darkcode-ui/refs/heads/main/apps/docs/content/docs/en/react/components/(data-display)/number-value.mdx > A formatted number display with locale-aware rendering for currency, percentages, and compact notation. *** ## Import ```tsx import { NumberValue } from '@darkcode-ui/react'; ``` ## Anatomy Import the NumberValue component and access all parts using dot notation. > The formatted number is always rendered in the `.number-value__value` element. Add > `` and `` to place text around it. ```tsx ``` ### Usage By default, `NumberValue` renders a locale-aware decimal number using `Intl.NumberFormat`. ```tsx import {NumberValue} from "@darkcode-ui/react"; export function NumberValueDefault() { return (
); } ``` ### Compact Use `notation="compact"` to render large numbers in short form (e.g. `1.2K`, `1.2M`). ```tsx import {NumberValue} from "@darkcode-ui/react"; export function NumberValueCompact() { return (
); } ``` ### Currency Set `style="currency"` together with a `currency` code to format monetary values. ```tsx import {NumberValue} from "@darkcode-ui/react"; export function NumberValueCurrency() { return (
); } ``` ### Format Options Pass `formatOptions` to access the full `Intl.NumberFormat` API. It overrides the individual convenience props. ```tsx import {NumberValue} from "@darkcode-ui/react"; export function NumberValueFormatOptions() { return (
); } ``` ### Percent Set `style="percent"` to render a fraction as a percentage. ```tsx import {NumberValue} from "@darkcode-ui/react"; export function NumberValuePercent() { return (
); } ``` ### Sign Display Use `signDisplay` to control when the `+` / `-` sign is shown. ```tsx import {NumberValue} from "@darkcode-ui/react"; export function NumberValueSignDisplay() { return (
); } ``` ### Tabular Nums The value uses tabular figures by default, so digits stay aligned as the number changes. ```tsx "use client"; import {NumberValue} from "@darkcode-ui/react"; import React from "react"; export function NumberValueTabularNums() { const [value, setValue] = React.useState(12500.0); React.useEffect(() => { const id = setInterval(() => { setValue((current) => current + (Math.random() - 0.5) * 480); }, 600); return () => clearInterval(id); }, []); return (
); } ``` ### With Prefix Suffix Use `NumberValue.Prefix` and `NumberValue.Suffix` to add contextual text around the value. ```tsx import {NumberValue} from "@darkcode-ui/react"; export function NumberValueWithPrefixSuffix() { return (
/ 5 ~ ms °F
); } ``` ## Localization `NumberValue` reads the locale from the nearest [`I18nProvider`](https://react-spectrum.adobe.com/react-aria/I18nProvider.html). Wrap your app (or a subtree) to format numbers for a specific locale, or pass the `locale` prop to override it on a single value. ```tsx import {I18nProvider} from 'react-aria-components'; import {NumberValue} from '@darkcode-ui/react'; ``` ## Styling ### Passing Tailwind CSS classes ```tsx import {NumberValue} from '@darkcode-ui/react'; function CustomNumberValue() { return ( USD ); } ``` ### Customizing the component classes To customize the NumberValue component classes, you can use the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .number-value { @apply items-baseline gap-0.5; } .number-value__value { @apply font-semibold tabular-nums; } .number-value__prefix, .number-value__suffix { @apply text-muted; } } ``` DarkCode UI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes The NumberValue component uses these CSS classes ([View source styles](https://github.com/DarkCode-Developers/darkcode-ui/blob/main/packages/styles/components/number-value.css)): #### Base Classes - `.number-value` - Base inline-flex wrapper #### Element Classes - `.number-value__prefix` - Text before the formatted number - `.number-value__value` - The formatted number - `.number-value__suffix` - Text after the formatted number ## API Reference ### NumberValue The root component. Formats and displays a number using locale-aware `Intl.NumberFormat`. | Prop | Type | Default | Description | |------|------|---------|-------------| | `value` | `number` | - | **Required.** The numeric value to format | | `style` | `'decimal' \| 'currency' \| 'percent' \| 'unit'` | `'decimal'` | Formatting style | | `currency` | `string` | - | Currency code (e.g. `"USD"`). Required when `style` is `"currency"` | | `unit` | `string` | - | Unit type (e.g. `"degree"`). Required when `style` is `"unit"` | | `notation` | `'standard' \| 'compact' \| 'scientific' \| 'engineering'` | `'standard'` | Notation style | | `signDisplay` | `'auto' \| 'always' \| 'exceptZero' \| 'never'` | - | Controls when the sign is displayed | | `minimumFractionDigits` | `number` | - | Minimum number of fraction digits | | `maximumFractionDigits` | `number` | - | Maximum number of fraction digits | | `locale` | `string` | - | Override the locale from the nearest I18nProvider | | `formatOptions` | `Intl.NumberFormatOptions` | - | Format options passed directly to the formatter. Overrides individual convenience props | | `children` | `React.ReactNode \| ((formatted: string) => React.ReactNode)` | - | Prefix/Suffix sub-components or a render function receiving the formatted string | Also supports all native `span` HTML attributes except `children` and `style`. ### NumberValue.Prefix Text displayed before the formatted number. | Prop | Type | Default | Description | |------|------|---------|-------------| | `children` | `React.ReactNode` | - | Prefix text | Also supports all native `span` HTML attributes. ### NumberValue.Suffix Text displayed after the formatted number. | Prop | Type | Default | Description | |------|------|---------|-------------| | `children` | `React.ReactNode` | - | Suffix text | Also supports all native `span` HTML attributes.