Masks

Formats as you type, verifies the check digit of documents and hides sensitive data. It doesn't replace the field with another control: it's behavior on top of your <input>, which keeps its name and the styling the project already applies.

Examples

It's all the same data-tuc-mask with another format. The placeholder text comes from the pattern — nobody writes 000.000.000-00 by hand. The named formats follow Brazilian documents and conventions; the free pattern works for anything else.

How to use

Mark the <input> with the format, and it initializes by itself on load and on every htmx:afterSwap. The component puts the .tuc-input class on the field and sets a numeric inputmode when the pattern doesn't accept letters, so phones open the number keypad.

<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="##/##">

In the Django form

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"}),
        }

The field posts the text as it appears on screen: 111.444.777-35, R$ 1.234,50. Clean it in clean_ — browser validation protects the screen, not the server.

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

In JavaScript

const m = new Tucano.Mask('#amount', { format: 'brl' });
m.getRaw();          // '123450' — no punctuation
m.getNumber();       // 1234.5 — currency formats only; null for the others
m.setValue('99');    // formats and fires tucano:change
m.isValid();         // verifies the check digit, on formats that have one
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
});

The utilities behind the mask are exposed too, to validate or format outside a field:

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'

Validation

With data-validate, the check digit is verified when leaving the field. If it fails, the field gets aria-invalid="true" and setCustomValidity, and the browser itself blocks the submit — without a line in the project.

And a correct value shows right away: as soon as the value is complete and right, the field turns green, without waiting for it to lose focus. The error waits — while typing, a half-typed CPF never turns red; it is only flagged when leaving the field, and clears again once the person goes back to fix it. The green state is the data-tuc-valid attribute, painted with --tuc-success.

It applies to cpf, cnpj, cnpj-numeric and cpf-cnpj; the other formats have no digit to verify. An empty field passes: requiredness belongs to required. While typing the error goes away, and when coming back to the field too — including the flag that came from the server, because the person is fixing it.

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

Sensitive field

data-tuc-reveal adds an eye to show and hide. A field that arrives already filled starts hidden, with only the end visible; an empty field starts visible, because whoever is typing needs to see. Passwords are the exception: they always start hidden.

<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>

What the form posts doesn't change because it's hidden. Except for type="password", the name moves to an <input type="hidden"> with the real value, and the visible field shows the dots. While hidden, the field is read-only: typing over the dots would overwrite the value without the person noticing. The separators stay in place, so the shape remains recognizable: •••.•••.•••-35.

Loose text on the page

Not all sensitive data lives in a field: the CPF on a customer screen, the card number in a table cell, the API key in a paragraph. data-tuc-reveal works on any element, in the same modes, and together with data-tuc-format. The text starts hidden, with the eye next to it.

<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>API key: <span data-tuc-reveal="all">{{ api_key }}</span></p>

Display only

For what already comes from the database and isn't edited, you don't need a field: data-tuc-format formats the text of the element itself.

<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>

Accepts cpf, cnpj, cpf-cnpj, phone, mobile, cep, card, real, currency and free patterns, with data-decimals and data-currency for currency. The value comes from the element's text or from data-value. Currency reads the database's decimal point (1234.5) and also a comma. Content that doesn't fill the pattern comes back as it was, instead of coming out half done and looking corrupted. For HTML inserted by some other path than HTMX, use Tucano.autoFormat(element).

Keyboard and accessibility

The mask uses the browser's keyboard handling, with no shortcuts of its own. What it takes care of is keeping the cursor from getting lost.

The eye announces "Show" or "Hide" and its state through aria-pressed. When showing, focus goes to the field. When it fails validation, the field gets aria-invalid="true", which the screen reader reads as invalid.

API

Generated from the code on every build — if something is not here, it does not exist.

Options

The notes in this table come from comments in the source code, which are written in Portuguese.