MaskedInput

Added in version 0.80.0

A masked input derived from Input, allowing to restrict user input and give visual aid via a simple template mask, which also acts as an implicit validator.

• Focusable
• Container

Example

The example below shows a masked input to ease entering a credit card number.

Outputcheckbox.py

from textual.app import App, ComposeResult
from textual.widgets import Label, MaskedInput


class MaskedInputApp(App):
    # (1)!
    CSS = """
    MaskedInput.-valid {
        border: tall $success 60%;
    }
    MaskedInput.-valid:focus {
        border: tall $success;
    }
    MaskedInput {
        margin: 1 1;
    }
    Label {
        margin: 1 2;
    }
    """

    def compose(self) -> ComposeResult:
        yield Label("Enter a valid credit card number.")
        yield MaskedInput(
            template="9999-9999-9999-9999;0",  # (2)!
        )


app = MaskedInputApp()

if __name__ == "__main__":
    app.run()

Reactive Attributes

Name	Type	Default	Description
template	str	""	The template mask string.

The template string format

A MaskedInput template length defines the maximum length of the input value. Each character of the mask defines a regular expression used to restrict what the user can insert in the corresponding position, and whether the presence of the character in the user input is required for the MaskedInput value to be considered valid, according to the following table:

Mask character	Regular expression	Required?
A	[A-Za-z]	Yes
a	[A-Za-z]	No
N	[A-Za-z0-9]	Yes
n	[A-Za-z0-9]	No
X	[^ ]	Yes
x	[^ ]	No
9	[0-9]	Yes
0	[0-9]	No
D	[1-9]	Yes
d	[1-9]	No
#	[0-9+\-]	No
H	[A-Fa-f0-9]	Yes
h	[A-Fa-f0-9]	No
B	[0-1]	Yes
b	[0-1]	No

There are some special characters that can be used to control automatic case conversion during user input: > converts all subsequent user input to uppercase; < to lowercase; ! disables automatic case conversion. Any other character that appears in the template mask is assumed to be a separator, which is a character that is automatically inserted when user reaches its position. All mask characters can be escaped by placing \ in front of them, allowing any character to be used as separator. The mask can be terminated by ;c, where c is any character you want to be used as placeholder character. The placeholder parameter inherited by Input can be used to override this allowing finer grain tuning of the placeholder string.

Messages

• MaskedInput.Changed
• MaskedInput.Submitted

Bindings

The masked input widget defines the following bindings:

Key(s)	Description
left	Move the cursor left.
ctrl+left	Move the cursor one word to the left.
right	Move the cursor right or accept the completion suggestion.
ctrl+right	Move the cursor one word to the right.
backspace	Delete the character to the left of the cursor.
home,ctrl+a	Go to the beginning of the input.
end,ctrl+e	Go to the end of the input.
delete,ctrl+d	Delete the character to the right of the cursor.
enter	Submit the current value of the input.
ctrl+w	Delete the word to the left of the cursor.
ctrl+u	Delete everything to the left of the cursor.
ctrl+f	Delete the word to the right of the cursor.
ctrl+k	Delete everything to the right of the cursor.

Component Classes

The masked input widget provides the following component classes:

Class	Description
input--cursor	Target the cursor.
input--placeholder	Target the placeholder text (when it exists).
input--suggestion	Target the auto-completion suggestion (when it exists).

---

Bases: Input

A masked text input widget.

Parameters:

Name	Type	Description	Default
template	str	Template string.	required
value	str | None	An optional default value for the input.	None
placeholder	str	Optional placeholder text for the input.	''
validators	Validator | Iterable[Validator] | None	An iterable of validators that the MaskedInput value will be checked against.	None
validate_on	Iterable[InputValidationOn] | None	Zero or more of the values "blur", "changed", and "submitted", which determine when to do input validation. The default is to do validation for all messages.	None
valid_empty	bool	Empty values are valid.	False
name	str | None	Optional name for the masked input widget.	None
id	str | None	Optional ID for the widget.	None
classes	str | None	Optional initial classes for the widget.	None
disabled	bool	Whether the input is disabled or not.	False
tooltip	RenderableType | None	Optional tooltip.	None

template class-attribute instance-attribute

template = template

Input template mask currently in use.

action_cursor_left

action_cursor_left()

Move the cursor one position to the left; separators are skipped.

action_cursor_left_word

action_cursor_left_word()

Move the cursor left next to the previous separator. If no previous separator is found, moves the cursor to the start of the input.

action_cursor_right

action_cursor_right()

Move the cursor one position to the right; separators are skipped.

action_cursor_right_word

action_cursor_right_word()

Move the cursor right next to the next separator. If no next separator is found, moves the cursor to the end of the input.

action_delete_left

action_delete_left()

Delete one character to the left of the current cursor position.

action_delete_left_all

action_delete_left_all()

Delete all characters to the left of the cursor position.

action_delete_left_word

action_delete_left_word()

Delete leftward of the cursor position to the previous separator or the start of the input.

action_delete_right

action_delete_right()

Delete one character at the current cursor position.

action_delete_right_word

action_delete_right_word()

Delete the current character and all rightward to next separator or the end of the input.

action_home

action_home()

Move the cursor to the start of the input.

clear

clear()

Clear the masked input.

insert_text_at_cursor

insert_text_at_cursor(text)

Insert new text at the cursor, move the cursor to the end of the new text.

Parameters:

Name	Type	Description	Default
text	str	New text to insert.	required

validate

validate(value)

Run all the validators associated with this MaskedInput on the supplied value.

Same as Input.validate() but also validates against template which acts as an additional implicit validator.

Returns:

Type	Description
ValidationResult | None	A ValidationResult indicating whether all validators succeeded or not. That is, if any validator fails, the result will be an unsuccessful validation.

validate_value

validate_value(value)

Validates value against template.