Logo

Midnight Owl UI

Input Mask

Stable v1.0.2

A text input that enforces a pattern as you type, phone numbers, dates, credit cards, whatever format you need, powered by Maska.

Interactive Playground

Experiment with masks, labels, icons, sizing, and validation states in real-time.

Configuration
Top
Mask & Sizing
Phone: +1 (###) ###-####
Small (sm)
Icons
Phone
None
States
v-model Output:
""
Live Source Code
<InputMask
  v-model="value"
  mask="+1 (###) ###-####"
  id="contact-phone-mask"
  label="Contact Number"
  placeholder="+1 (___) ___-____"
  iconStart="lucide:phone"
/>

Standard Masks

Use the mask prop to enforce specific data entry patterns. Use # for numbers and @ for letters.

Template
<!-- Use '#' for numbers -->
<InputMask
  label="Phone Number"
  mask="+1 (###) ###-####"
  v-model="phoneValue"
/>

Inline Forms (Left Labels)

Pass labelPosition="left" to align the label next to the input. This layout automatically stacks on mobile devices.

Template
<div class="flex flex-col gap-6 w-full max-w-2xl">
  <InputMask
    label="Contact Number"
    labelPosition="left"
    mask="+1 (###) ###-####"
    required
  />
</div>

Validation & States

The error prop transforms the input and intelligently maps over arrays to display multiple validation requirements.

Invalid date format.
Must be a valid international format.
Cannot start with a zero.
Template
<script setup>
const maskErrors = ref([
  'Must be a valid international format.',
  'Cannot start with a zero.'
])
</script>

<template>
  <InputMask
    label="Secure Phone"
    mask="+1 (###) ###-####"
    :error="maskErrors"
  />
</template>

Input Sizing

Five carefully calibrated sizes. Use xs specifically for dense data tables or tight inline filters.

Template
<!-- Dense layout masks -->
<InputMask label="Extra Small" size="xs" mask="####" />
<InputMask label="Small" size="sm" mask="####" />

<!-- Standard layout masks -->
<InputMask label="Medium" size="md" mask="####" />
<InputMask label="Large" size="lg" mask="####" />

Advanced Tokens & Dynamics

Pass an array to mask for dynamic lengths, or map custom RegExp validation using the tokens prop.

Custom Tokens
const hexTokens = {
  'H': { pattern: /[0-9a-fA-F]/, uppercase: true }
}
Template
<!-- Dynamic Arrays -->
<InputMask :mask="['#### #### #### ####', '#### ###### #####']" />

<!-- Custom RegExp Tokens -->
<InputMask mask="!#HHHHHH" :tokens="hexTokens" />

API Reference

Props

Name
Type / Signature
Default
Description
modelValue
string
""
The masked input value, bound via v-model.
id
string
undefined
Overrides the auto-generated id applied to the underlying input element and its label.
mask
string | string[]
required
Mask pattern using '#' for numbers and '@' for letters. Pass an array for dynamic-length masks.
tokens
Record<string, any>
undefined
Custom Maska token definitions for advanced patterns (e.g. hex colors).
label
string
undefined
Top or left-aligned input label.
labelPosition
"top" | "left"
"top"
Alignment of the label relative to the input field.
required
boolean
false
Marks the field as required and renders an asterisk next to the label.
placeholder
string
undefined
Text shown when the input is empty.
disabled
boolean
false
Disables user interaction and grays out the component.
error
string | boolean | string[]
false
Applies red error styling and displays error message(s) below the input.
iconStart
string
undefined
Lucide icon displayed on the left side of the input.
iconEnd
string
undefined
Lucide icon displayed on the right side of the input. Can be combined with iconStart.
size
"xs" | "sm" | "md" | "lg" | "xl"
"sm"
Dimensional size of the component.

Events

Event Name
Payload Signature
Description
@focus
(event: FocusEvent)
Fired when the input receives focus.
@blur
(event: FocusEvent)
Fired when the input loses focus.
@input
(value: string)
Fired on every keystroke.
@change
(value: string)
Fired when the value commits (on native change).
@maska
(event: CustomEvent)
Fired by Maska whenever the mask engine processes input, exposing raw/masked/completed details.