NumberValue

Formata e mostra um número em pt-BR: moeda, porcentagem, compacto ou sinal.

O NumberValue mostra um número já formatado pelo Intl.NumberFormat do locale atual: saldo de Créditos, taxa de entrega, contagem de Pedidos. Ele lê o idioma do I18nProvider pt-BR do Admin. Para valor editável use NumberField; para a variação de uma métrica, TrendChip.

import { NumberValue } from "@rastreio-x/ui";

Padrão

value é obrigatório. Os separadores seguem o locale: 1.284.

1.284

Moeda

style="currency" com currency="BRL". A fachada resolve a formatação (R$ 1.234,50).

R$ 1.234,50R$ 0,35por Crédito

Porcentagem

style="percent" multiplica por 100; maximumFractionDigits limita as casas e signDisplay="exceptZero" mostra o sinal.

98,5%-2%

Compacto

notation="compact" abrevia números grandes (1,2 mil, 1,2 mi).

12341,2 mil

4567846 mil

12345671,2 mi

Prefixo e sufixo

NumberValue.Prefix e NumberValue.Suffix carregam a unidade ou o contexto, com estilo próprio.

182CréditosFaltam3dias

Algarismos tabulares

Em colunas de valores, alinhe à direita: o NumberValue usa algarismos tabulares e as casas decimais ficam alinhadas.

R$ 1.234,50R$ 71,90R$ 15.654,00R$ 9,99

Saldo de Créditos

Como no KPI da tela de Créditos, em um Widget.

Anatomia

NumberValue
├── NumberValue.Prefix
└── NumberValue.Suffix

NumberValue: o span com o número formatado.
NumberValue.Prefix e NumberValue.Suffix: texto antes e depois.

Propriedades

NumberValue:

NumberValue
Prop	Tipo	Padrão	Descrição
`value`*	`number`	-	Valor atual (controlado). Em campos de formulário, é o valor enviado.
`children`	`React.ReactNode \| ((formatted: string) => React.ReactNode)`	-	Conteúdo do componente.
`className`	`string`	-	Classes CSS aplicadas ao elemento.
`currency`	`string`	-	Currency code (e.g. "USD", "EUR"). Required when style is "currency".
`formatOptions`	`NumberFormatOptions`	-	Formato de exibição do valor (`Intl.NumberFormatOptions`).
`locale`	`string`	-	Código de idioma e região (por exemplo, `pt-BR`).
`maximumFractionDigits`	`number`	-	Maximum number of fraction digits.
`minimumFractionDigits`	`number`	-	Minimum number of fraction digits.
`notation`	`'compact' \| 'engineering' \| 'scientific' \| 'standard'`	`"standard"`	Notation style.
`signDisplay`	`'auto' \| 'always' \| 'exceptZero' \| 'never'`	-	Controls when the sign is displayed.
`style`	`'decimal' \| 'currency' \| 'percent' \| 'unit'`	`"decimal"`	Estilos em linha aplicados ao elemento.
`unit`	`string`	-	Unit type (e.g. "degree", "celsius"). Required when style is "unit".

Animações

Sem movimento
indicativo

O NumberValue não anima nem faz contagem progressiva. O número troca direto quando value muda.

Acessibilidade

É texto: o leitor de tela lê o valor formatado ("R$ 1.234,50"), sem depender de cor.
Dê contexto ao lado (rótulo "Saldo", título do Widget): o número sozinho não diz o que mede.
Sufixos decorativos curtos ("Créditos") entram no texto lido; se forem só visuais, marque aria-hidden.
Não use cor para indicar positivo ou negativo sem sinal; use signDisplay.

Boas práticas

Faça

Formatar sempre pelo locale (pt-BR) e dar a unidade perto do número.

Evite

Concatenar “R$” e toFixed à mão, ou alinhar colunas de valores à esquerda.

Use maximumFractionDigits={0} para contagens inteiras.
Para números grandes em KPIs, o font-heading com text-4xl ou text-5xl segue o padrão do Admin.
Para editar um número, use NumberField.

Relacionados

TrendChip para a variação do KPI.
NumberField para entrada de números.
Widget como contêiner do KPI.
I18nProvider para o idioma.