Pharos
Navegar componentes
← Componentes

NumberInput

MiscExemplo
Um form input para valores numéricos com validação integrada, restrições min/max e controles de step. Use NumberInput para quantidades, medidas, porcentagens e inputs similares.
Importação
import {NumberInput} from '@pharos-ds/core/NumberInput';

Exemplos

Área interativa

size
isDisabled
isIntegerOnly
units
Código
import {NumberInput} from '@pharos-ds/core/NumberInput';

<NumberInput
  size="md"
  isDisabled={false}
  isIntegerOnly={false}
  units="none"
 />

Boas práticas

  • Faça: Defina min, max e step para orientar usuários a valores válidos.
  • Faça: Mostre units (ex.: "%" ou "GB") para que usuários saibam o que o número representa.
  • Evite: Use NumberInput para texto livre que por acaso contém números; use TextInput em vez disso.
  • Evite: Defina isOptional e isRequired no mesmo campo.
  • Evite: Envolva um NumberInput desabilitado em Tooltip para explicar por que está desabilitado; controles desabilitados engolem os eventos de hover que o wrapper precisa. Use a prop disabledMessage em vez disso.

Props

PropTipoPadrãoDescrição
label *string—Texto do label do input (sempre renderizado para acessibilidade).
value *number | null | undefined—Valor atual do input.
onChange *(value: number) => void—Callback disparado quando o valor do input muda (apenas em input válido).
size'sm' | 'md' | 'lg''md'Variante de size.
isLabelHiddenboolean—Oculta visualmente o label (ainda acessível a leitores de tela).
descriptionstring—Texto de description exibido entre o label e o input.
isOptionalboolean—Se o campo é opcional (mutuamente exclusivo com isRequired).
isRequiredboolean—Se o campo é obrigatório (mutuamente exclusivo com isOptional).
isDisabledboolean—Se o input está desabilitado.
disabledMessagestring—Explica por que o input está desabilitado. Com isDisabled, exibe um tooltip no hover/foco via teclado e mantém o input focável via aria-disabled (o campo torna-se read-only). Use isto em vez de envolver um NumberInput desabilitado em Tooltip.
placeholderstring—Texto placeholder.
labelTooltipstring—Texto de tooltip a exibir em um ícone de info no final do label.
startIconIconType—Ícone a exibir no início do input. Veja `pharos docs icons` para nomes semânticos válidos.
labelIconIconType—Ícone a exibir antes do texto do label. Veja `pharos docs icons` para nomes semânticos válidos.
status{type: 'error' | 'warning' | 'success', message?: string}—Status de validação com mensagem opcional.
statusVariant'attached' | 'detached' | 'tooltip''attached'Como a mensagem de status é posicionada em relação ao input. attached sobrepõe diretamente abaixo do input (tratamento com borda); detached flutua abaixo como elemento separado com espaçamento; tooltip oculta a caixa de mensagem e a exibe em um tooltip no ícone de status.
minnumber | null—Valor mínimo permitido.
maxnumber | null—Valor máximo permitido.
stepnumber | null1Incremento de step do input.
unitsstring | null—Texto de units a exibir no final do input (ex.: "%" ou "GB").
isIntegerOnlyboolean—Permite apenas valores inteiros (sem ponto flutuante).
hasClearbooleanfalseExibe um botão de limpar (×) quando o input tem um valor. Quando true, o callback onChange também aceita null para sinalizar que o usuário limpou o input.
htmlNamestring—Atributo HTML name para submissões de formulário.
autoCompletestring—Atributo HTML autocomplete.
widthSizeValue—Largura do campo (número = pixels, string usada como está, ex.: "100%"). Dimensiona o campo inteiro (label, controle e status) para que permaneçam alinhados.
hasAutoFocusboolean—Se deve focar o input ao montar.
onFocus(e: FocusEvent<HTMLInputElement>) => void—Callback disparado quando o input recebe foco.
onBlur(e: FocusEvent<HTMLInputElement>) => void—Callback disparado quando o input perde foco.
onEnter() => void—Callback disparado quando o usuário pressiona a tecla Enter.
Pacote: @pharos-ds/core · Import: @pharos-ds/core/NumberInput
NumberInput · Pharos