Pular para o conteúdo
Formulário

CurrencyInput

/componentes/currency-input.mdmarkdown cru, para quem lê com agent em vez de olho

Valor da cobrança

Vai para o servidor como 248000 centavos.

Com limite

De R$ 10,00 a R$ 5.000,00 por transferência.

Ajuste com sinal

Digite - em qualquer ponto para trocar o sinal.

Tamanhos e estados

Importar
import { CurrencyInput } from '@rivocode/ui'

Quando usar

O campo de dinheiro em reais. O valor entra e sai em centavos inteiros (123456 é R$ 1.234,56), a digitação anda da direita para a esquerda como na maquininha, e o "R$" fica desenhado ao lado, fora do valor.

const [cents, setCents] = useState<number | null>(null)

<Field>
  <FieldLabel>Valor da cobrança</FieldLabel>
  <CurrencyInput value={cents} onValueChange={setCents} />
</Field>

Cada tecla empurra os dígitos para a esquerda: 1 mostra 0,01, 12 mostra 0,12, 123456 mostra 1.234,56. A pontuação sai do Intl.NumberFormat em pt-BR, e o teclado do celular abre no numérico. Campo vazio é null, e não zero: "não digitou" e "digitou zero" são respostas diferentes num formulário, e o zero se digita com a tecla 0.

Guarde os centavos. O servidor recebe inteiro, sem ponto flutuante no meio, e a pontuação é assunto de tela. O campo para em doze dígitos, R$ 9.999.999.999,99, que é onde o inteiro ainda cabe folgado.

Colar

Colar substitui o valor, e o texto colado é lido como a pessoa o escreveria: R$ 1.234,56, 1234,56, 1.234,5 e 1234.56 entram como R$ 1.234,56, e 150 entra como R$ 150,00. O separador de centavos é a vírgula ou o ponto que tiver um ou dois dígitos depois; os outros são milhar. O sinal vem pelo -, antes ou depois do número, ou pelos parênteses da contabilidade: (10,00) é R$ -10,00.

O colado é recusado inteiro, e o valor que estava fica, quando não é só um valor: texto sem número, texto misturado ao número (R$ 10 - desconto 2, Total: R$ 10,00) e valor com mais de doze dígitos. Nada é cortado em silêncio para caber.

Desabilitado, o campo fica fora do formulário, como qualquer campo desabilitado do HTML. O leitor de tela ouve o número e, na descrição, "em reais": o "R$" desenhado ao lado é só visual.

Sinal

Sem allowNegative, o - não entra, nem digitado nem colado. Com ele, o - em qualquer ponto do campo põe o sinal, e um segundo - tira:

<CurrencyInput value={adjustment} onValueChange={setAdjustment} allowNegative />

O teclado numérico do iPhone não tem o sinal, então com allowNegative o campo abre o teclado de texto no web, e o de números e pontuação no nativo.

Limites

min e max são em centavos. Fora deles o campo se marca inválido, com a borda de perigo e aria-invalid, e nada é corrigido sozinho: trocar o valor de dinheiro que a pessoa digitou, sem ela ver, é o pior erro que um campo destes pode cometer. A mensagem que diz o limite é do formulário, como no TimeField. Campo vazio não é inválido por causa de min: obrigatório é outra regra, e também é do formulário.

<CurrencyInput value={cents} onValueChange={setCents} min={1_000} max={500_000} />

No formulário

O forValue do @rivocode/ui/form liga o campo ao React Hook Form: o onValueChange já entrega o número que o schema espera. O campo vazio é null, então o schema aceita null no tipo (.nullable()) e o recusa no refine: sem isso, defaultValues: { amount: null } não compila.

const schema = z.object({
  amount: z
    .number()
    .int()
    .min(100, 'O mínimo é R$ 1,00')
    .nullable()
    .refine((cents) => cents !== null, 'Informe o valor'),
})

const form = useZodForm(schema, { defaultValues: { amount: null } })

<FormField name="amount" label="Valor da cobrança">
  {(field) => <CurrencyInput {...forValue(field)} />}
</FormField>

O forValue repassa a ref e o onBlur: o envio com erro põe o foco no campo, e o useZodForm, que nasce com mode: 'onTouched', confere ao sair dele. No formulário nativo do HTML, sem React Hook Form, o name põe os centavos num campo escondido: o que chega ao servidor é 123456, e não 1.234,56.

Partes

classNames alcança cada nó pelo nome: input e prefix (o "R$"). className veste a raiz, que embrulha os dois.

Quando não usar

  • Quantidade com passo, como parcelas, itens ou dias de prazo, é NumberField: ali o valor anda de um em um pelos botões e pelas setas, e o que importa é o limite, não a pontuação.
  • Dinheiro que precisa de molde junto de outros moldes, na mesma lista de campos gerada por configuração, é MaskedInput com mask="moeda". Ele entrega o cru e o texto pontuado, e o centavo sai por toCents(); não tem sinal, limite nem colagem inteligente.
  • Valor que a tela só mostra é texto formatado, e não campo desabilitado: use currency() numa célula ou no Stat. O currency() recebe reais: o valor deste campo se escreve currency(cents / 100), e sem a divisão a tela mostra cem vezes mais.

iOS e Android

No iOS, com allowNegative, o campo abre o teclado de números e pontuação, porque o teclado numérico do iOS não tem sinal de menos; no Android abre o numérico, que tem o sinal. É o único ponto em que os dois sistemas ficam diferentes, e é limite do teclado, não da peça. O - digitado ou colado põe e tira o sinal do mesmo jeito nos dois.

No React Native

Traduz, com a mesma conta: o valor em centavos, a digitação que anda da direita para a esquerda, o - que põe e tira o sinal e a leitura do texto colado moram num arquivo só, compartilhado pelos dois pacotes. O campo é controlado, como todo o nativo: value e onValueChange são obrigatórios.

O React Native não avisa quando a pessoa cola, então o campo lê a seleção de antes da troca para saber o que entrou por cima. Com allowNegative, o teclado passa a ser o de números e pontuação, que é o que tem o sinal no iPhone. Não há name: formulário escondido não existe no celular.

As partes vestem pelo mesmo classNames do web: input e prefix, este no texto do "R$".

API

PropTipoPadrão
allowNegative

Aceita valor negativo.

booleanfalse
classNames

Classe por parte: `input` e `prefix` (o "R$").

Partial<Record<"input" | "prefix", string>>sem padrão
defaultValue

O valor inicial em centavos, quando o campo controla o proprio estado.

number | nullnull
max

O maior valor aceito, em centavos.

numbersem padrão
min

O menor valor aceito, em centavos.

numbersem padrão
name

Some no formulario nativo com os centavos, e nunca com o texto pontuado.

stringsem padrão
onValueChange

Chamado a cada tecla com os centavos, ou `null` quando o campo esvazia.

((cents: number | null) => void)sem padrão
render

Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente.

ComponentRenderFn<HTMLProps, FieldControlState> | ReactElement<unknown, string | JSXElementConstructor<any>>sem padrão
sizeControlSize | nullsem padrão
value

O valor em centavos inteiros: `123456` e R$ 1.234,56.

number | nullsem padrão

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

@rivocode/ui, 149 peças no catálogo. Esta página é gerada dos mesmos arquivos que alimentam o design system, então ela não envelhece sozinha.

Feito por RivoCode.