InputMask

Patterns typed clean.

<sui-input-mask>Text inputsStable

About

Text field that types into a pattern: phones, EINs, ZIPs. 9 takes a digit, a a letter, * either, ? makes the rest optional, and every other character is a literal the field inserts for you. Keys that do not fit are dropped without a flash. Form-associated: it posts name=value and binds to React, Vue (v-model) and Angular forms.

Usage

<sui-input-mask label="Phone" name="phone" mask="(999) 999-9999" value="8122820135"></sui-input-mask> <script type="module"> import { defineCustomElements } from "@shineui/core/loader"; import "@shineui/core/shineui.css"; defineCustomElements(); const el = document.querySelector("sui-input-mask"); el.addEventListener("suiChange", (e) => console.log(e.detail)); </script>

import { SuiInputMask } from "@shineui/react"; import "@shineui/core/shineui.css"; export function Example() { return <SuiInputMask label="Phone" name="phone" mask="(999) 999-9999" value="8122820135" onSuiChange={(e) => console.log(e.detail)} />; }

import { Component } from "@angular/core"; import { SuiInputMask } from "@shineui/angular"; @Component({ standalone: true, imports: [SuiInputMask], template: `<sui-input-mask label="Phone" name="phone" mask="(999) 999-9999" value="8122820135" (suiChange)="onChange($event)"></sui-input-mask>`, }) export class Example { onChange(e: CustomEvent) { console.log(e.detail); } }

Basic

The placeholder is the mask with underscores in the slots. A "Format" line is described with the help text, so a screen reader hears the shape once the placeholder is gone.

Patterns

9 is a digit slot, a is a letter slot and * takes either. Set placeholder to show something other than underscores.

Optional slots

Everything after ? is optional. suiComplete fires once the required slots fill, at five digits here, and the format hint read with the help text names the required part.

Sizes

md is the default, one height with every select, picker and button, so a form built from defaults lines up. lg is the roomier field for a sign-in or marketing page; sm packs into table rows.

States

The error line replaces help and carries role="alert". A read-only field still posts its value; a disabled one does not.

Half-typed values

While the required slots are not all filled the field reports patternMismatch with the format, so a form refuses a half-typed number the way it refuses an empty required phone. auto-clear drops the partial text when the field loses focus; without it the text stays and the message does.

Nothing checked yet.

<div style="display:grid;gap:14px;max-width:320px"> <sui-input-mask id="im-partial" label="Phone" name="phone" required help="Type three digits and press Tab."></sui-input-mask> <sui-input-mask id="im-clear" label="Phone" name="phone2" auto-clear help="The same, cleared on blur."></sui-input-mask> <output id="im-partial-out" style="font:460 13px/1.6 var(--font-sans);color:var(--ink-muted)">Nothing checked yet.</output> </div>

// setup(root): properties and events setup(root) { const partial = root.querySelector('#im-partial'); const out = root.querySelector('#im-partial-out'); partial.addEventListener('suiBlur', () => { out.textContent = partial.checkValidity() ? 'Valid.' : partial.validationMessage; }); }

In a form

The field posts what it shows, unless unmask asks for the bare characters. Reset restores the value each field mounted with.

<form id="mask-form" style="display:grid;gap:14px;max-width:340px"> <sui-input-mask label="Phone" name="phone" mask="(999) 999-9999" value="6145551212"></sui-input-mask> <sui-input-mask label="Phone, unmasked" name="phone_raw" mask="(999) 999-9999" value="6145551212" unmask></sui-input-mask> <div style="display:flex;gap:8px"> <sui-button type="submit" variant="brand" label="Submit"></sui-button> <sui-button type="reset" variant="outline" label="Reset"></sui-button> </div> <output id="mask-out" style="font:460 13px/1.6 var(--font-sans);color:var(--ink-muted)">Submit to see what posts.</output> </form>

// setup(root): properties and events setup(root) { const form = root.querySelector('#mask-form'); const out = root.querySelector('#mask-out'); form.addEventListener('submit', (e) => { e.preventDefault(); out.textContent = [...new FormData(form)].map(([k, v]) => `${k}=${v || '(empty)'}`).join(' '); }); form.addEventListener('reset', () => { out.textContent = 'Reset. Submit to see what posts.'; }); }

Events

suiInput fires on every keystroke and suiChange on commit at blur or Enter, both with the formatted value. suiComplete fires once, the moment the required slots fill. suiFocus and suiBlur follow the input.

Idle.

// setup(root): properties and events setup(root) { const log = root.querySelector('#mask-log'); const el = root.querySelector('#mask-events'); el.addEventListener('suiFocus', () => { log.textContent = 'suiFocus'; }); el.addEventListener('suiBlur', () => { log.textContent = 'suiBlur'; }); el.addEventListener('suiInput', (e) => { log.textContent = `suiInput ${e.detail || '(empty)'}`; }); el.addEventListener('suiChange', (e) => { log.textContent = `suiChange ${e.detail || '(empty)'}`; }); el.addEventListener('suiComplete', (e) => { log.textContent = `suiComplete ${e.detail}`; }); }

