CE
PE
EE

since 11.0.0

Employment/Purpose

Daterangebox lets a user enter or choose a begin and end date in one component. Its popup displays multiple calendar panels, making it suitable for travel dates, reporting periods, reservations, and date-range filters.

Example

<daterangebox value="@bind(vm.period)"
              format="yyyy/MM/dd"
              numberOfMonths="2"
              minNights="1"
              maxNights="30"
              placeholder="Select a date range"/>

The value is an org.zkoss.zul.DateRange, whose begin and end values are inclusive.

Working with Values

Use value to read or replace both endpoints atomically. You can also bind beginValue and endValue separately (see Data Binding).

DateRange range = daterangebox.getValue();
Date begin = range.getBegin();
Date end = range.getEnd();

daterangebox.setValue(DateRange.of(begin, end));

Java Time variants are available for LocalDate, LocalDateTime, and ZonedDateTime. For example, use getValueInLocalDate() and setValueInLocalDate(LocalDateRange) when the application works with calendar dates rather than java.util.Date.

Data Binding

Every value property supports two-way MVVM binding with @bind, @load, and @save. Pick the property that matches the type your ViewModel uses: either the whole range in one property, or the begin and end values in two separate properties.

Type Whole range Begin and end separately
java.util.Date value (DateRange) beginValue, endValue
java.time.LocalDate valueInLocalDate (LocalDateRange) beginValueInLocalDate, endValueInLocalDate
java.time.LocalDateTime valueInLocalDateTime (LocalDateTimeRange) beginValueInLocalDateTime, endValueInLocalDateTime
java.time.ZonedDateTime valueInZonedDateTime (ZonedDateTimeRange) beginValueInZonedDateTime, endValueInZonedDateTime

All of them are saved to the ViewModel on onChange, that is, once the user commits a range, not while the range is being picked. When the begin and end values are bound separately, both are saved on the same onChange.

<daterangebox beginValueInLocalDate="@bind(vm.checkIn)"
              endValueInLocalDate="@bind(vm.checkOut)"/>

public class BookingVM {
    private LocalDate checkIn = LocalDate.now();
    private LocalDate checkOut = LocalDate.now().plusDays(3);

    public LocalDate getCheckIn() { return checkIn; }
    public void setCheckIn(LocalDate checkIn) { this.checkIn = checkIn; }

    public LocalDate getCheckOut() { return checkOut; }
    public void setCheckOut(LocalDate checkOut) { this.checkOut = checkOut; }
}

Properties

Format, Locale, and TimeZone

format applies the same SimpleDateFormat pattern to both inputs. Without an explicit pattern, the component uses a locale-sensitive medium date format. locale and timeZone control parsing and display.

When showTime="true", the popup includes time selection. If the format has no time field, the effective format adds HH:mm.

NumberOfMonths

Default Value: 2

Sets the number of side-by-side calendar panels. It accepts 1 through the configured maximum, which defaults to 12.

AllowEmpty

Default Value: both

Controls which endpoint may be empty:

Value Meaning
none Both endpoints are required.
begin Only the begin endpoint may be empty.
end Only the end endpoint may be empty.
both Either endpoint may be empty.

MinNights and MaxNights

Both values default to 0. minNights sets the minimum calendar-day difference; maxNights sets the maximum. A zero maximum means unlimited.

<daterangebox minNights="2" maxNights="14"/>

Constraint

The component applies a SimpleDateConstraint to both endpoints. Rules such as no past, no future, before, after, and between work as they do for Datebox.

Property Default Description
position after_start Popup position relative to the input.
buttonVisible true Shows the calendar button.
weekOfYear false Shows week numbers.
showTodayLink false Shows a localized Today shortcut.
open false Opens or closes the popup programmatically.
hoverPreview true Previews a range while choosing its end.
readonly false Prevents typing; the popup can still open and a selection can still update the value.
disabled false Disables interaction.
lenient true Allows lenient parsing.
strictDate false Rejects impossible dates such as November 31.

separator defaults to ~. placeholder applies to both inputs; beginPlaceholder and endPlaceholder override it for one endpoint.

Global Defaults

Set commonly used defaults with library properties:

<library-property>
    <name>org.zkoss.zul.daterangebox.numberOfMonths</name>
    <value>2</value>
</library-property>
<library-property>
    <name>org.zkoss.zul.daterangebox.numberOfMonths.max</name>
    <value>12</value>
</library-property>
<library-property>
    <name>org.zkoss.zul.daterangebox.hoverPreview</name>
    <value>true</value>
</library-property>
<library-property>
    <name>org.zkoss.zul.daterangebox.separator</name>
    <value>~</value>
</library-property>

numberOfMonths.max cannot exceed the framework’s safety ceiling of 24.

Supported Events

Name Event Type
onChange Event: Daterangebox.RangeChangeEvent Fired after a committed change. Read getRange(), getBegin(), or getEnd().
onChanging Event: Daterangebox.RangeChangeEvent Fired while the user changes the range.
onOpen Event: org.zkoss.zk.ui.event.OpenEvent Fired when the popup opens or closes.
onError Event: org.zkoss.zk.ui.event.ErrorEvent Fired for invalid input.

RangeChangeEvent is not an InputEvent; do not read event.value. MVVM binding continues to work through the value properties listed in Data Binding.

Supported Children

*NONE

Daterangebox manages its input fields and popup content internally, so it does not accept child components.