datePicker

datePicker lets users enter a date by typing or select it using a calendar overlay.

  • XML element: datePicker

  • Java class: TypedDatePicker

Basics

Unlike a regular input field, datePicker has a calendar button and a calendar overlay. The calendar opens when the user clicks the button or the field itself, or starts entering a date.

date picker

The calendar is scrollable and allows selecting a year in the right pane. Click Today at the bottom to navigate back to the current date.

The following example defines a datePicker with a label:

<datePicker label="Select date"/>

Data Types

datePicker is a typed component which supports common data types for storing a date:

  • date

  • dateTime

  • localDateTime

  • offsetDateTime

  • localDate

When you bind the component to an entity attribute, it will automatically assume the data type of that attribute. To set the type explicitly, use the datatype attribute.

Data Binding

Data binding refers to linking a visual component to a data container. Changes in the visual component or corresponding data container can trigger updates to one another. See Использование компонентов данных for more details.

The following example produces a data-aware datePicker:

<datePicker dataContainer="userStepDc" property="dueDate"/>

Date Format

The default date and time format in the application is defined by the localized format strings. To use a different format, add your own format strings to the message bundle.

To change the format for a particular component, use its dateFormat attribute.

Date Range

To restrict the input to a specific date range, specify the minimum and maximum dates using the max and min attributes:

<datePicker id="datePicker" min="2024-01-01" max="2024-12-31"/>

Or specify an adaptable data range within the view controller:

@ViewComponent
private TypedDatePicker<Comparable> datePicker;

@Subscribe
public void onInit(InitEvent event) {
    datePicker.setMin(LocalDate.now());
    datePicker.setMax(LocalDate.now().plusDays(7));
}

Theme Variants

Use the themeNames attribute to adjust date alignment, helper text placement, and component size.

Alignment

Choose among three alignment options: align-left (default), align-right, align-center.

date picker alignment
XML code
<datePicker themeNames="align-left"/>
<datePicker themeNames="align-center"/>
<datePicker themeNames="align-right"/>

Helper Text Position

Setting helper-above-field will move the helper text from its default position below the field to above it.

date picker helper text position
XML code
<datePicker label="Date picker label" helperText="Helper text"/>
<datePicker themeNames="helper-above-field" label="Date picker label" helperText="Helper text"/>

Size

Two size options are available: the default size and small.

date picker size
XML code
<datePicker/>
<datePicker themeNames="small"/>

Validation

To check values entered into datePicker, add a validator element. This allows adding a custom validation criterion or select one of the following predefined validators:

This example demonstrates how to use the FutureValidator to ensure that the selected date is in the future:

<datePicker label="Select a future date"
            datatype="date">
    <validators>
        <future/>
    </validators>
</datePicker>

Attributes

autoOpen

Defines whether an overlay calendar opens when the user starts typing a date.

  • If set to true, an overlay calendar opens both on user input and on clicking the calendar button or the field.

  • If set to false, an overlay calendar opens only on clicking the calendar button.

max

Specifies the latest date that can be selected. Accepted format is yyyy-MM-dd.

min

Specifies the earliest date that can be selected. Accepted format is yyyy-MM-dd.

name

Specifies a name for an HTML element that can be used to reference the component.

opened

Specifies whether the calendar overlay is opened.

Handlers

Чтобы сгенерировать заглушку обработчика в Jmix Studio, используйте вкладку Handlers панели инспектора Jmix UI, или команду Generate Handler, доступную на верхней панели контроллера экрана и через меню CodeGenerate (Alt+Insert / Cmd+N).

ClientValidatedEvent

ClientValidatedEvent is sent by the web component whenever it is validated on the client-side.

InvalidChangeEvent

com.vaadin.flow.component.datepicker.DatePicker.InvalidChangeEvent is sent when the value of the invalid attribute of the component changes.

OpenedChangeEvent

OpenedChangeEvent is sent every time the opened attribute of the component changes. That is, when the calendar is opened or closed.

validator

Adds a validator instance to the component. The validator must throw ValidationException if the value is not valid. For example:

@Install(to = "birthDatePicker", subject = "validator")
private void birthDatePickerValidator(Date date) {
        Date now = timeSource.currentTimestamp();
        if (date != null && DateUtils.addYears(now,-18).compareTo(date) < 0) {
            throw new ValidationException("The age must be over 18 years");
        }
}

Elements

See Also

See Vaadin Docs for more information.