Java Swing Tutorial - Java Swing JFormattedTextField

A JFormattedTextField is a JTextField with formatting functions.

We can specify the format in which the text will be edited and displayed. We can specify a format in case the value is null.

JFormattedTextField offers two new methods called getValue() and setValue() to accept any type of data instead of just text.

The JFormattedTextField has three preconfigured format:

  • numbers
  • dates
  • strings

We can also customize the JFormattedTextField to format any object.

The following table lists the constructors of the JFormattedTextField Class.

Creates a JFormattedTextField with no formatter. we need to use its setFormatterFactory() or setValue() method to set a formatter.
2JFormattedTextField(Format format)
Creates a JFormattedTextField and it will use the specified format to format the text in the field.
3JFormattedTextField( JFormattedTextField.AbstractFormatter formatter)
Creates a JFormattedTextField with the specified formatter.
4JFormattedTextField(JFormattedTextField. AbstractFormatterFactory factory)
Creates a JFormattedTextField with the specified factory.
5JFormattedTextField( JFormattedTextField.AbstractFormatterFactory factory, Object initialValue)
Creates a JFormattedTextField with the specified factory and the specified an initial value.
6JFormattedTextField(Object value)
Creates a JFormattedTextField with the specified value.

A java.text.Format object defines the format of an object in a string form. For example, a date object in mm/dd/yyyy format would look like 07/20/2014.

A formatter is represented by a JFormattedTextField.AbstractFormatter object and it uses a java.text.Format object to format an object.

A formatter factory is a collection of formatters. A formatter factory object is represented by an instance of the JFormattedTextField.AbstractFormatterFactory class.

The JFormattedTextField knows what default formatter to use based on the value type passed in. If the value passed in through setValue() method is a Date time, it would use the default date formatter.

The following code formats the text in it as a date using the current locale format:

JFormattedTextField  dobField = new JFormattedTextField();
dobField.setValue(new Date());

The following code formats a number in the current locale format:

JFormattedTextField salaryField  = new JFormattedTextField();
salaryField.setValue(new  Double(12345.98));

We can create a JFormattedTextField with a formatter. We can use the DateFormatter, NumberFormatter, and MaskFormatter classes to format a date, a number, and a string, respectively.

These classes are in the javax.swing.text package.

The following code creates a JFormattedTextField to format a date in mm/dd/yyyy format

DateFormat  dateFormat = new SimpleDateFormat("mm/dd/yyyy"); 
DateFormatter dateFormatter  = new DateFormatter(dateFormat); 
dobField = new JFormattedTextField(dateFormatter);

The following code creates a JFormattedTextField to format a number in $#0,000.00 format.

NumberFormat numFormat = new DecimalFormat("$#0,000.00"); 
NumberFormatter  numFormatter  = new NumberFormatter(numFormat); 
salaryField = new JFormattedTextField(numFormatter);

Custom Format

The following table lists special characters we can use to create a custom format.

#A number
?A letter
AA letter or a number
U A letter, with lowercase characters mapped to their uppercase equivalents
LA letter, with uppercase characters mapped to their lowercase equivalents
H A hexadecimal digit (A-F, a-f, 0-9)
'A single quote. It is an escape character that is used to escape any of the special formatting characters.

The following code creates a format for a social security number in the ###-##-#### format.

MaskFormatter ssnFormatter  = null; 
JFormattedTextField ssnField  = null; 
try  {
    ssnFormatter = new MaskFormatter("###-##-####");
    ssnField = new JFormattedTextField(ssnFormatter);
catch (ParseException e)  {

The code above would not show any place holder mask. It displays space and - as " - - ".

To display 000-00-0000 in a SNN field, we need to use '0' as a placeholder character for the mast formatter.

ssnFormatter = new MaskFormatter("###-##-####");


We can use the setFormatterFactory() method from JFormattedTextField to install the formatter.

DateFormatter df  = new DateFormatter(new SimpleDateFormat("mm/dd/yyyy")); DefaultFormatterFactory dff  = new DefaultFormatterFactory(df, df, df, df); dobField.setFormatterFactory(dff);

A JFormattedTextField can accept four types of formatters:

  • A null formatter: used when the value in the field is null.
  • An edit Formatter: used when the field has focus.
  • A display Formatter: used when the field does not have focus with a non-null value.
  • A default Formatter: used in the absence of any of the above three formatters.

The following code shows how to install differents formatter for a JFormattedTextField.

DateFormatter df  = new DateFormatter(new SimpleDateFormat("mmmm dd, yyyy")); 
DateFormatter edf  = new DateFormatter(new SimpleDateFormat("mm/dd/yyyy")); 

DefaultFormatterFactory ddf  = new DefaultFormatterFactory(df, df, edf, df); dobField.setFormatterFactory(ddf);

If we have configured the JFormattedTextField to format a date, we can use its getValue() method to get a Date object.

To overwrite the value in the field as we type, we need to set the formatter in overwrite mode by using the method setOverwriteMode(true).

To use a JFormattedTextField to limit the number of characters that can be entered in a field, set a mask formatter with * mask.

To accept only two characters, use the following code

JFormattedTextField  twoCharField = new JFormattedTextField(new MaskFormatter("**"));