An input with mask is a <div> wrapper around a text <input> and a decorative format-mask display (e.g., (___) ___-____) that overlays the input to show the user where to type each character.
Use it for structured fields such as phone numbers, dates, or document identifiers that have a predictable character pattern.
<div class="input-with-mask" aria-label="an input displaying a format mask placeholder for the user to fill in">InputWithMask</div><script lang="ts">
import InputWithMask from './InputWithMask.svelte';
let phone = $state('');
</script>
<InputWithMask
label="Phone number"
mask="(___) ___-____"
value={phone}
oninput={(e) => (phone = (e.target as HTMLInputElement).value)}
/>
// In your Svelte component:
import InputWithMask from "lily-design-system-svelte-headless/components/InputWithMask/InputWithMask.svelte";
<InputWithMask>
<!-- content -->
</InputWithMask>
US phone number mask:
<InputWithMask
label="Phone number"
mask="(___) ___-____"
value={phone}
oninput={(e) => phone = e.target.value}
/>Date mask:
<InputWithMask
label="Date of birth"
mask="MM/DD/YYYY"
value={dob}
/>label: string (required) -- aria-label for the inputmask: string (required) -- format mask (e.g., (___) ___-____)value: string (default: "") -- input valueplaceholder: string (optional) -- input placeholderdisabled: boolean (default: false) -- disabled stateonInput / oninput: callback (optional) -- input change handler...restProps: any additional HTML attributes<input>aria-label from the label proparia-hidden="true" so screen readers do not announce the placeholder pattern<div> has a data-mask attribute for consumer stylingTextInput instead.PasswordInput.<input type="tel">, <input type="date">) when those are appropriate.Renders the structural skeleton — <div> with <span> mask display and <input> control. The visual overlay technique that aligns the mask with the input characters is entirely the consumer's responsibility.
Consumer CSS targets the input-with-mask class plus the inner input-with-mask-display and input-with-mask-control classes. Typical treatments use absolute positioning to overlay the mask on the input, with monospace typography so the characters align.
<div> with class input-with-maskdata-mask attribute equals the mask prop<span class="input-with-mask-display" aria-hidden="true">mask propinput-with-mask-controltextaria-label equal to the label propvalue propdisabled is trueValidationList) to verify the format.<div> with class input-with-mask and data-mask attributelabel prop is required — it sets aria-label on the <input>mask prop is required — the format string displayed to the user<span class="input-with-mask-display" aria-hidden="true"><input class="input-with-mask-control" type="text">aria-label is the accessible namevalue, placeholder, disabled are forwarded to the inputonInput / oninput callback fires on input changetext-input — a single-line text input field <input type="text">pin-input-div — a series of single-digit inputs for entering a PIN or OTP codeinput — a generic HTML input element<input type="text">: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/textGenerated from this component's canonical metadata — the machine-checked source the implementations are held to.
aria-label from the label proparia-hidden="true" (decorative)<input>label: string (REQUIRED) -- aria-label for the inputmask: string (REQUIRED) -- format mask stringvalue: string (default: "") -- input valueplaceholder: string (optional)disabled: boolean (default: false)onInput / oninput: callback (optional)...restProps: any additional HTML attributes