1. Domino UI
  2. Forms
  3. Input mask Pro
Top Mask box Input mask String mask Docs

String mask

A utility class for applying mask rules to strings (e.g., phone numbers, IDs).

This class uses a Mask internally to define a pattern of placeholder characters (e.g., underscores) and fixed characters (like hyphens or parentheses). Users can input text, and StringMask will enforce the mask constraints. For example, if the mask is "(999) 999-9999" , users can only type digits where the '9' placeholders appear.

Once an input is masked, it can be retrieved as a partially-complete or fully-complete masked string. It also supports removing characters, shifting text, and retrieving the unmasked value.

Mask box

A specialized text box component that enforces a specified input mask on user-entered text.

This class extends BaseTextBox and internally manages an InputMask object. Users can configure the mask via StringMask and its associated MaskOptions to allow or restrict certain characters, implement special formatting, etc.

Example usage:


 MaskBox maskBox = MaskBox.create("(999) 999-9999");
 maskBox.appendChildTo(document.body);

By default, MaskBox calls startMasking upon construction to activate event listeners for enforcing the mask.

Input mask

A higher-level utility class that binds a StringMask to an input element (either an HTMLInputElement or HTMLTextAreaElement).

Upon calling startMasking , this class intercepts keyboard and clipboard events to enforce the configured mask, updating the displayed text accordingly while keeping track of a separate masked and unmasked value.

Features:

  • Listening to keyboard events to validate and place typed characters within the mask
  • Handling copy, cut, and paste operations, such that only the unmasked/filtered content is passed to/from the clipboard
  • Automated deletion (backspace and delete) logic that respects the mask boundaries
  • Synchronizing cursor position (selection start/end) with the internal StringMask

This class can be created via various static of(...) methods that accept different types of input elements and optional MaskOptions .

Examples

String mask Format strings using a mask

Mask box Form fields with built-in input masking

Input mask Mask any input field

Learn more

API Docs: StringMask

Browse full javadocs

Constructors

public void StringMask(String mask)
Constructs a new StringMask with a given mask string and default MaskOptions .

mask

the mask pattern (e.g., "(999) 999-9999" ). Cannot be null.

@throws IllegalArgumentException if {@code mask} is null
public void StringMask(String mask, MaskOptions options)
Constructs a new StringMask with a given mask string and MaskOptions .

mask

the mask pattern (e.g., "(999) 999-9999" ). Cannot be null.

options

configuration options for how masking behaves

@throws IllegalArgumentException if {@code mask} is null

Public methods

public String getPlaceHolder()
Gets the entire placeholder string for this mask. For instance, if the mask is "(999) 999-9999" , the placeholder might be "(___) ___-____" .

Returns:

the placeholder string

public int getPosition()
Gets the current cursor position within the mask. This is where new characters would be inserted or where deletions would occur.

Returns:

the current position in the masked string

public String getMaskedValue()
Gets the fully masked value in its current state. Some positions may still contain placeholder characters, while others may have user-entered data.

Returns:

the masked string

public StringMask clearMasking()
Resets the mask to its initial placeholder state and sets the cursor position to 0.

Returns:

this StringMask instance, for chaining

public StringMask setMask(String mask)
Sets a new mask pattern, optionally preserving and re-masking the existing input if available.

If the new mask is not null or empty, the unmasked value is extracted from the current masked value, the mask is cleared, and then the input is remasked according to the new pattern.

mask

the new mask string



Returns:

this StringMask instance, for chaining

public StringMask clearMasking(int startPosition, int endPosition)
Clears the masking (resets positions to placeholder) in a specified range from startPosition to endPosition .

startPosition

the starting index

endPosition

the ending index



Returns:

this StringMask instance, for chaining

public StringMask maskInput(String input)
Adds/masks the entire provided string input into the current mask, starting from the current cursor position.

input

the string to insert



Returns:

this StringMask instance, for chaining

public StringMask maskInput(int startPosition, String input)
Adds/masks the entire provided string input into the current mask at a specific position.

startPosition

the position at which to begin masking

input

the string to insert



Returns:

this StringMask instance, for chaining

public StringMask setPosition(int position)
Sets the current cursor position within the mask. If the specified position is out of bounds, it is clamped to [0, mask length].

position

the new cursor position



Returns:

this StringMask instance, for chaining

public StringMask moveLeft()
Moves the cursor one position to the left (if possible).

Returns:

this StringMask instance, for chaining

public StringMask moveLeft(int repeat)
Moves the cursor multiple positions to the left (if possible).

repeat

how many positions to move



Returns:

this StringMask instance, for chaining

public StringMask moveRight()
Moves the cursor one position to the right (if possible).

Returns:

this StringMask instance, for chaining

public StringMask moveRight(int repeat)
Moves the cursor multiple positions to the right (if possible).

repeat

how many positions to move



Returns:

this StringMask instance, for chaining

public StringMask deleteLeft()
Deletes a single character to the left of the current cursor position, if it is a placeholder position that currently holds user input.

Returns:

this StringMask instance, for chaining

public StringMask deleteLeft(int repeat)
Deletes multiple characters to the left of the current cursor position, if they are placeholder positions that currently hold user input.

repeat

how many characters to delete



Returns:

this StringMask instance, for chaining

public StringMask deleteLeft(int startPosition, int repeat)
Deletes characters to the left of a specified position in the mask.

startPosition

the position from which to start deleting

repeat

the number of characters to delete



Returns:

this StringMask instance, for chaining

public StringMask deleteRight()
Deletes a single character to the right of the current cursor position, if it is a placeholder position that currently holds user input.

Returns:

this StringMask instance, for chaining

public StringMask deleteRight(int repeat)
Deletes multiple characters to the right of the current cursor position, if they are placeholder positions that currently hold user input.

