java.time.format.DateTimeFormatterBuilder Class in Java

Last Updated : 13 Jul, 2026

The DateTimeFormatterBuilder class in the java.time.format package is a builder class used to create custom DateTimeFormatter objects. It provides a flexible way to define complex date-time formatting and parsing rules by combining multiple formatting elements.

  • Allows combining multiple formatting elements into a single formatter.
  • Supports optional sections for flexible parsing.
  • Enables adding custom literals, date-time fields, and patterns.

Syntax

public final class DateTimeFormatterBuilder
extends Object

Constructors of DateTimeFormatterBuilder Class

ConstructorDescription
DateTimeFormatterBuilder()Constructs a new instance of the builder.

Approach

  • Import the required classes from the java.time and java.time.format packages.
  • Create a DateTimeFormatterBuilder object.
  • Append the required date/time fields, patterns, or literals.
  • Convert the builder into a DateTimeFormatter using toFormatter().
  • Format or parse date-time values using the formatter.

Example 1: Java Program to Illustrate DateTimeFormatterBuilder class by invoking appendValue() Method of this class

Java
// Importing required classes from respective packages
import java.io.*;
import java.lang.*;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import java.time.format.DateTimeFormatterBuilder;
import java.time.format.TextStyle;
import java.time.temporal.ChronoField;

// Main class
public class GFG {

    // Main driver method
    public static void main(String[] args)
    {
        // Creating an object of this class
        // inside main() method
        DateTimeFormatterBuilder builder
            = new DateTimeFormatterBuilder();

        // Now creating object of DateTimeFormatter class
        // over which appendValue() method is invoked
        DateTimeFormatter formatter
            = builder.appendLiteral("Day is:")
                  .appendValue(ChronoField.DAY_OF_MONTH)
                  .appendLiteral(", Month is:")
                  .appendValue(ChronoField.MONTH_OF_YEAR)
                  .toFormatter();

        // Creating object of LocalDateTime class
        // invoking now() method over it
        LocalDateTime dateTime = LocalDateTime.now();

        // Formatting the date and lately
        // storing it in a string
        String str = dateTime.format(formatter);

        // Print and display the day and month
        System.out.println(str);
    }
}

Output
Day is:2, Month is:2

Explanation: This example creates a custom formatter using appendLiteral() and appendValue(). It formats the current date by displaying the day and month with custom labels.

Example 2: Using optionalStart() and optionalEnd() Methods

Java
// Importing required libraries
import java.io.*;
import java.lang.*;
import java.time.LocalDate;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import java.time.format.DateTimeFormatterBuilder;
import java.time.temporal.ChronoField;

// Main class
public class GFG {

    // Main driver methods
    public static void main(String[] args)
    {

        // Creating an object of DateTimeFormatter class
        DateTimeFormatter parser
            = new DateTimeFormatterBuilder()
                  .appendPattern("[yyyy][yyyyMM][yyyyMMdd]")
                  .optionalStart()
                  .parseDefaulting(
                      ChronoField.MONTH_OF_YEAR, 1)
                  .parseDefaulting(ChronoField.DAY_OF_MONTH,
                                   1)
                  .optionalEnd()
                  .toFormatter();

        // Print and display statements

        // Execute if only year is given in parameter
        System.out.println(
            parser.parse("2021", LocalDate::from));

        // Execute if year and month is given
        System.out.println(
            parser.parse("202106", LocalDate::from));

        // Execute if year, month and date is given
        System.out.println(
            parser.parse("20210631", LocalDate::from));
    }
}

Output
2021-01-01
2021-06-01
2021-06-30

Explanation: This example demonstrates optional parsing sections. The formatter accepts input in multiple formats (yyyy, yyyyMM, and yyyyMMdd). Missing month and day values are automatically assigned default values using parseDefaulting().

Example 3: Java Program to illustrate DateTimeFormatterBuilder Class

Java
// Importing required classes
import java.io.*;
import java.lang.*;
import java.time.LocalDate;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import java.time.format.DateTimeFormatterBuilder;
import java.time.format.TextStyle;
import java.time.temporal.ChronoField;
import java.util.Locale;

// Main class
// DateTimeFormatterBuilderExample
class GFG {

    // Main driver method
    public static void main(String[] args)
    {
        // Creating object of LocalDate class
        // inside main() method
        LocalDate date = LocalDate.of(2021, 6, 30);

        // Creating object of DateTimeFormatter class

        // Object 1
        DateTimeFormatter formatter
            = DateTimeFormatter.ofPattern("dd/MM/yyyy");

        // Object 2
        DateTimeFormatter italianFormatter
            = DateTimeFormatter.ofPattern("d. MMMM yyyy",
                                          Locale.ITALIAN);

        // Print and display date in format XX-XX-XX
        System.out.println(
            date.format(DateTimeFormatter.ISO_LOCAL_DATE));

        // Print and display date in format XX/XX/XX
        System.out.println(date.format(formatter));

        // Print and display Italian date formatter
        System.out.println(date.format(italianFormatter));

        // Object 3
        DateTimeFormatter complexFormatter
            = new DateTimeFormatterBuilder()
                  .appendText(ChronoField.DAY_OF_MONTH)
                  .appendLiteral(". ")
                  .appendText(ChronoField.MONTH_OF_YEAR)
                  .appendLiteral(" ")
                  .appendText(ChronoField.YEAR)
                  .parseCaseInsensitive()
                  .toFormatter(Locale.US);

        // Print and display US date formatter
        System.out.println(date.format(complexFormatter));
    }
}

