JEP draft: JEP: Add a JDatePicker UI Component to the Swing UI Toolkit (Preview)

OwnerTejesh R
TypeFeature
ScopeSE
StatusDraft
Componentclient-libs / javax.swing
Discussionclient dash libs dash dev at openjdk dot org
EffortM
DurationM
Created2025/09/29 13:55
Updated2025/09/30 04:14
Issue8368874

Summary

Add to the Swing UI toolkit a JDatePicker component which has an intuitive UI, an easy-to-use API and supports a wide range of common use cases, such as picking a single day or range of days from a month calendar.

This is a Preview API (see https://openjdk.org/jeps/12)

Goals

Non-Goals

Motivation

Many UI applications have a need to allow the user to select a date, or a range of dates.     Swing has a rich set of UI components but lacks such a Date Picker.     The need for this in Swing was recognised a long time ago and there was a prototype in the now abandoned SwingX project.     The continued need for this is demonstrated by applications resorting to 3rd party solutions. These have various limitations.     Swing developers have indicated (Seeking feedback on a possible JDatePicker Swing component) that if a DatePicker with required features were available as a standard Swing component that they would adopt it.

Description

The proposal is to add new public APIs implementing a Date Picker to the existing javax.swing package. These APIs will provide a JDatePicker UI component which allows a user to select a date from a calendar view.

The core components of this JDatePicker are:

The Date Picker is designed to be either embedded in a container or to be used via a popup dialog API. A user selected date from the calendar view is copied to the textfield provided by Date Picker, and vice versa. Both are initialised either with an initial value either set by the application or by a default date which is the current date. The calendar view will always be a month view and supports display of year, month, weeks, and days of the week. Forward and backward navigation buttons provide navigation through month/year, one count on every click. Month and Year can be selected by respective panels which opens up when clicked on Month/Year Label.

DateSelectionModel interface defines methods for handling date(s) selection and also allows event listeners to be notified when a date is selected. AbstractCalendarPanel provides options for user to extend it and create a custom calendar panel, JDatePicker provide in-built BasicCalendarPanelUI class for date selection.

JDatePicker provides APIs to

Sample code references:

Set single selection mode and get a date:

JDatePicker datePicker = new JDatePicker();

datePicker.setSelectionMode(DateSelectionModel.SelectionMode.SINGLE_SELECTION); 
 ChangeListener changeListener = new ChangeListener() {
        public void stateChanged(ChangeEvent e) {
                LocalDate date = datePicker.getDate();

               System.out.println("Selected date : " + date);

        }
};
datePicker.getCalendarPanel().getDateSelectionModel().addChangeListener(l);

Set range selection mode and get range of date(start and end range):

JDatePicker datePicker = new JDatePicker();
datePicker.setSelectionMode(DateSelectionModel.SelectionMode.RANGE_SELECTION); 
 ChangeListener changeListener = new ChangeListener() {
        public void stateChanged(ChangeEvent e) {
                SortedSet<LocalDate> dates = datePicker.getDates();
                 System.out.println("First date : " + dates.getFirst());
                 System.out.println("Last date : " + dates.getLast());
        }
};

Set initial date through API:

JDatePicker datePicker = new JDatePicker();
datePicker.getCalendarPanel().setDate(LocalDate.of(2025, Month.AUGUST, 25));

Set year selection scroll limit to 200 years before current year and 200 years after current year:

JDatePicker datePicker = new JDatePicker();
datePicker.getCalendarPanel().setYearSelectionLimit(200);

Set text field formatter:

JDatePicker datePicker = new JDatePicker();
datePicker.setTextFieldFormatter(DateTimeFormatter.ISO_WEEK_DATE);

UI references:

Alternatives

Testing

New tests need to be created to test this new Swing component, this includes but is not limited to:

As a demonstration, SwingSet2 will be enhanced to have a Date Picker tab.