DatePicker

DatePicker provides an interactive calendar interface for selecting single dates or date ranges, with customizable formatting and validation options. It displays a text input that opens a calendar popup when clicked, offering both keyboard and mouse interaction.

Key features:

• Flexible modes: Single date selection (default) or date range selection
• Format customization: Support for various date formats (MM/dd/yyyy, yyyy-MM-dd, etc.)
• Date restrictions: Set minimum/maximum dates and disable specific dates
• Localization options: Configure first day of week and show week numbers

Context variables available during execution:

• value: Current value. Single mode returns a string; range mode returns { from, to }.

Behaviors

This component supports the following behaviors:

Properties

autoFocus

default: false

If this property is set to true, the component gets the focus automatically when displayed.

clearable

default: false

Set to true to show a clear button that resets the value. Hidden by default.

confirmRangeSelection

default: false

In range mode, show a Cancel/Proceed footer so the user must explicitly confirm the selected range before it is committed. When false (default), the range auto-commits on the second click and the popup closes.

dateFormat

default: "MM/dd/yyyy"

The format of the date displayed in the input field

Available values: MM/dd/yyyy (default), MM-dd-yyyy, yyyy/MM/dd, yyyy-MM-dd, dd/MM/yyyy, dd-MM-yyyy, yyyyMMdd, MMddyyyy

Formats handle years (y), months (m or M), days of the month (d). Providing multiple placeholder letters changes the display of the date.

The table below shows the available date formats:

<App>
  <DatePicker
    dateFormat="dd-MM-yyyy"
    initialValue="01-01-2024"
    endDate="01-01-2027"
/>
</App>

<App>
  <DatePicker
    dateFormat="dd-MM-yyyy"
    initialValue="01-01-2024"
    endDate="01-01-2027"
/>
</App>

disabledDates

An optional array of dates that are to be disabled. Accepts a date string, { from, to }, { before }, { after }, { before, after }, or { dayOfWeek } matchers (parsed with dateFormat).

The disabledDates prop supports multiple patterns for disabling specific dates in the calendar. You can use Date objects, strings (parsed using the dateFormat), or complex matcher objects.

Basic patterns:

You can use the getDate() function to query the current date.

<App>
  <DatePicker
    disabledDates="{['05/26/2024', '05/27/2024']}"
    initialValue="05/25/2024" />
</App>

<App>
  <DatePicker
    disabledDates="{['05/26/2024', '05/27/2024']}"
    initialValue="05/25/2024" />
</App>

Advanced patterns:

<App>
  <DatePicker disabledDates="{{dayOfWeek: [0, 6]}}" />
</App>

<App>
  <DatePicker disabledDates="{{dayOfWeek: [0, 6]}}" />
</App>

<App>
  <DatePicker
    disabledDates="{{from: '05/20/2024', to: '05/25/2024'}}"
    initialValue="05/18/2024" />
</App>

<App>
  <DatePicker
    disabledDates="{{from: '05/20/2024', to: '05/25/2024'}}"
    initialValue="05/18/2024" />
</App>

<App>
  <DatePicker
    disabledDates="{{before: getDate()}}"
    initialValue="{getDate()}"/>
</App>

<App>
  <DatePicker
    disabledDates="{{before: getDate()}}"
    initialValue="{getDate()}"/>
</App>

<App>
  <DatePicker
    disabledDates="{[getDate(), {after: getDate()}]}"
    initialValue="{getDate()}"/>
</App>

<App>
  <DatePicker
    disabledDates="{[getDate(), {after: getDate()}]}"
    initialValue="{getDate()}"/>
</App>

<App>
  <DatePicker
    disabledDates="{[
    {dayOfWeek: [0, 6]},
    {from: '12/24/2024', to: '12/26/2024'},
    '01/01/2025']}"
    initialValue="12/20/2024"
/>
</App>

<App>
  <DatePicker
    disabledDates="{[
    {dayOfWeek: [0, 6]},
    {from: '12/24/2024', to: '12/26/2024'},
    '01/01/2025']}"
    initialValue="12/20/2024"
/>
</App>

enabled

default: true

This boolean property value indicates whether the component responds to user events (true) or not (false).

<App>
  <DatePicker enabled="false" />
</App>

<App>
  <DatePicker enabled="false" />
</App>

endDate

The latest month to start the month navigation from (inclusive). If not defined, the component allows any future dates. Accepts the same date format as the initialValue. Example: '2023-12-31' ensures the last month to select a date from is December 2023.

endIcon

This property sets an optional icon to appear on the end (right side when the left-to-right direction is set) of the input.

endText

This property sets an optional text to appear on the end (right side when the left-to-right direction is set) of the input.

initialValue

This property sets the component's initial value.

<App>
  <DatePicker initialValue="05/25/2024" />
</App>

<App>
  <DatePicker initialValue="05/25/2024" />
</App>

inline

default: false

If set to true, the calendar is always visible and its panel is rendered as part of the layout. If false, the calendar is shown in a popup when the input is focused or clicked.

invalidMessages

The invalid messages to display in the concise validation summary.

label

Optional label rendered above the input.

locale

default: "en-US"

BCP 47 locale used for calendar labels.

mode

default: "single"

The mode of the datepicker (single or range)

