text_masking_controller

This package provides a TextEditingController for TextField and TextFormField which format the input text by a costumized mask (or multiple masks) saving the cursor position.

TODO README

Add example

Example

Usage

Add the dependency into pubspec.yaml.

dependencies:
  text_masking_controller:
    git:
      url: https://github.com/Nicollas1705/text_masking_controller
      ref: master

Import the library:

import 'package:text_masking_controller/text_masking_controller.dart';

Create the controller:

final controller = TextMaskingController(mask: "00/00/0000");

Set the controller to the TextField (or TextFormField):

TextField(controller: controller),

Result

Input text: 01012000

Output text: 01/01/2000

Parameters

Multiple masks (automatically updated according to the text size)

final controller = TextMaskingController(
  masks: ["000.000.000-00", "00.000.000/0000-00"],
);

Costumizing the filters

To set a Map filter, use the key (example: "_") and the regex pattern (example: r'[01]').

final controller = TextMaskingController(
  mask: "_ _ _ _",
  filters: {"_": r'[01]'}, // Binary code
);

Initializing a text

final controller = TextMaskingController(
  masks: ["(00) 00000-0000"],
  initialText: "12345678901", // Result: (12) 34567-8901
);

Completing the mask quickly

It will complete the mask as quick as possible:

Mask example: "00--00".

When input only 2 numbers ("12"), the result will be: "12--|" (the cursor will go to the final).

Note: The cursor is represented by this character: "|" (pipe).

final controller = TextMaskingController(
  mask: "+00 (00) 00000-0000",
  maskAutoComplete: MaskAutoComplete.quick,
  initialText: "1234", // Result: +12 (34) 
);

Methods

Update to another single mask or masks

Use the "mask" parameter to update to a single mask.

Use the "masks" parameter to update to a multiple masks.

controller.updateMask(mask: "000-000");

Update the thext using updateText() method

controller.updateText("123456");

Get the default filters (it is an static method)

Map<String, String> defaultFilters = TextMaskingController.defaultFilters;

Get the current mask

It will returns the mask being used by the current text.

It can be null because the "mask" and "masks" parameters can be null.

String? mask = controller.currentMask;

Get the clean text (without the mask)

Mask example: "00-00-00".

Input example: "123456" (resulting: "12-34-56").

The unmasked text will be: "123456".

String text = controller.unmaskedText;

Check if the current mask is properly filled

Masks example: ["00-00", "0000-0000"].

Input example: "1234" (resulting: "12-34"). This is filled.

Input example: "123456" (resulting: "1234-56"). This is not filled.

bool filled = controller.isFilled;

Default filters

Key	Regex pattern	Description
0	[0-9]	Only numbers
A	[A-Z]	Upper case letters
a	[a-z]	Lower case letters
@	[a-zA-Z]	Any case letters
*	.*	Any character

Example masks

final cpfAndCnpj = TextMaskingController(
  masks: ["000.000.000-00", "00.000.000/0000-00"],
);

final brazilianPhones = TextMaskingController(
  masks: 
    "+00 (00) 00000-0000",
    "+00 (00) 0000-0000",
    "(00) 00000-0000",
    "(00) 0000-0000",
    "00000-0000",
    "0000-0000",
  ],
);

final date = TextMaskingController(mask: "00/00/0000");

Note

This package was developed based on flutter_masked_text2 and mask_text_input_formatter packages.

Main differences

Can use multiple masks easily

Just set the "masks" parameter to update the mask according to the text size.

This package saves the user cursor

The cursor will be saved even if it changes the mask from masks parameter.

Masks example: ["00-00", "000-000", "0000-0000"].

Note: The cursor will be represented by this character: "|" (pipe).

Result text from an input: "12-|34". If the user add some number (example: "123"), the result will be: "1212-3|34".

Adding each character ("123"):

Text	Input	Result
"12-\|34"	"1"	"121-\|34"
"121-\|34"	"2"	"121-2\|34"
"121-2\|34"	"3"	"1212-3\|34"

TODO

[ ] Convert lower-upper case inputs

Nowadays, the code doesn't convert the letter case.

Example:

final controller = TextMaskingController(
  mask: "AAA",
);

If the user types "abc" (lower case), the text will not be insert. It will only be insert if the user type upper case letters.

[ ] Make a way to update the mask automatically based on the first digits (not only by the text size).