Máscaras

Formata enquanto se digita, confere o dígito verificador de documento e esconde dado sensível. Não troca o campo por outro controle: é comportamento sobre o seu <input>, que continua com o name e com o estilo que o projeto já aplica.

Exemplos

Tudo é o mesmo data-tuc-mask com outro formato. O texto de espera sai do gabarito — ninguém escreve 000.000.000-00 à mão.

Como usar

Marque o <input> com o formato, e ele inicializa sozinho no carregamento e a cada htmx:afterSwap. O componente veste a classe .tuc-input no campo e põe o inputmode numérico quando o gabarito não aceita letra, para o celular abrir o teclado de números.

<input name="cpf"      data-tuc-mask="cpf" data-validate="true">
<input name="document" data-tuc-mask="cpf-cnpj">
<input name="phone"    data-tuc-mask="phone">
<input name="amount"   data-tuc-mask="brl">
<input name="expiry"   data-tuc-mask="##/##">

No formulário do Django

class CustomerForm(forms.ModelForm):
    class Meta:
        model = Customer
        fields = ["document", "phone", "credit_limit"]
        widgets = {
            "document": forms.TextInput(attrs={"data-tuc-mask": "cpf-cnpj", "data-validate": "true"}),
            "phone": forms.TextInput(attrs={"data-tuc-mask": "phone"}),
            "credit_limit": forms.TextInput(attrs={"data-tuc-mask": "brl"}),
        }

O campo posta o texto como está na tela: 111.444.777-35, R$ 1.234,50. Limpe no clean_ — a validação do navegador protege a tela, não o servidor.

def clean_document(self):
    return re.sub(r"[^0-9A-Z]", "", self.cleaned_data["document"].upper())

def clean_credit_limit(self):
    text = re.sub(r"[^\d,]", "", self.cleaned_data["credit_limit"])
    return Decimal(text.replace(",", ".")) if text else None

Em JavaScript

const m = new Tucano.Mask('#amount', { format: 'brl' });
m.getRaw();          // '123450' — sem pontuação
m.getNumber();       // 1234.5 — só nos formatos de moeda; nos outros, null
m.setValue('99');    // formata e dispara tucano:change
m.isValid();         // confere o dígito verificador, nos formatos que têm
m.destroy();

document.querySelector('#amount').addEventListener('tucano:change', (e) => {
  e.detail.value;    // 'R$ 1.234,50'
  e.detail.raw;      // '123450'
  e.detail.number;   // 1234.5
});

Os utilitários por trás da máscara também saem prontos, para validar ou formatar fora de um campo:

Tucano.mask.validateCPF('111.444.777-35')              // true
Tucano.mask.validateCNPJ('11.222.333/0001-81')         // true
Tucano.mask.validateCpfCnpj('123.456.789-01')          // false
Tucano.mask.format('12345678901', 'cpf')               // '123.456.789-01'
Tucano.mask.applyCurrency('12345', { currency: 'BRL' }) // 'R$ 123,45'
Tucano.mask.maskEmail('contato@empresa.com.br')        // 'c••••••@empresa.com.br'

Validação

Com data-validate, o dígito verificador é conferido ao sair do campo. Reprovado, o campo recebe aria-invalid="true" e setCustomValidity, e o próprio navegador barra o envio — sem uma linha no projeto.

E o acerto aparece na hora: assim que o valor fica completo e certo, o campo fica verde, sem esperar sair dele. O erro espera — digitando, um CPF pela metade nunca fica vermelho; ele só é acusado ao sair do campo, e some de novo quando a pessoa volta a corrigir. O verde é o atributo data-tuc-valid, que o CSS pinta com --tuc-success.

Valem cpf, cnpj, cnpj-numeric e cpf-cnpj; os outros formatos não têm dígito para conferir. Campo vazio passa: obrigatoriedade é do required. Enquanto se digita o erro some, e ao voltar ao campo também — inclusive a marca que veio do servidor, porque a pessoa está corrigindo.

<input name="cpf" data-tuc-mask="cpf" data-validate="true" data-error-text="Confira o CPF">

Campo sensível

O data-tuc-reveal põe um olho para mostrar e ocultar. Campo que já chega preenchido nasce oculto, com só o fim à mostra; campo vazio nasce visível, porque quem digita precisa ver. A senha é a exceção: nasce sempre oculta.

<input name="cpf" value="111.444.777-35" data-tuc-mask="cpf" data-tuc-reveal>
<input name="card" data-tuc-mask="card" data-tuc-reveal data-reveal-visible="4">
<input name="api_key" data-tuc-reveal="all">
<input type="email" name="email" data-tuc-reveal>
<input type="password" name="password" data-tuc-reveal>

O que o formulário posta não muda por estar oculto. Fora do type="password", o name passa para um <input type="hidden"> com o valor real, e o campo visível mostra os pontos. Enquanto oculto, o campo é só leitura: digitar em cima dos pontos escreveria por cima do valor sem a pessoa perceber. Os separadores continuam no lugar, para a forma seguir reconhecível: •••.•••.•••-35.

Texto solto na tela

Nem todo dado sensível está num campo: o CPF na tela de um cliente, o cartão numa célula de tabela, a chave de API num parágrafo. O data-tuc-reveal vale em qualquer elemento, nos mesmos modos, e junto com data-tuc-format. O texto nasce escondido, com o olho ao lado.

<td><span data-tuc-format="cpf" data-tuc-reveal>{{ customer.cpf }}</span></td>
<td><span data-tuc-reveal data-reveal-visible="4">{{ card.number }}</span></td>
<p>Chave de API: <span data-tuc-reveal="all">{{ api_key }}</span></p>

Só para exibir

Para o que já vem do banco e não se edita, não precisa de campo: data-tuc-format formata o texto do próprio elemento.

<span data-tuc-format="cpf">{{ customer.cpf }}</span>
<span data-tuc-format="brl">{{ order.total }}</span>
<span data-tuc-format="phone" data-value="{{ customer.phone }}"></span>

Aceita cpf, cnpj, cpf-cnpj, phone, mobile, cep, card, real, currency e gabarito livre, com data-decimals e data-currency na moeda. O valor sai do texto do elemento ou de data-value. Moeda lê o ponto decimal do banco (1234.5) e também a vírgula. Conteúdo que não preenche o gabarito volta como veio, em vez de sair pela metade e parecer corrompido. Para HTML inserido por outro caminho que não o HTMX, Tucano.autoFormat(element).

Teclado e acessibilidade

A máscara usa o teclado do navegador, sem atalho próprio. O que ela cuida é de o cursor não se perder.

O olho anuncia "Mostrar" ou "Ocultar" e o estado por aria-pressed. Ao mostrar, o foco vai para o campo. Reprovado na validação, o campo fica com aria-invalid="true", que o leitor de tela lê como inválido.

API

Gerada do código a cada build — se algo não está aqui, não existe.

Opções