Number Field

Campo numérico com botões de incremento e decremento embutidos, integrado nativamente a formulários.

O mk-number-field captura valores numéricos inteiros. Reaproveita a estrutura e os estados visuais do mk-input quase integralmente, com dois botões de step embutidos no próprio campo — decremento à esquerda, incremento à direita — separados por divisores verticais. A digitação aceita estritamente dígitos: letras, acentos e símbolos são bloqueados.

Quando usar

Use mk-number-field para capturar quantidades, contagens ou limites numéricos simples.

Use quando:

O dado for um número inteiro (quantidade, idade, limite, quota).
O usuário se beneficiar de ajustes finos via botões +/-, além da digitação direta.

Prefira uma alternativa quando:

O valor precisar de formatação de moeda ou casas decimais — use mk-input com mask="brl" ou mask="number".
O dado não for estritamente numérico — use mk-input.

Padrão

import { MkNumberField } from '@db1/makuco-ui-react';

<MkNumberField label="Quantidade" placeholder="0" />

<mk-number-field label="Quantidade" placeholder="0"></mk-number-field>

Limites (min/max)

Use min e max para restringir o intervalo aceito. Os botões de step ficam disabled automaticamente ao atingir cada limite.

<MkNumberField label="Quantidade" min={1} max={10} value={1} />

<mk-number-field label="Quantidade" [min]="1" [max]="10" [value]="1"></mk-number-field>

Passo (step)

Use step para controlar o incremento/decremento aplicado pelos botões de step e pelas setas ↑/↓ do teclado.

<MkNumberField label="Quantidade" step={5} value={10} />

<mk-number-field label="Quantidade" [step]="5" [value]="10"></mk-number-field>

Texto de suporte

<MkNumberField label="Quantidade" supportText="Selecione entre 1 e 99 unidades" />

<mk-number-field
  label="Quantidade"
  support-text="Selecione entre 1 e 99 unidades"
></mk-number-field>

Estado de erro

<MkNumberField label="Quantidade" errorMessage="Este campo é obrigatório" />

<mk-number-field label="Quantidade" error-message="Este campo é obrigatório"></mk-number-field>

Obrigatório

<MkNumberField label="Quantidade" required />

<mk-number-field label="Quantidade" required></mk-number-field>

Desabilitado e somente leitura

<MkNumberField label="Desabilitado" value={1} disabled />
<MkNumberField label="Somente leitura" value={1} readonly />

<mk-number-field label="Desabilitado" [value]="1" [disabled]="true"></mk-number-field>
<mk-number-field label="Somente leitura" [value]="1" [readonly]="true"></mk-number-field>

Formulários

O mk-number-field é form-associated e integra com <form> nativo via name. A tecla Enter aciona o submit do formulário pai.

<form onSubmit={handleSubmit}>
  <MkNumberField label="Quantidade" name="quantidade" min={1} required />
  <MkButton type="submit">Enviar</MkButton>
</form>

<form (ngSubmit)="handleSubmit()">
  <mk-number-field label="Quantidade" name="quantidade" [min]="1" required></mk-number-field>
  <mk-button type="submit">Enviar</mk-button>
</form>

Comportamento

O usuário digita diretamente no campo — apenas dígitos são aceitos, letras, acentos e símbolos são ignorados na digitação. Os botões de decremento e incremento aplicam step a cada clique e desabilitam automaticamente ao atingir min/max. As setas ↑/↓ do teclado fazem o mesmo enquanto o campo está focado.

mkInput é emitido a cada alteração; mkChange é emitido quando o valor muda de fato (no evento nativo change, ao perder o foco) ou imediatamente após um clique num botão de step.

Autofill do navegador

Defina autocomplete com um token do HTML para habilitar o autofill do navegador.

<MkNumberField label="Número" name="address-line2" autocomplete="address-line2" />

<mk-number-field label="Número" name="address-line2" autocomplete="address-line2"></mk-number-field>

Props — mk-number-field

Prop	Tipo	Padrão	Descrição
`label`	`string`	—	Texto do rótulo exibido acima do campo. Quando omitido, o rótulo não é renderizado.
`name`	`string`	—	Atributo `name` para envio em formulários.
`value`	`number`	—	Valor numérico controlado. Prop mutável.
`min`	`number`	—	Valor mínimo permitido. Desabilita o botão de decremento ao ser atingido.
`max`	`number`	—	Valor máximo permitido. Desabilita o botão de incremento ao ser atingido.
`step`	`number`	`1`	Incremento/decremento aplicado pelos botões de step e pelas setas `↑`/`↓`.
`placeholder`	`string`	—	Texto exibido quando o campo está vazio.
`supportText`	`string`	—	Texto auxiliar abaixo do campo, visível quando não há erro.
`helperText`	`string`	—	Texto exibido no ícone de ajuda ao lado do rótulo. Quando omitido, o ícone não é exibido.
`errorMessage`	`string`	—	Mensagem de erro. Quando definida, ativa o estado inválido.
`disabled`	`boolean`	`false`	Desabilita o campo e os dois botões de step.
`readonly`	`boolean`	`false`	Torna o campo somente leitura; desabilita os botões de step.
`required`	`boolean`	`false`	Marca o campo como obrigatório com asterisco no rótulo.
`requiredMessage`	`string`	i18n	Mensagem personalizada para a validação nativa quando `required` e vazio.
`locale`	`string`	—	Tag BCP 47 usada para resolver os rótulos i18n dos botões de step. Recai para `lang` do ancestral, depois `pt-BR`.
`autocomplete`	`string`	—	Token `autocomplete` do HTML repassado ao input nativo, para habilitar o autofill do navegador.

Eventos

Evento	Payload	Descrição
`mkInput`	`number \| null`	Emitido a cada alteração — digitação, clique num botão de step, ou setas `↑`/`↓`.
`mkChange`	`number \| null`	Emitido quando o valor muda de fato e o campo perde o foco, ou imediatamente após clique num botão de step.
`mkFocus`	`void`	Emitido quando o campo recebe foco.
`mkBlur`	`void`	Emitido quando o campo perde foco.

Acessibilidade

Usa <input> nativo internamente (inputMode="numeric") — foco e navegação por teclado estão inclusos.
Os botões de decremento e incremento são <button> nativos com aria-label traduzido ("Diminuir"/"Aumentar" conforme locale); os ícones internos são aria-hidden.
aria-invalid="true" aplicado automaticamente quando errorMessage está definida.
aria-describedby aponta para o texto de suporte ou mensagem de erro.
Com delegatesFocus: true, o foco é delegado ao <input> interno ao clicar no host.

Teclado:

Tecla	Comportamento
`Tab`	Percorre decremento → input → incremento, na ordem natural do DOM.
`↑`	Incrementa o valor em `step` com o input focado.
`↓`	Decrementa o valor em `step` com o input focado.
`Enter`/`Espaço`	Ativa o botão de step focado (comportamento nativo de `<button>`).

Number Field

On this page