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.
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.
Preview
Section titled “Preview”<div style="display: grid; gap: 1rem; width: 100%; max-width: 24rem">
<nana-masked-input
label="Date of birth"
mask="##/##/####"
keep-literals
placeholder="DD/MM/YYYY"
style="width: 100%"
></nana-masked-input>
<nana-masked-input
label="KRA PIN"
mask="A#########A"
uppercase
placeholder="A000000000Z"
style="width: 100%"
></nana-masked-input>
<nana-masked-input
label="Number plate"
mask="AAA ###A"
uppercase
placeholder="KAA 000A"
style="width: 100%"
></nana-masked-input>
</div> — · — · —
<script lang="ts">
import { NanaMaskedInput } from '$lib';
let born = $state('');
let pin = $state('');
let plate = $state('');
</script>
<div class="grid w-full max-w-sm gap-4">
<NanaMaskedInput
bind:value={born}
mask="##/##/####"
keepLiterals
label="Date of birth"
placeholder="DD/MM/YYYY"
/>
<NanaMaskedInput
bind:value={pin}
mask="A#########A"
uppercase
label="KRA PIN"
placeholder="A000000000Z"
/>
<NanaMaskedInput
bind:value={plate}
mask="AAA ###A"
uppercase
label="Number plate"
placeholder="KAA 000A"
/>
<p class="text-sm text-foreground-muted">
{born || '—'} · {pin || '—'} · {plate || '—'}
</p>
</div> Installation
Section titled “Installation”Install the package for a versioned dependency:
npm install @nana-tec/ui-componentsOr copy the source in and own it:
npx @nana-tec/ui add masked-input --framework web-componentsnpx @nana-tec/ui add masked-input --framework svelteLands 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.
| Character | Takes |
|---|---|
# | A digit |
A | A letter |
* | A letter or a digit |
\ | Makes the next character a literal, so \# is a # |
| Anything else | Written in for the person |
Some masks:
| Value | Mask |
|---|---|
| Date | ##/##/#### |
| KRA PIN | A#########A |
| Number plate | AAA ###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
Section titled “The value”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.
Validation
Section titled “Validation”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.
Accessibility
Section titled “Accessibility”- 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
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
disabled | disabled | boolean | false | Blocks interaction and leaves the value out of form submission. |
errorMessage | error-message | string | '' | Shown while invalid is set |
helperText | helper-text | string | '' | Text under the field, in the help part. |
invalid | invalid | boolean | false | Marks the field invalid and shows error-message in place of the helper text. |
keepLiterals | keep-literals | boolean | false | Hold and submit the value with the mask's literals in it |
label | label | string | '' | Visible label |
mask | mask | string | '' | # a digit, A a letter, * either, \\ makes the next character literal |
name | name | string | '' | Name the value is submitted under in a form. |
placeholder | placeholder | string | '' | Hint text shown while the field is empty. |
required | required | boolean | false | The form will not submit while this has no value. |
uppercase | uppercase | boolean | false | Upper-case letters as they are typed |
value | value | string | '' | The characters entered, with the literals too when keep-literals is set |
Events
| Event | Description |
|---|---|
nana-input | While typing; detail: { value, raw, complete } |
nana-change | When the field is left; detail: { value, raw, complete } |
CSS parts
| Part | Description |
|---|---|
::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
| Property | Description |
|---|---|
--nana-masked-input-height | Height of the field |
NanaMaskedInput
| Prop | Type | Default |
|---|---|---|
maskrequired | string | |
valuebind: | string | '' |
uppercase | boolean | false |
keepLiterals | boolean | false |
label | string | |
helperText | string | |
errorMessage | string | |
invalid | boolean | false |
onValueChange | (value: string, detail: { raw: string; complete: boolean }) => void |
Also accepts Omit<HTMLInputAttributes, 'class' | 'value' | 'type'>.