Keyboard

Key	Action
`Digits and letters`	Accepted when they fit the slot at the caret; the field inserts the next literal for you. Anything else is dropped.
`Any character on a full field`	Dropped: the mask has no room to shift.
`Ctrl or Cmd shortcuts`	Select all, copy, cut, paste and undo work as in any text field, on a full field too. Pasted text is fitted to the mask.

API

`<sui-input-mask>`

Properties

Property	Attribute	Type	Default	Description
`autoClear`	`auto-clear`	`boolean`	`false`	Drops a half-typed value when the field loses focus, so a phone number with three digits in it leaves as an empty field rather than a wrong one. Off by default: the partial text stays, and the field reports it as `patternMismatch` until the required slots are full.
`autocomplete`	`autocomplete`	`string`string \| undefined		Native autocomplete token. Off by default: autofilled text is re-packed positionally, so a value carrying a country code or extension mis-formats (`+1 812 282 0135` becomes `(181) 228-2013`). Opt in only where the mask matches the token exactly.
`disabled`	`disabled`	`boolean`	`false`	Disables the field.
`error`	`error`	`string`string \| undefined		Error message; paints the field in the danger tone and sets aria-invalid.
`help`	`help`	`string`string \| undefined		Help text under the field. Replaced by `error` when set.
`invalid`	`invalid`	`boolean`	`false`	Danger border without a message (validation handled elsewhere).
`label`	`label`	`string`string \| undefined		Field label. Without one the field takes the host's `aria-label` or `aria-labelledby` as its name; a visible label wins over both.
`mask`	`mask`	`string`	`'(999) 999-9999'`	Mask pattern: 9 digit, a letter, * alphanumeric, anything else literal. A `?` marks everything after it optional, so `99999?-9999` takes a five or a nine digit ZIP and `suiComplete` fires at five.
`name`	`name`	`string`string \| undefined		Form control name. Reflected: form entry construction reads the content attribute, while all three framework bindings set properties, so an unreflected name posts nothing at all.
`placeholder`	`placeholder`	`string`string \| undefined		Placeholder; defaults to the mask with slots shown as underscores and the `?` dropped.
`readOnly`	`readonly`	`boolean`	`false`	Display only: the text can be selected and copied but not edited; the field still posts.
`required`	`required`	`boolean`	`false`	Marks the field required (asterisk + valueMissing validity when empty).
`size`	`size`	`"lg" \| "md" \| "sm"`	`'md'`	Control height: sm 28 for table rows, md 34 for forms and toolbars (the default, shared with the select family and the buttons, so a form built from defaults is one height), lg 42 for a sign-in or marketing page.
`unmask`	`unmask`	`boolean`	`false`	Post the typed characters instead of the formatted value: `6145551212` rather than `(614) 555-1212`. Off by default: the field posts exactly what it shows, which is what `value`, `suiInput` and `suiChange` all carry. Turn it on when the endpoint wants bare characters. `getUnmasked()` reads the same string without changing what the form posts.
`value`	`value`	`string`	`''`	The formatted value, as shown. Mutable; a raw write is re-formatted against the mask. `getUnmasked()` returns the typed characters alone.

Events

Event	Detail	React	Vue	Description
`suiBlur`	`void`	`onSuiBlur`	`@sui-blur`	Fires when the input loses focus; no detail. Does not bubble.
`suiChange`	`string`	`onSuiChange`	`@sui-change`	Fires on commit (blur or Enter, native change); detail is the formatted value.
`suiComplete`	`string`	`onSuiComplete`	`@sui-complete`	Fires once when the required slots fill: every slot, or those before a `?`. Detail is the formatted value.
`suiFocus`	`void`	`onSuiFocus`	`@sui-focus`	Fires when the input takes focus; no detail. The same pair is on every text field. Does not bubble.
`suiInput`	`string`	`onSuiInput`	`@sui-input`	Fires on every keystroke; detail is the formatted value.

Methods

Method	Signature	Description
`getUnmasked()`	`getUnmasked() => Promise<string>`	Returns the typed characters without mask literals, e.g. "8122820135".
`select()`	`select() => Promise<void>`	Selects the field text.
`setFocus()`	`setFocus() => Promise<void>`	Moves keyboard focus into the field.

Theming

Every design token this element can render with, read from its own stylesheets and the ones it imports. Set a token on :root or on any ancestor and every use below follows it. The values shown are the ones in the theme you are viewing. The list is read per stylesheet, so an element that imports a shared drawing module lists that module's tokens too, whether or not it paints with all of them.

InputMask

About

Usage

Basic

Patterns

Optional slots

Sizes

States

Half-typed values

In a form

Events

Keyboard

API

`<sui-input-mask>`

Properties

Events

Methods

Theming

Color12

Typography1

Spacing and size4

Radius1

Motion2

See also