Input OTP
Campo de código de uso único (OTP) com slots individuais, avanço automático de foco e suporte a colar.
O mk-input-otp renderiza uma fileira de slots de caractere único para captura de códigos OTP (One-Time Password) ou PINs. Cada slot corresponde a um dígito do código, guiando visualmente o usuário sobre quantos caracteres são esperados. Ao digitar em um slot, o foco avança automaticamente para o próximo, tornando o preenchimento mais ágil e reduzindo erros. Suporta avanço automático de foco, navegação por teclado (ArrowLeft / ArrowRight / Backspace) e distribuição de texto colado entre os slots.
Integração com Angular Forms
Para usar com ngModel ou FormControl, importe MkInputOtpModule em vez de MkInputOtpComponent. Veja Formulários com Angular.
Quando usar
Use o mk-input-otp quando o fluxo exigir a entrada de um código de comprimento fixo e conhecido.
- O fluxo exigir verificação por código enviado via SMS, e-mail ou aplicativo autenticador.
- O código tiver comprimento fixo e conhecido (4 ou 6 dígitos).
- O código tiver comprimento variável — use um campo de texto comum.
- A entrada não for de verificação pontual, mas sim de dados numéricos contínuos.
Anatomia
| # | Parte | Obrigatório? | Função |
|---|---|---|---|
| 1 | Rótulo | Não | Instrução acima do campo — ex.: "Digite o código recebido". |
| 2 | Caixas de dígito | Sim | Uma caixa por caractere esperado. O foco avança automaticamente a cada entrada. |
| 3 | Texto de suporte | Não | Instrução adicional ou mensagem de erro abaixo das caixas. |
Estados
A tabela abaixo descreve os estados visuais possíveis do componente.
| Estado | Quando aparece | O que muda visualmente |
|---|---|---|
| Habilitado | Campo disponível, não tocado | Caixas vazias com borda neutra |
| Hover | Cursor sobre o campo | Borda com leve destaque |
| Ativo | Campo com foco | Caixa ativa com borda destacada |
| Focado | Cursor de texto visível | Caret piscando na caixa ativa |
| Preenchido | Todas as caixas com valor | Dígitos visíveis em todas as caixas |
| Sucesso | Código verificado com sucesso | Indicador visual positivo (verde) |
| Erro preenchido | Código incorreto | Borda vermelha, mensagem de erro |
| Erro vazio | Tentativa sem preenchimento | Borda vermelha, mensagem de erro |
| Desabilitado | Campo indisponível | Opacidade reduzida, sem interação |
Erro
<MkInputOtp label="Código inválido" isError /><mk-input-otp label="Código inválido" is-error></mk-input-otp>Sucesso
<MkInputOtp label="Código verificado" isSuccess /><mk-input-otp label="Código verificado" is-success></mk-input-otp>Desabilitado
<MkInputOtp label="Desabilitado" disabled /><mk-input-otp label="Desabilitado" disabled></mk-input-otp>Padrão
import { MkInputOtp } from '@db1/makuco-ui-react';
<MkInputOtp label="Código de verificação" /><mk-input-otp label="Código de verificação"></mk-input-otp>Comprimento
Use length para definir o número de slots. O padrão é 6. Para códigos curtos como PINs e confirmações simples, use length={4}; para códigos padrão de autenticação de dois fatores (TOTP/HOTP), use length={6}.
<MkInputOtp label="PIN de 4 dígitos" length={4} />
<MkInputOtp label="Código de 8 caracteres" length={8} /><mk-input-otp label="PIN de 4 dígitos" [length]="4"></mk-input-otp>
<mk-input-otp label="Código de 8 caracteres" [length]="8"></mk-input-otp>Tipo
type="numeric" restringe a entrada a dígitos e exibe o teclado numérico no mobile. type="text" aceita qualquer caractere.
<MkInputOtp label="Numérico" type="numeric" />
<MkInputOtp label="Alfanumérico" type="text" /><mk-input-otp label="Numérico" type="numeric"></mk-input-otp>
<mk-input-otp label="Alfanumérico" type="text"></mk-input-otp>Separador
Use separator para exibir um traço visual no meio dos slots. Disponível apenas quando length é par.
<MkInputOtp label="Código com separador" separator /><mk-input-otp label="Código com separador" separator></mk-input-otp>Texto de suporte
<MkInputOtp label="Código SMS" supportText="Enviamos um código para o seu celular" /><mk-input-otp label="Código SMS" support-text="Enviamos um código para o seu celular"></mk-input-otp>Comportamento
O mk-input-otp avança o foco automaticamente para o próximo slot a cada caractere digitado válido. Ao pressionar Backspace em um slot vazio, o foco retorna ao slot anterior e o caractere ali presente é apagado. As teclas ArrowLeft e ArrowRight permitem navegar entre os slots sem apagar conteúdo.
Quando o usuário cola texto, os caracteres são distribuídos sequencialmente entre os slots a partir do slot com foco atual. Caracteres além do comprimento configurado são descartados silenciosamente.
Ao preencher o último slot, o evento mkComplete é emitido com o valor completo, permitindo que a aplicação dispare a verificação do código imediatamente, sem necessidade de um botão de confirmação explícito.
Composição
O mk-input-otp é concebido para uso standalone em formulários de verificação. Pode ser combinado com um botão de reenvio de código abaixo do campo para cobrir o fluxo completo de autenticação — nesse caso, certifique-se de que o botão de reenvio seja acessível por teclado e esteja claramente identificado.
Em fluxos de autenticação de dois fatores, posicione o campo logo após a instrução que informa ao usuário onde encontrar o código (ex.: "Verifique seu SMS"). Evite adicionar outros campos de entrada na mesma tela para reduzir a carga cognitiva.
Props
| Prop | Tipo | Padrão | Descrição |
|---|---|---|---|
label | string | — | Texto do rótulo exibido acima dos slots. |
length | number | 6 | Número de slots a renderizar. |
type | "numeric" \| "text" | "numeric" | numeric restringe a dígitos e exibe teclado numérico mobile; text aceita qualquer caractere. |
value | string | — | Valor controlado do OTP. Caracteres extras são truncados ao length. |
separator | boolean | false | Exibe separador visual entre as duas metades. Requer length par. |
isError | boolean | false | Ativa o estado de erro em todos os slots e exibe a mensagem i18n de erro. |
isSuccess | boolean | false | Ativa o estado de sucesso em todos os slots e exibe a mensagem i18n de sucesso. |
disabled | boolean | false | Desabilita todos os slots, impedindo qualquer interação. |
supportText | string | — | Texto auxiliar exibido abaixo dos slots quando não há estado de erro ou sucesso. |
locale | string | — | Tag BCP 47 para resolver mensagens i18n. Recai para lang do ancestral e depois pt-BR. |
Eventos
| Evento | Payload | Descrição |
|---|---|---|
mkChange | string | Emitido sempre que o valor muda, com o valor concatenado atual dos slots. |
mkComplete | string | Emitido quando todos os slots estão preenchidos, com o valor final. |
Acessibilidade
- O primeiro slot recebe
autoComplete="one-time-code"para facilitar o preenchimento automático de códigos SMS. - Navegação por teclado: ArrowLeft / ArrowRight movem o foco entre slots; Backspace apaga o slot atual e volta ao anterior.
- Ao colar texto, os caracteres são distribuídos automaticamente entre os slots a partir do slot com foco.
delegatesFocus: truegarante que o foco seja delegado ao primeiro slot disponível ao clicar no host.
Agrupamento: as caixas individuais devem ser agrupadas com role="group" e aria-label descrevendo o propósito (ex.: "Código de verificação").
Avanço automático: o avanço de foco ao digitar melhora a experiência para a maioria dos usuários, mas deve ser implementado com cuidado para não prejudicar usuários de tecnologia assistiva — garanta que o foco seja movido via JavaScript de forma acessível.
Mensagem de erro: associe mensagens de erro ao grupo via aria-describedby para que leitores de tela as anunciem junto ao campo.
Reenvio de código: se houver uma opção de reenviar o código, ela deve ser acessível por teclado e identificada claramente.