NumberField

Campo numérico com botões de incremento, formatação e limites.

O NumberField recebe um número com validação de limites e formatação por locale, como o prazo de uma rota ou o frete. Para escolher aproximadamente com o dedo, use Slider; os dois combinam bem lado a lado.

import { Label, NumberField } from "@rastreio-x/ui";

Padrão

Informe minValue e maxValue quando existirem limites reais. O grupo reúne os botões e o campo.

Prazo Total (dias)

Passo e formato

step define o incremento; formatOptions aceita opções de Intl.NumberFormat, como moeda em reais.

Ajuste (passo de 5)

Soma de 5 em 5.

Valor do Frete

Estados

Desabilitado e inválido. A mensagem de erro cita o intervalo permitido.

Desabilitado

Prazo Total (dias)

Use um valor entre 25 e 40 dias.

Anatomia

NumberField
├── NumberField.DecrementButton
├── NumberField.Group
├── NumberField.IncrementButton
└── NumberField.Input

NumberField.Group: o conjunto de campo e botões.
NumberField.DecrementButton e NumberField.IncrementButton: subtrai e soma um step.
NumberField.Input: o campo editável.

Propriedades

Raiz (NumberField):

NumberField
Prop	Tipo	Padrão	Descrição
`aria-label`	`string`	-	Nome acessível, lido por leitores de tela quando não há rótulo visível.
`autoFocus`	`boolean`	-	Foca o elemento ao renderizar.
`children`	`ChildrenOrFunction<NumberFieldRenderProps>`	-	Conteúdo do componente.
`className`	`ClassNameOrFunction<NumberFieldRenderProps>`	`'react-aria-NumberField'`	Classes CSS aplicadas ao elemento.
`commitBehavior`	`'validate' \| 'snap'`	`'snap'`	Ao sair do campo: `validate` valida e mostra o erro; `snap` ajusta ao valor válido mais próximo.
`decrementAriaLabel`	`string`	-	Rótulo acessível do botão de diminuir.
`defaultValue`	`number`	-	Valor inicial, para uso não controlado.
`form`	`string`	-	Id do `<form>` ao qual o elemento está associado.
`formatOptions`	`Intl.NumberFormatOptions`	-	Formato de exibição do valor (`Intl.NumberFormatOptions`).
`fullWidth`	`boolean`	-	Ocupa toda a largura disponível.
`id`	`string`	-	Identificador único do elemento.
`incrementAriaLabel`	`string`	-	Rótulo acessível do botão de aumentar.
`isDisabled`	`boolean`	-	Desabilita o componente: sem foco, clique nem envio.
`isInvalid`	`boolean`	-	Marca o valor como inválido e mostra o estado de erro.
`isReadOnly`	`boolean`	-	Permite selecionar e copiar o valor, mas não alterá-lo.
`isRequired`	`boolean`	-	Exige um valor antes de enviar o formulário.
`isWheelDisabled`	`boolean`	-	Desativa a alteração do valor pela roda do mouse.
`maxValue`	`number`	-	Valor máximo.
`minValue`	`number`	-	Valor mínimo.
`name`	`string`	-	Nome do campo enviado com o formulário.
`onChange`	`((value: number) => void)`	-	Chamada quando o valor ou a seleção muda.
`render`	`DOMRenderFunction<'div', NumberFieldRenderProps>`	-	Troca o elemento DOM padrão por outro, mantendo o comportamento e as props do componente.
`step`	`number`	-	Passo entre valores consecutivos.
`style`	`StyleOrFunction<NumberFieldRenderProps>`	-	Estilos em linha aplicados ao elemento.
`validate`	`((value: number) => ValidationError \| true \| null \| undefined)`	-	Função de validação: devolve a mensagem de erro, ou `true` ou `null` quando o valor é válido.
`validationBehavior`	`'native' \| 'aria'`	`'native'`	Como validar: `native` usa a validação do navegador; `aria` só marca o estado e anuncia o erro.
`value`	`number`	-	Valor atual (controlado). Em campos de formulário, é o valor enviado.
`variant`	`'primary' \| 'secondary'`	-	Estilo: `primary` (com sombra suave) ou `secondary` (sem sombra, para uso dentro de cartões).

Campo (NumberField.Input):

NumberField.Input
Prop	Tipo	Padrão	Descrição
`children`	`React.ReactNode`	-	Conteúdo do componente.
`className`	`ClassNameOrFunction<InputRenderProps>`	`'react-aria-Input'`	Classes CSS aplicadas ao elemento.
`placeholder`	`string`	-	Texto de apoio exibido quando o campo está vazio.
`render`	`DOMRenderFunction<'input', InputRenderProps>`	-	Troca o elemento DOM padrão por outro, mantendo o comportamento e as props do componente.
`style`	`StyleOrFunction<InputRenderProps>`	-	Estilos em linha aplicados ao elemento.

Animações

CSS
indicativo

Sem animação própria além da troca de cor no hover e no foco dos botões. A folha global da fachada reduz as transições com prefers-reduced-motion.

Acessibilidade

Papel spinbutton com aria-valuemin, aria-valuemax e aria-valuenow.
Setas para cima e para baixo incrementam; Page Up e Page Down saltam; Home e End vão aos limites.
Os botões de incremento têm nome acessível localizado (pelo I18nProvider pt-BR).
Número digitado respeita o formato do locale (vírgula decimal em pt-BR).

Boas práticas

Faça

Limites reais, unidade no rótulo e erro que cita o intervalo: Use um valor entre 25 e 40 dias.

Evite

Campo numérico sem unidade, ou limites que só aparecem depois do erro.

Mostre a unidade no rótulo ou no formato (dias, R$).
Ofereça Slider quando a precisão não for crítica.
Para códigos e identificadores (CEP, telefone), use TextField com inputMode.

Relacionados

Slider para ajustar visualmente a mesma grandeza.
TextField para texto e identificadores.
Select para escolher entre valores predefinidos.