--- title: Date Input with DateField order: 13 layout: page --- [[components.datefield]] = Date Input with DateField ifdef::web[] [.sampler] image:{live-demo-image}[alt="Live Demo", link="http://demo.vaadin.com/sampler/#ui/data-input/dates/date-field"] endif::web[] The [classname]#DateField# component provides the means to display and input dates. The field comes in two variations: [classname]#DateField#, with a numeric input box and a popup calendar view, and [classname]#InlineDateField#, with the calendar view always visible. The example below illustrates the use of the [classname]#DateField#. We set the initial date of the date field to current date by using the factory method [methodname]#now# of the [classname]#java.time.LocalDate# class. [source, java] ---- // Create a DateField with the default style DateField date = new DateField(); // Set the date to present date.setValue(LocalDate.now()); ---- The result is shown in <>. [[figure.components.datefield.basic]] .[classname]#DateField# for Selecting a Date image::img/datefield-example1.png[width=35%, scaledwidth=60%] [[components.datefield.popupdatefield]] == [classname]#DateField# The [classname]#DateField# provides date input using a text box. Clicking the handle right of the date opens a popup view for selecting the year, month, and day. The Down key also opens the popup. Once opened, the user can navigate the calendar using the cursor keys. The date selected from the popup is displayed in the text box according to the default date and format of the current locale, or as specified with [methodname]#setDateFormat()#. The same format definitions are used for parsing user input. [[components.datefield.popupdatefield.format]] === Date Format The date is normally displayed according to the default format for the current locale (see <>). You can specify a custom format with [methodname]#setDateFormat()#. It takes a format string that follows the format of the [classname]#java.time.format.DateTimeFormatter# in Java. [source, java] ---- // Display only year, month, and day in ISO format date.setDateFormat("yyyy-MM-dd"); // Display the correct format as placeholder date.setPlaceholder("yyyy-mm-dd"); ---- The result is shown in <>. [[figure.components.datefield.popupdatefield.format]] .Custom Date Format for [classname]#DateField# image::img/datefield-formatting.png[width=35%, scaledwidth=60%] The same format specification is also used for parsing user-input date, as described later. [[components.datefield.popupdatefield.malformed]] === Handling Malformed User Input A user can easily input a malformed or otherwise invalid date. [classname]#DateField# has two validation layers: first on the client-side and then on the server-side. The validity of the entered date is first validated on the client-side, immediately when the input box loses focus. If the date format is invalid, the [literal]#++v-datefield-parseerror++# style is set. Whether this causes a visible indication of a problem depends on the theme. The built-in [literal]#++reindeer++# theme does not shown any indication by default, making server-side handling of the problem more convenient. [source, css] ---- .mydate.v-datefield-parseerror .v-textfield { background: pink; } ---- The [methodname]#setLenient(true)# setting enables relaxed interpretation of dates, so that invalid dates, such as February 30th or March 0th, are wrapped to the next or previous month, for example. The server-side validation phase occurs when the date value is sent to the server. If the date field is set in immediate state, it occurs immediately after the field loses focus. Once this is done and if the status is still invalid, an error indicator is displayed beside the component. Hovering the mouse pointer over the indicator shows the error message. You can handle the errors by overriding the [methodname]#handleUnparsableDateString()# method. The method gets the user input as a string parameter and can provide a custom parsing mechanism, as shown in the following example. [source, java] ---- // Create a date field with a custom parsing and a // custom error message for invalid format DateField date = new DateField("My Date") { @Override protected Result handleUnparsableDateString( String dateString) { try { // try to parse with alternative format LocalDate parsedAtServer = LocalDate.parse(dateString, DateTimeFormatter.ISO_DATE); return Result.ok(parsedAtServer); } catch (DateTimeParseException e) { return Result.error("Bad date"); } } }; // Display only year, month, and day in slash-delimited format date.setDateFormat("yyyy/MM/dd"); // Don't be too tight about the validity of dates // on the client-side date.setLenient(true); ---- [[components.datefield.popupdatefield.css]] === CSS Style Rules [source, css] ---- .v-datefield, v-datefield-popupcalendar {} .v-textfield, v-datefield-textfield {} .v-datefield-button {} ---- The top-level element of [classname]#DateField# and [classname]#InlineDateField# have [literal]#++v-datefield++# style. The [classname]#DateField# also has the [literal]#++v-datefield-popupcalendar++# style. In addition, the top-level element has a style that indicates the resolution, with [literal]#++v-datefield-++# basename and an extension, which is one of [literal]#++full++#, [literal]#++day++#, [literal]#++month++#, or [literal]#++year++#. The [literal]#++-full++# style is enabled when the resolution is smaller than a day. These styles are used mainly for controlling the appearance of the popup calendar. The text box has [literal]#++v-textfield++# and [literal]#++v-datefield-textfield++# styles, and the calendar button [literal]#++v-datefield-button++#. Once opened, the calendar popup has the following styles at the top level: [source, css] ---- .v-datefield-popup {} .v-popupcontent {} .v-datefield-calendarpanel {} ---- The top-level element of the floating popup calendar has [literal]#++.v-datefield-popup++# style. Observe that the popup frame is outside the HTML structure of the component, hence it is not enclosed in the [literal]#++v-datefield++# element and does not include any custom styles. // NOTE: May be changed in #5752. The content in the [literal]#++v-datefield-calendarpanel++# is the same as in [classname]#InlineDateField#, as described in <>. [[components.datefield.calendar]] == [classname]#InlineDateField# The [classname]#InlineDateField# provides a date picker component with a month view. The user can navigate months and years by clicking the appropriate arrows. Unlike with the pop-up variant, the month view is always visible in the inline field. [source, java] ---- // Create a DateField with the default style InlineDateField date = new InlineDateField(); // Set the date to present date.setValue(LocalDate.now()); ---- The result is shown in <>. [[figure.components.datefield.inlinedatefield]] .Example of the [classname]#InlineDateField# image::img/datefield-inlinedatefield.png[width=35%, scaledwidth=60%] The user can also navigate the calendar using the cursor keys. === CSS Style Rules [source, css] ---- .v-datefield {} .v-datefield-calendarpanel {} .v-datefield-calendarpanel-header {} .v-datefield-calendarpanel-prevyear {} .v-datefield-calendarpanel-prevmonth {} .v-datefield-calendarpanel-month {} .v-datefield-calendarpanel-nextmonth {} .v-datefield-calendarpanel-nextyear {} .v-datefield-calendarpanel-body {} .v-datefield-calendarpanel-weekdays, .v-datefield-calendarpanel-weeknumbers {} .v-first {} .v-last {} .v-datefield-calendarpanel-weeknumber {} .v-datefield-calendarpanel-day {} ---- The top-level element has the [literal]#++v-datefield++# style. In addition, the top-level element has a style name that indicates the resolution of the calendar, with [literal]#++v-datefield-++# basename and an extension, which is one of [literal]#++full++#, [literal]#++day++#, [literal]#++month++#, or [literal]#++year++#. The [literal]#++-full++# style is enabled when the resolution is smaller than a day. The [literal]#++v-datefield-calendarpanel-weeknumbers++# and [literal]#++v-datefield-calendarpanel-weeknumber++# styles are enabled when the week numbers are enabled. The former controls the appearance of the weekday header and the latter the actual week numbers. The other style names should be self-explanatory. For weekdays, the [literal]#++v-first++# and [literal]#++v-last++# styles allow making rounded endings for the weekday bar. [[components.datefield.resolution]] == Date Resolution In addition to display a calendar with dates, [classname]#DateField# can also display just the month or year. The visibility of the input components is controlled by [methodname]#setDateResolution()#, which you can set with [methodname]#setResolution()#. The method takes as its parameter the highest resolution date element that should be visible. Please see the API Reference for the complete list of resolution parameters. [[components.datefield.locale]] == DateField Locale The date is displayed according to the locale of the user, as reported by the browser. You can set a custom locale with the [methodname]#setLocale()# method of [classname]#AbstractComponent#, as described in <>. Only Gregorian calendar is supported. [[components.datefield.weeknumbers]] == Week Numbers You can enable week numbers in a date field with [methodname]#setShowISOWeekNumbers()#. The numbers are shown according to the ISO 8601 standard in a column on the left side of the field.