Skip to content
Nana UI

Forms & Inputs

Masked Input

A text field shaped by a pattern, such as a date, a KRA PIN or a number plate, that writes in the separators as people type.

View .md Download

The masked input takes a value with a fixed shape: a date, a KRA PIN, a number plate, an account number. People type only the characters; the field accepts the right kind in each place and writes in the separators. For a phone number use the phone input, which knows each country’s length and dialling code; for a number someone adjusts, the number input.

— · — · —

Install the package for a versioned dependency:

npm install @nana-tec/ui-components

Or copy the source in and own it:

npx @nana-tec/ui add masked-input --framework web-components
npx @nana-tec/ui add masked-input --framework svelte

Lands in src/lib/components/ui/masked-input/ as NanaMaskedInput.svelte, styled with Tailwind classes that resolve to the design tokens. Requires Tailwind v4.

<script lang="ts">
import { NanaMaskedInput } from '$lib/components/ui/masked-input';
let pin = $state('');
</script>
<NanaMaskedInput bind:value={pin} mask="A#########A" uppercase label="KRA PIN" name="pin" />

value is bindable. onValueChange receives it with { raw, complete }.

Import the autoloader once, in your app's entry point. Every <nana-*> tag then works anywhere, and each component downloads only the first time a page uses it:

import "@nana-tec/ui-components/autoloader";
import "@nana-tec/ui-components/theme";

The second line gives every component the Nana look and the design tokens behind it. Leave it out to style the components entirely yourself.

Import a component directly when it must be ready at once: on screen at first paint, or when you call its methods straight away. The two mix freely:

import "@nana-tec/ui-components/masked-input";

Copied in with npx @nana-tec/ui add masked-input? Import your project's own @/lib/nana-ui/autoloader.js once instead; the CLI keeps it up to date.

<nana-masked-input label="KRA PIN" mask="A#########A" uppercase name="pin"></nana-masked-input>
<script type="module">
const pin = document.querySelector('nana-masked-input');
pin.addEventListener('nana-change', (event) => {
console.log(event.detail.value, event.detail.complete);
});
</script>

The element takes part in its form: it submits value under name, resets with the form, and is disabled with a disabled fieldset. nana-input fires while typing and nana-change when the field is left.

CharacterTakes
#A digit
AA letter
*A letter or a digit
\Makes the next character a literal, so \# is a #
Anything elseWritten in for the person

Some masks:

ValueMask
Date##/##/####
KRA PINA#########A
Number plateAAA ###A
Card expiry##/##
Account number#### #### ####

A separator appears once the character after it is typed, so Backspace removes characters rather than stopping at a slash. A separator someone types or pastes is accepted, so 12/05/2026 and 12052026 give the same value. Characters that do not fit their place are skipped, and typing stops when the mask is full. Set uppercase to upper-case letters.

The value holds only the characters typed: 12052026. Set keepLiterals (keep-literals on the element) to hold and submit it as shown instead: 12/05/2026. A value you set can be written either way.

A value that does not fill the mask blocks the form, and once the field is left it shows “Complete this field”. With required, an empty field blocks the form too. For any other problem, such as a date in the future, set invalid with your own errorMessage.

Use placeholder to show the shape before anything is typed, such as DD/MM/YYYY.

  • The field asks for the number pad (inputmode="numeric") when every place takes a digit, and the keyboard otherwise.
  • Autocomplete and spellcheck are off, since browsers rarely hold these values and would mark a PIN as misspelt.
  • Say what goes in the field in its label or help, such as “As on your ID”; the mask alone does not tell anyone the expected order of day and month.
  • The help text describes the field; an error replaces it and is announced.

Properties

PropertyAttributeTypeDefaultDescription
disableddisabledbooleanfalseBlocks interaction and leaves the value out of form submission.
errorMessageerror-messagestring''Shown while invalid is set
helperTexthelper-textstring''Text under the field, in the help part.
invalidinvalidbooleanfalseMarks the field invalid and shows error-message in place of the helper text.
keepLiteralskeep-literalsbooleanfalseHold and submit the value with the mask's literals in it
labellabelstring''Visible label
maskmaskstring''# a digit, A a letter, * either, \\ makes the next character literal
namenamestring''Name the value is submitted under in a form.
placeholderplaceholderstring''Hint text shown while the field is empty.
requiredrequiredbooleanfalseThe form will not submit while this has no value.
uppercaseuppercasebooleanfalseUpper-case letters as they are typed
valuevaluestring''The characters entered, with the literals too when keep-literals is set

Events

EventDescription
nana-inputWhile typing; detail: { value, raw, complete }
nana-changeWhen the field is left; detail: { value, raw, complete }

CSS parts

PartDescription
::part(label)The field label
::part(required)The asterisk after a required field's label
::part(base)The box around the field
::part(input)The text field
::part(help)The helper text
::part(error)The error message

CSS custom properties

PropertyDescription
--nana-masked-input-heightHeight of the field

NanaMaskedInput

PropTypeDefault
maskrequiredstring
valuebind:string''
uppercasebooleanfalse
keepLiteralsbooleanfalse
labelstring
helperTextstring
errorMessagestring
invalidbooleanfalse
onValueChange(value: string, detail: { raw: string; complete: boolean }) => void

Also accepts Omit<HTMLInputAttributes, 'class' | 'value' | 'type'>.