repeat

how many characters to delete



Returns:

this StringMask instance, for chaining

public StringMask deleteRight(int startPosition, int repeat)
Deletes characters to the right of a specified position in the mask.

startPosition

the position from which to start deleting

repeat

the number of characters to delete



Returns:

this StringMask instance, for chaining

public String getUnmaskedValue()
Retrieves the unmasked value from the entire current masked string (0..mask length). Any placeholder characters are removed or replaced based on MaskOptions .

Returns:

the unmasked string (user-entered data)

public String getUnmaskedValue(int startIndex)
Retrieves the unmasked value from a given start index to the end of the mask.

startIndex

the start index for extraction



Returns:

the unmasked substring

public String getUnmaskedValue(int startIndex, int endIndex)
Retrieves the unmasked value in a specified range. This strips out placeholder characters (unless the user has typed over them), potentially replacing them with a missing character token (from MaskOptions ) if desired.

startIndex

the start index (inclusive)

endIndex

the end index (exclusive)



Returns:

the unmasked substring

public MaskOptions getOptions()


Returns:

the MaskOptions being used by this mask

public StringMask withOptions(ChildHandler<StringMask, MaskOptions> handler)
Allows customization of the current MaskOptions instance using a functional handler.

handler

a ChildHandler that takes this mask and its options for further configuration



Returns:

this StringMask instance, for chaining

API Docs: MaskBox

Browse full javadocs

Constructors

public void MaskBox(String mask)
Constructs a new MaskBox with a given mask and default options.

mask

the mask pattern (cannot be null)

@throws IllegalArgumentException if the provided mask is null
public void MaskBox(String mask, MaskOptions options)
Constructs a new MaskBox with a given mask and custom options.

mask

the mask pattern (cannot be null)

options

the custom mask options

@throws IllegalArgumentException if the provided mask is null
public void MaskBox(String label, String mask)
Constructs a new MaskBox with a given label and mask, using default options.

label

the label for the text box

mask

the mask pattern (cannot be null)

@throws IllegalArgumentException if the provided mask is null
public void MaskBox(String label, String mask, MaskOptions options)
Constructs a new MaskBox with a given label, mask, and custom options.

label

the label for the text box

mask

the mask pattern (cannot be null)

options

custom MaskOptions

@throws IllegalArgumentException if the provided mask is null

Static methods

public static MaskBox create(String mask)
Creates a new MaskBox with the specified mask and default MaskOptions .

mask

the mask pattern (e.g., "(999) 999-9999" )



Returns:

a new MaskBox instance

@throws IllegalArgumentException if the provided mask is null
public static MaskBox create(String mask, MaskOptions options)
Creates a new MaskBox with the specified mask and custom MaskOptions .

mask

the mask pattern

options

the custom mask options



Returns:

a new MaskBox instance

@throws IllegalArgumentException if the provided mask is null
public static MaskBox create(String label, String mask)
Creates a new MaskBox with the specified label and mask, using default options.

label

the label for the text box

mask

the mask pattern



Returns:

a new MaskBox instance

@throws IllegalArgumentException if the provided mask is null
public static MaskBox create(String label, String mask, MaskOptions options)
Creates a new MaskBox with the specified label, mask, and custom options.

label

the label for the text box

mask

the mask pattern

options

the custom mask options



Returns:

a new MaskBox instance

@throws IllegalArgumentException if the provided mask is null

Public methods

public String getValue()
Check super implementation documentation.

Returns the current unmasked value stored in this component.

public MaskBox setMask(String mask)
Dynamically changes the mask pattern, preserving user input if possible. The component is re-initialized according to the new mask.

mask

the new mask pattern



Returns:

this MaskBox instance

public String getUnmaskedValue()
Returns the current unmasked value from the internal InputMask .

Returns:

the unmasked string

public String getMaskedValue()
Returns the current masked value from the internal InputMask . This is the text displayed in the input element.

Returns:

the masked string

public InputMask getInputMask()
Returns the underlying InputMask controlling this component.

Returns:

the current InputMask

public MaskBox withInputMask(ChildHandler<MaskBox, InputMask> handler)
Allows further customization or inspection of the underlying InputMask , via a ChildHandler .

handler

a lambda or method reference to be applied to the input mask



Returns:

this MaskBox instance, for method chaining

public StringMask getStringMask()
Retrieves the StringMask currently in use by the InputMask .

Returns:

the string mask

public MaskBox withStringMask(ChildHandler<MaskBox, StringMask> handler)
Allows customization of the underlying StringMask , via a ChildHandler .

handler

a lambda or method reference to be applied to the string mask



Returns:

this MaskBox instance, for method chaining

public MaskBox withOptions(ChildHandler<MaskBox, MaskOptions> handler)
Allows customization of the underlying MaskOptions , via a ChildHandler .

handler

a lambda or method reference to be applied to the mask options



Returns:

this MaskBox instance, for method chaining

public String getType()
Check super implementation documentation.

Specifies the input type for the underlying DOM element, which is "text" by default for masked input.

API Docs: InputMask

Browse full javadocs

Constructors

public void InputMask(InputElement inputElement, String mask)
Constructs a new InputMask for a Domino InputElement and basic mask pattern.

inputElement

the Domino UI wrapper for

mask

the mask pattern

public void InputMask(HTMLInputElement inputElement, String mask)
Constructs a new InputMask for a raw HTMLInputElement and basic mask pattern.

inputElement

the element

mask

the mask pattern

public void InputMask(TextAreaElement textAreaElement, String mask)
Constructs a new InputMask for a Domino TextAreaElement and basic mask pattern.

textAreaElement

the Domino UI wrapper for

We are a group of passionate people who love what we do

Donate & Support Us