Awesome
<img src="Documentation/Assets/logo.png" alt="Input Mask" />Input masks restrict data input and allow you to guide users to enter correct values.
Check out our wiki for quick start and further reading.
⚙️ Features
- Apply formatting to your text fields, see examples
- Filter out nonessential symbols (e.g. extract
0123456
from+1 (999) 012-34-56
) - For international phone numbers
- guess the country from the entered digits
- apply corresponding value restrictions (e.g. a 🇺🇸US phone will have a format like
+1 201 456-7890
)
- Apply number/currency formatting
💳 Examples
- Phone numbers:
+1 ([000]) [000] [00] [00]
- Dates:
[00]{.}[00]{.}[9900]
- Serial numbers:
[AA]-[00000099]
- IPv4:
[099]{.}[099]{.}[099]{.}[099]
- Visa/MasterCard numbers:
[0000] [0000] [0000] [0000]
- UK IBAN:
GB[00] [____] [0000] [0000] [0000] [00]
🛠️ Installation
Gradle
Make sure you've added Kotlin support to your project.
repositories {
maven { url 'https://jitpack.io' }
}
dependencies {
implementation 'com.redmadrobot:input-mask-android:7.2.4'
implementation 'org.jetbrains.kotlin:kotlin-stdlib:$latest_version'
}
📢 Communication, Questions & Issues
Please take a closer look at our Known issues section before you incorporate our library into your project.
For your bugreports and feature requests please file new issues via GitHub.
Should you have any questions, please search for closed issues or ask questions at StackOverflow with the input-mask
tag.
❗Known issues
InputMask vs. NoClassDefFoundError
java.lang.NoClassDefFoundError: Failed resolution of: Lkotlin/jvm/internal/Intrinsics;
Receiving this error might mean you haven't configured Kotlin for your Java only project. Consider explicitly adding the following to the list of your project dependencies:
implementation 'org.jetbrains.kotlin:kotlin-stdlib:$latest_version'
— where latest_version
is the current version of kotlin-stdlib
.
InputMask vs. android:inputType
and IndexOutOfBoundsException
Be careful when specifying field's android:inputType
.
The library uses native Editable
variable received on afterTextChange
event in order to replace text efficiently. Because of that, field's inputType
is actually considered when the library is trying to mutate the text.
For instance, having a field with android:inputType="numeric"
, you cannot put spaces and dashes into the mentioned Editable
variable by default. Doing so will cause an out of range exception when the MaskedTextChangedListener
will try to reposition the cursor.
Still, you may use a workaround by putting the android:digits
value beside your android:inputType
; there, you should specify all the acceptable symbols:
<EditText
android:inputType="number"
android:digits="0123456789 -."
... />
— such that, you'll have the SDK satisfied.
Alternatively, if you are using a programmatic approach without XML files, you may consider configuring a KeyListener
like this:
editText.setInputType(InputType.TYPE_CLASS_NUMBER);
editText.setKeyListener(DigitsKeyListener.getInstance("0123456789 -.")); // modify character set for your case, e.g. add "+()"
InputMask vs. autocorrection & prediction
(presumably fixed by PR50)
Symptoms:
- You've got a wildcard template like
[________]
, allowing user to write any kind of symbols; - Cursor jumps to the beginning of the line or to some random position while user input.
In this case text autocorrection & prediction might be a root cause of your problem, as it behaves somewhat weirdly in case when field listener tries to change the text during user input.
If so, consider disabling text suggestions by using corresponding input type:
<EditText
...
android:inputType="textNoSuggestions" />
Additionally be aware that some of the third-party keyboards ignore textNoSuggestions
setting; the recommendation is to use an extra workaround by setting the inputType
to textVisiblePassword
.
InputMask vs. android:textAllCaps
Please be advised that android:textAllCaps
is not meant to work with EditText
instances:
This setting will be ignored if this field is editable or selectable.
Enabling this setting on editable and/or selectable fields leads to weird and unpredictable behaviour and sometimes even crashes. Instead, consider using android:inputType="textCapCharacters"
or workaround by adding an InputFilter
:
final InputFilter[] filters = { new InputFilter.AllCaps() };
editText.setFilters(filters);
Bare in mind, you might have to befriend this solution with your existing android:digits
property in case your text field accepts both digits and letters.
🙏 Special thanks
These folks rock:
- Artem Fi5t Kulakov
- Nikita nbarishok Barishok
- Roman yatsinar Iatcyna
- Alexander xanderblinov Blinov
- Vladislav Shipaaaa Shipugin
- Vadim vkotovv Kotov
♻️ License
The library is distributed under the MIT LICENSE.