Mask input

A mask is a pattern string. The token 9 matches a digit, a matches a letter and * matches a letter or a digit. Every other character is a literal that the mask inserts on its own, as in (999) 999-9999, 99/99/9999 and aaa-9999.

The formatting is a pure function. The web version reformats on every keystroke inside a JavaScript hook. Here the field sends the raw text to your screen, and the screen calls MishkaMaskInput.apply_mask/2 where the value settles, in the handler. The component renders the value you give it.

apply_mask/2 works from the significant characters of the input only, which are its letters and digits. It discards literals and lays them out again from the mask, so formatting is idempotent. A user who deletes back through a literal does not have it re-inserted ahead of them, and pasting an already formatted value does not double its punctuation. MishkaMaskInput.strip/1 returns that payload without the literals.

The field gets the mask's length as max_length, so the keystroke past the end is refused where it happens. apply_mask/2 truncates as well, and the two work together. The placeholder defaults to the mask. The keyboard is "number" when the mask holds only 9 tokens and "text" otherwise. Pass keyboard to choose another.

Run this from your Mob app's root to add the component to lib/<app>/components/:

mix mishka.ui.gen.mob mask_input

The generator registers the tag, so you can use it in ~MOB markup. It also copies the shared Event helper module, unless you pass --no-kit. The examples on this page use the mishka_ prefix of the showcase app (--module-prefix mishka_), so the tag is <MishkaMaskInput>. Without a prefix, the tag is <MaskInput>.

Set mask to a pattern. As the user types digits, the literals of (999) 999-9999 appear on their own. The field sends the raw text as {:change, :phone, text}, and the handler applies the mask. Masking a value that is already masked changes nothing. The showcase also prints MishkaMaskInput.strip/1 under the field, which returns the unformatted digits.

Phone number mask

LTR RTL

Preview

Show the whole example Show less

~MOB"""
<Column fill_width={true}>
  <MishkaMaskInput value={@phone} mask="(999) 999-9999" on_change={:phone} />
</Column>
"""

# the mask is applied where the value settles — in the handler
def handle_info({:change, :phone, raw}, socket) do
  {:noreply, assign(socket, :phone, MishkaMaskInput.apply_mask(raw, "(999) 999-9999"))}
end

A mask can be any pattern. 9 is a digit, a a letter, * a letter or a digit, and everything else is a literal. placeholder replaces the default, which is the mask itself.

Date mask

LTR RTL

Preview

Show the whole example Show less

~MOB"""
<Column fill_width={true}>
  <MishkaMaskInput value={@date} mask="99/99/9999" placeholder="DD/MM/YYYY"
                   on_change={:date} />
</Column>
"""

Props of the <MishkaMaskInput> tag.

Your screen receives {:change, tag, text} in handle_info/2 with the raw text from on_change. The handler applies the mask before it assigns the value.

def handle_info({:change, :phone, raw}, socket) do
  {:noreply, Mob.Socket.assign(socket, :phone, MishkaMaskInput.apply_mask(raw, "(999) 999-9999"))}
end

• The web reformats inside a JavaScript hook. Mob formats in your handler with apply_mask/2.
• name is not ported, because it is form plumbing.
• inputmode is not ported. Mob derives the keyboard from the mask.
• id and class are not ported.

• Headless Mask Input, the web component this one ports.
• Mob OTP Field, a segmented input for one-time codes.
• Mob Number Field and Mob Field, other form controls.
• Mob components, the full list of native components.