Available values: single (default), range

<App>
  <DatePicker mode="single" />
  <DatePicker mode="range" />
</App>

<App>
  <DatePicker mode="single" />
  <DatePicker mode="range" />
</App>

numOfMonths

default: 1

The number of months displayed at once.

placeholder

An optional placeholder text that is visible in the input field when its empty.

<App>
  <DatePicker placeholder="This is a placeholder" />
</App>

<App>
  <DatePicker placeholder="This is a placeholder" />
</App>

presets

Customizes the range presets (range mode only). Supplying a list also turns the presets on. Accepts a comma-separated string or array of built-in preset keys (e.g. last7Days, thisMonth), { value, label } objects to relabel a built-in, or { label, from, to } objects for fully custom date ranges (parsed with dateFormat).

readOnly

default: false

Set this property to true to disallow changing the component value.

required

default: false

Set this property to true to indicate it must have a value before submitting the containing form.

showPresets

default: false

Range presets are hidden by default. Set to true to show the built-in presets (Last 7 days, Last 30 days, This month, Last month); set to false to force them off even when a presets list is supplied.

showWeekNumber

default: false

Show week number cells in the day table.

<App>
  <DatePicker showWeekNumber="true" />
</App>

<App>
  <DatePicker showWeekNumber="true" />
</App>

showWeekNumbers

default: false

Alias for showWeekNumber.

startDate

The earliest month to start the month navigation from (inclusive). If not defined, the component allows any dates in the past. Accepts the same date format as the initialValue. Example: '2023-01-01' ensures the first month to select a date from is January 2023.

startIcon

This property sets an optional icon to appear at the start (left side when the left-to-right direction is set) of the input.

startText

This property sets an optional text to appear at the start (left side when the left-to-right direction is set) of the input.

timeZone

default: "UTC"

The time zone used for date calculations.

validationIconError

Icon to display for the error state when the concise summary is enabled.

validationIconSuccess

Icon to display for the valid state when the concise summary is enabled.

validationStatus

default: "none"

This property allows you to set the validation status of the input component.

Available values:

<App>
  <DatePicker />
  <DatePicker validationStatus="valid" />
  <DatePicker validationStatus="warning" />
  <DatePicker validationStatus="error" />
</App>

<App>
  <DatePicker />
  <DatePicker validationStatus="valid" />
  <DatePicker validationStatus="warning" />
  <DatePicker validationStatus="error" />
</App>

value

Controlled value. In single mode, a date string; in range mode, a { from, to } object.

verboseValidationFeedback

Enables a concise validation summary (icon) in the input.

weekStartsOn

default: 0

The first day of the week. 0 is Sunday, 1 is Monday, etc.

Available values:

<App>
  <DatePicker weekStartsOn="1" />
</App>

<App>
  <DatePicker weekStartsOn="1" />
</App>

width

CSS width for the picker root.

Events

didChange

This event is triggered when value of DatePicker has changed.

Signature: didChange(newValue: any): void

• newValue: The new value of the component.

Write in the input field and see how the Text underneath it is updated in parallel.

<App var.field="(none)">
  <Text value="{field}" />
  <DatePicker
    initialValue="{field}"
    onDidChange="(val) => field = val" />
</App>

<App var.field="(none)">
  <Text value="{field}" />
  <DatePicker
    initialValue="{field}"
    onDidChange="(val) => field = val" />
</App>

gotFocus

This event is triggered when the DatePicker has received the focus.

Signature: gotFocus(): void

Clicking on the DatePicker in the example demo changes the label text. Note how clicking elsewhere resets the text to the original.

<App var.isFocused="false">
  <Text value="{isFocused === true
    ? 'DatePicker focused' : 'DatePicker lost focus'}"
  />
  <DatePicker
    onGotFocus="isFocused = true"
    onLostFocus="isFocused = false"
  />
</App>

<App var.isFocused="false">
  <Text value="{isFocused === true
    ? 'DatePicker focused' : 'DatePicker lost focus'}"
  />
  <DatePicker
    onGotFocus="isFocused = true"
    onLostFocus="isFocused = false"
  />
</App>

lostFocus

This event is triggered when the DatePicker has lost the focus.

Signature: lostFocus(): void

Exposed Methods

focus

Focus the DatePicker component.

Signature: focus(): void

getValue

Return the current value of the DatePicker.

Signature: getValue(): string | { from?: string; to?: string } | undefined

setValue

This method sets the current value of the DatePicker.

Signature: setValue(value: string | { from?: string; to?: string }): void

• value: The new value to set for the date picker.

<App>
  <HStack>
    <Button
      label="Set Date to 05/25/2024"
      onClick="picker.setValue('05/25/2024')" />
    <Button
      label="Remove Date"
      onClick="picker.setValue('')" />
  </HStack>
  <DatePicker id="picker" />
</App>

<App>
  <HStack>
    <Button
      label="Set Date to 05/25/2024"
      onClick="picker.setValue('05/25/2024')" />
    <Button
      label="Remove Date"
      onClick="picker.setValue('')" />
  </HStack>
  <DatePicker id="picker" />
</App>

value

You can query the component's value. If no value is set, it will retrieve undefined.

Signature: get value(): any

Styling

Theme Variables