Output
2021-06-30
30/06/2021
30. giugno 2021
30. June 2021

Explanation: This example demonstrates different ways to format a date. It uses predefined patterns, locale-specific formatting, and a custom formatter built using DateTimeFormatterBuilder to display the date in different formats.

Common Methods of DateTimeFormatterBuilder

They are pictorially depicted below in tabular format in alphabetical alongside the action performed by them which are as follows:

MethodsAction Performed 
append(DateTimeFormatter formatter)Appends all the elements of a formatter to the builder.
appendChronologyId()Appends the chronology ID, such as 'ISO' or 'ThaiBuddhist', to the formatter.
appendChronologyText(TextStyle textStyle)Appends the chronology name to the formatter.
appendFraction(TemporalField field, int minWidth, int maxWidth, boolean decimalPoint)Appends the fractional value of a date-time field to the formatter.
appendInstant()Appends an instant using ISO-8601 to the formatter, formatting fractional digits in groups of three.
appendInstant(int fractionalDigits)Appends an instant using ISO-8601 to the formatter with control over the number of fractional digits.
appendLiteral(char literal)Appends a character literal to the formatter.
appendLiteral(String literal)Appends a string literal to the formatter.
appendLocalized(FormatStyle dateStyle, FormatStyle timeStyle)Appends a localized date-time pattern to the formatter.
appendLocalizedOffset(TextStyle style)Appends the localized zone offset, such as 'GMT+01:00', to the formatter.
appendOffset(String pattern, String noOffsetText)Appends the zone offset, such as '+01:00', to the formatter.
appendOffsetId()Appends the zone offset, such as '+01:00', to the formatter.
appendOptional(DateTimeFormatter formatter)Appends a formatter to the builder which will optionally format/parse.
appendPattern(String pattern)Appends the elements defined by the specified pattern to the builder.
appendText(TemporalField field)Appends the text of a date-time field to the formatter using the full-text style.
appendText(TemporalField field, Map<Long,String> textLookup)Appends the text of a date-time field to the formatter using the specified map to supply the text.
appendText(TemporalField field, TextStyle textStyle)Appends the text of a date-time field to the formatter.
appendValue(TemporalField field)Appends the value of a date-time field to the formatter using a normal output style.
appendValue(TemporalField field, int width)Appends the value of a date-time field to the formatter using a fixed width, zero-padded approach.
appendValue(TemporalField field, int minWidth, int maxWidth, SignStyle signStyle)Appends the value of a date-time field to the formatter providing full control over formatting.
appendValueReduced(TemporalField field, int width, int maxWidth, ChronoLocalDate baseDate)Appends the reduced value of a date-time field to the formatter.
appendValueReduced(TemporalField field, int width, int maxWidth, int baseValue)Appends the reduced value of a date-time field to the formatter.
appendZoneId()Appends the time-zone ID, such as 'Europe/Paris' or '+02:00', to the formatter.
appendZoneOrOffsetId()Appends the time-zone ID, such as 'Europe/Paris' or '+02:00', to the formatter, using the best available zone ID.
appendZoneRegionId()Appends the time-zone region ID, such as 'Europe/Paris', to the formatter, rejecting the zone ID if it is a ZoneOffset
appendZoneText(TextStyle textStyle)Appends the time-zone name, such as 'British Summer Time', to the formatter.
appendZoneText(TextStyle textStyle, Set<ZoneId> preferredZones)Appends the time-zone name, such as 'British Summer Time', to the formatter.
getLocalizedDateTimePattern()Gets the formatting pattern for date and time styles for a locale and chronology.
optionalEnd()Ends an optional section.
optionalStart()Mark the start of an optional section.
padNext(int padWidth)Causes the next added printer/parser to pad to a fixed width using a space.
padNext(int padWidth, char padChar)Causes the next added printer/parser to pad to a fixed width.
parseCaseInsensitive()Changes the parse style to be case insensitive for the remainder of the formatter.
parseCaseSensitive()Changes the parse style to be case-sensitive for the remainder of the formatter.
parseDefaulting()Appends a default value for a field to the formatter for use in parsing.
parseLenient()Changes the parse style to be lenient for the remainder of the formatter.
parseStrict()Changes the parse style to be strict for the remainder of the formatter.
 toFormatter()Completes this builder by creating the DateTimeFormatter using the default locale.
toFormatter(Locale locale)Completes this builder by creating the DateTimeFormatter using the specified locale.

Advantages of DateTimeFormatterBuilder

  • Creates highly customizable date-time formatters.
  • Supports both formatting and parsing operations.
  • Allows optional fields and multiple input formats.
  • Supports locale-specific formatting.
  • Provides greater flexibility than DateTimeFormatter.ofPattern().
  • Immutable formatters created by the builder are thread-safe and reusable.
Comment