datePicker

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

XML Element

datePicker

Java Class

TypedDatePicker

Basics

LIVE DEMO

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.

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 id="datePicker" label="DatePicker" datatype="localDate"/>

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-aware datePicker

LIVE DEMO

Use the dataContainer and property attributes to bind datePicker to an entity attribute. The data container provides the entity instance, and property identifies the date attribute to edit.

The following example produces a data-aware datePicker:

<data>
    <instance id="orderDc"
              class="io.jmix.uisamples.entity.Order"
              fetchPlan="_local"/>
</data>
<layout>
    <datePicker id="datePicker" label="DatePicker"
                     dataContainer="orderDc" property="date"/>
    <hbox>
        <span text="Value in the container:"/>
        <span id="spanValue"/>
    </hbox>
</layout>

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

LIVE DEMO

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 a dynamic date range within the view controller:

@ViewComponent
protected TypedDatePicker<LocalDate> datePicker;

@Subscribe
protected void onInit(InitEvent event) {
    datePicker.setMin(LocalDate.now().minusWeeks(1));
    datePicker.setMax(LocalDate.now().plusWeeks(1));
}

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>

Theme Variants

LIVE DEMO

Use the themeNames attribute to apply one or more theme variants.

Variant Description Supported By

small

Makes the component smaller.

Aura, Lumo

align-left

Aligns the field value to the left side.

Aura, Lumo

align-center

Centers the field value.

Aura, Lumo

align-right

Aligns the field value to the right side.

Aura, Lumo

helper-above-field

Renders the helper text above the field, below the label.

Aura, Lumo

Attributes

The following attributes are specific to datePicker:

Name Description Default

autoOpen

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

—

max

Specifies the latest date that can be selected.

—

min

Specifies the earliest date that can be selected.

—

name

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

—

opened

Specifies whether the calendar overlay is opened.

—

The following shared attributes are supported by datePicker:

id - alignSelf - allowedCharPattern - ariaLabel - ariaLabelledBy - classNames - clearButtonVisible - colspan - css - dataContainer - datatype - dateFormat - enabled - errorMessage - focusShortcut - height - helperText - label - maxHeight - maxWidth - minHeight - minWidth - overlayClass - placeholder - property - readOnly - required - requiredMessage - tabIndex - themeNames - visible - weekNumbersVisible - width

Handlers

The following handlers are specific to datePicker:

Name Description

ClientValidatedEvent

Fired after client-side validation changes the component’s validity.

InvalidChangeEvent

Fired when the component’s invalid state changes.

OpenedChangeEvent

Fired when the component overlay opens or closes.

validator

Validates the component value.

The following shared handlers are supported by datePicker:

AttachEvent - BlurEvent - ComponentValueChangeEvent - DetachEvent - FocusEvent - TypedValueChangeEvent - statusChangeHandler

Elements

A datePicker can include prefix, tooltip, and validator as its nested elements.

See Also