Logo

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

Properties

autoFocus (default: false)

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

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:
FormatExample
MM/dd/yyyy05/25/2024
MM-dd-yyyy05-25-2024
yyyy/MM/dd2024/05/25
yyyy-MM-dd2024-05-25
dd/MM/yyyy25/05/2024
dd-MM-yyyy25-05-2024
yyyyMMdd20240525
MMddyyyy05252024
<App>
  <DatePicker 
    inline 
    dateFormat="dd-MM-yyyy" 
    initialValue="05/25/2024" />
</App>
Example: dateFormat
<App>
  <DatePicker 
    inline 
    dateFormat="dd-MM-yyyy" 
    initialValue="05/25/2024" />
</App>

disabledDates

An optional array of dates that are disabled
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:
PatternDescriptionExample
Single stringDisable one specific date"05/25/2024"
Array of stringsDisable multiple specific dates["05/25/2024", "05/26/2024"]
BooleanDisable all datestrue
You can use the getDate() function to query the current date.
<App>
  <DatePicker 
    inline 
    disabledDates="{['05/26/2024', '05/27/2024']}" 
    initialValue="05/25/2024" />
</App>  
Example: Disable specific dates
<App>
  <DatePicker 
    inline 
    disabledDates="{['05/26/2024', '05/27/2024']}" 
    initialValue="05/25/2024" />
</App>  
Advanced patterns:
PatternDescriptionExample
Date rangeDisable a range of dates{from: "05/20/2024", to: "05/25/2024"}
Day of weekDisable specific weekdays (0=Sunday, 6=Saturday){dayOfWeek: [0, 6]}
Before dateDisable all dates before a specific date{before: "05/25/2024"}
After dateDisable all dates after a specific date{after: "05/25/2024"}
Date intervalDisable dates between two dates (exclusive){before: "05/30/2024", after: "05/20/2024"}
<App>
  <DatePicker inline disabledDates="{{dayOfWeek: [0, 6]}}" />
</App>  
Example: Disable weekends
<App>
  <DatePicker inline disabledDates="{{dayOfWeek: [0, 6]}}" />
</App>  
<App>
  <DatePicker 
    inline 
    disabledDates="{{from: '05/20/2024', to: '05/25/2024'}}" 
    initialValue="05/18/2024" />
</App>  
Example: Disable date range
<App>
  <DatePicker 
    inline 
    disabledDates="{{from: '05/20/2024', to: '05/25/2024'}}" 
    initialValue="05/18/2024" />
</App>  
<App>
  <DatePicker
    inline 
    disabledDates="{{before: getDate()}}"
    intialValue="{getDate()}"/>
</App>  
Example: Disable dates before today
<App>
  <DatePicker
    inline 
    disabledDates="{{before: getDate()}}"
    intialValue="{getDate()}"/>
</App>  
<App>
  <DatePicker
    inline 
    disabledDates="{[getDate(), {after: getDate()}]}"
    intialValue="{getDate()}"/>
</App>  
Example: Disable dates today and after
<App>
  <DatePicker
    inline 
    disabledDates="{[getDate(), {after: getDate()}]}"
    intialValue="{getDate()}"/>
</App>  
<App>
  <DatePicker 
    inline
    disabledDates="{[
    {dayOfWeek: [0, 6]}, 
    {from: '12/24/2024', to: '12/26/2024'}, 
    '01/01/2025']}" 
    initialValue="12/20/2024"
/>
</App>  
Example: Complex combination
<App>
  <DatePicker 
    inline
    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>  
Example: enabled
<App>
  <DatePicker enabled="false" />
</App>  

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 inline initialValue="05/25/2024" />
</App>  
Example: initialValue
<App>
  <DatePicker inline initialValue="05/25/2024" />
</App>  

inline (default: false)

Whether to display the datepicker inline

label

This property sets the label of the component. If not set, the component will not display a label.

labelBreak (default: true)

This boolean value indicates whether the DatePicker label can be split into multiple lines if it would overflow the available label width.

labelPosition (default: "top")

Places the label at the given position of the component.
Available values:
ValueDescription
startThe left side of the input (left-to-right) or the right side of the input (right-to-left)
endThe right side of the input (left-to-right) or the left side of the input (right-to-left)
topThe top of the input (default)
bottomThe bottom of the input

labelWidth

This property sets the width of the DatePicker component's label. If not defined, the label's width will be determined by its content and the available space.

maxValue

The optional end date of the selectable date range. If not defined, the range allows any future dates.
<App>
  <DatePicker inline maxValue="05/26/2024" />
</App>
Example: maxValue
<App>
  <DatePicker inline maxValue="05/26/2024" />
</App>

minValue

The optional start date of the selectable date range. If not defined, the range allows any dates in the past.
<App>
  <DatePicker inline minValue="05/24/2024" />
</App>
Example: minValue
<App>
  <DatePicker inline minValue="05/24/2024" />
</App>

mode (default: "single")

The mode of the datepicker (single or range)
Available values: single (default), range
<App>
  <DatePicker mode="single" />
  <DatePicker mode="range" />
</App>
Example: mode
<App>
  <DatePicker mode="single" />
  <DatePicker mode="range" />
</App>

placeholder

An optional placeholder text that is visible in the input field when its empty.
<App>
  <DatePicker placeholder="This is a placeholder" />
</App>  
Example: placeholder
<App>
  <DatePicker placeholder="This is a placeholder" />
</App>  

readOnly (default: false)

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

showWeekNumber (default: false)

Whether to show the week number in the calendar
<App>
  <DatePicker showWeekNumber="true" />
</App>
Example: showWeekNumber
<App>
  <DatePicker showWeekNumber="true" />
</App>

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.

validationStatus (default: "none")

This property allows you to set the validation status of the input component.
Available values:
ValueDescription
validVisual indicator for an input that is accepted
warningVisual indicator for an input that produced a warning
errorVisual indicator for an input that produced an error
ValueDescription
validVisual indicator for an input that is accepted
warningVisual indicator for an input that produced a warning
errorVisual indicator for an input that produced an error
<App>
  <DatePicker />
  <DatePicker validationStatus="valid" />
  <DatePicker validationStatus="warning" />
  <DatePicker validationStatus="error" />
</App>
Example: validationStatus
<App>
  <DatePicker />
  <DatePicker validationStatus="valid" />
  <DatePicker validationStatus="warning" />
  <DatePicker validationStatus="error" />
</App>

weekStartsOn (default: 0)

The first day of the week. 0 is Sunday, 1 is Monday, etc.
Available values:
ValueDescription
0Sunday (default)
1Monday
2Tuesday
3Wednesday
4Thursday
5Friday
6Saturday
DayNumber
Sunday0
Monday1
Tuesday2
Wednesday3
Thursday4
Friday5
Saturday6
<App>
  <DatePicker inline weekStartsOn="1" />
</App>
Example: weekStartsOn
<App>
  <DatePicker inline weekStartsOn="1" />
</App>

Events

didChange

This event is triggered when value of DatePicker has changed.
Write in the input field and see how the Text underneath it is updated in parallel.
<App var.field="(none)">
  <Text value="{field}" />
  <DatePicker 
    inline
    initialValue="{field}" 
    onDidChange="(val) => field = val" />
</App>
Example: didChange
<App var.field="(none)">
  <Text value="{field}" />
  <DatePicker 
    inline
    initialValue="{field}" 
    onDidChange="(val) => field = val" />
</App>

gotFocus

This event is triggered when the DatePicker has received the focus.
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>
Example: gotFocus/lostFocus
<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.

Exposed Methods

focus

Focus the DatePicker component.
Signature: focus(): void

setValue

This method sets the current value of the DatePicker.
Signature: set value(value: any): 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 inline id="picker" />
</App>
Example: setValue
<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 inline 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

VariableDefault Value (Light)Default Value (Dark)
backgroundColor-DatePicker--disablednonenone
backgroundColor-DatePicker-defaultnonenone
backgroundColor-DatePicker-default--hovernonenone
backgroundColor-DatePicker-errornonenone
backgroundColor-DatePicker-error--hovernonenone
backgroundColor-DatePicker-successnonenone
backgroundColor-DatePicker-success--hovernonenone
backgroundColor-DatePicker-warningnonenone
backgroundColor-DatePicker-warning--hovernonenone
backgroundColor-item-DatePicker--active$color-surface-200$color-surface-200
backgroundColor-item-DatePicker--active$color-surface-200$color-surface-200
backgroundColor-item-DatePicker--hover$color-surface-100$color-surface-100
backgroundColor-item-DatePicker--hover$color-surface-100$color-surface-100
backgroundColor-menu-DatePicker$color-surface-50$color-surface-50
backgroundColor-menu-DatePicker$color-surface-50$color-surface-50
borderColor-DatePicker--disablednonenone
borderColor-DatePicker-defaultnonenone
borderColor-DatePicker-default--hovernonenone
borderColor-DatePicker-errornonenone
borderColor-DatePicker-error--hovernonenone
borderColor-DatePicker-successnonenone
borderColor-DatePicker-success--hovernonenone
borderColor-DatePicker-warningnonenone
borderColor-DatePicker-warning--hovernonenone
borderColor-selectedItem-DatePicker$color-primary-200$color-primary-200
borderColor-selectedItem-DatePicker$color-primary-200$color-primary-200
borderRadius-DatePicker-defaultnonenone
borderRadius-DatePicker-errornonenone
borderRadius-DatePicker-successnonenone
borderRadius-DatePicker-warningnonenone
borderRadius-menu-DatePicker$borderRadius$borderRadius
borderRadius-menu-DatePicker$borderRadius$borderRadius
borderStyle-DatePicker-defaultnonenone
borderStyle-DatePicker-errornonenone
borderStyle-DatePicker-successnonenone
borderStyle-DatePicker-warningnonenone
borderWidth-DatePicker-defaultnonenone
borderWidth-DatePicker-errornonenone
borderWidth-DatePicker-successnonenone
borderWidth-DatePicker-warningnonenone
boxShadow-DatePicker-defaultnonenone
boxShadow-DatePicker-default--hovernonenone
boxShadow-DatePicker-errornonenone
boxShadow-DatePicker-error--hovernonenone
boxShadow-DatePicker-successnonenone
boxShadow-DatePicker-success--hovernonenone
boxShadow-DatePicker-warningnonenone
boxShadow-DatePicker-warning--hovernonenone
boxShadow-menu-DatePicker$boxShadow-md$boxShadow-md
boxShadow-menu-DatePicker$boxShadow-md$boxShadow-md
color-adornment-DatePicker-defaultnonenone
color-adornment-DatePicker-errornonenone
color-adornment-DatePicker-successnonenone
color-adornment-DatePicker-warningnonenone
fontSize-DatePickernonenone
fontSize-placeholder-DatePicker-defaultnonenone
fontSize-placeholder-DatePicker-errornonenone
fontSize-placeholder-DatePicker-successnonenone
fontSize-placeholder-DatePicker-warningnonenone
minHeight-DatePickernonenone
outlineColor-DatePicker-default--focusnonenone
outlineColor-DatePicker-error--focusnonenone
outlineColor-DatePicker-success--focusnonenone
outlineColor-DatePicker-warning--focusnonenone
outlineOffset-DatePicker-default--focusnonenone
outlineOffset-DatePicker-error--focusnonenone
outlineOffset-DatePicker-success--focusnonenone
outlineOffset-DatePicker-warning--focusnonenone
outlineStyle-DatePicker-default--focusnonenone
outlineStyle-DatePicker-error--focusnonenone
outlineStyle-DatePicker-success--focusnonenone
outlineStyle-DatePicker-warning--focusnonenone
outlineWidth-DatePicker-default--focusnonenone
outlineWidth-DatePicker-error--focusnonenone
outlineWidth-DatePicker-success--focusnonenone
outlineWidth-DatePicker-warning--focusnonenone
padding-DatePickernonenone
paddingBottom-DatePickernonenone
paddingHorizontal-DatePicker$space-2$space-2
paddingLeft-DatePickernonenone
paddingRight-DatePickernonenone
paddingTop-DatePickernonenone
paddingVertical-DatePicker$space-2$space-2
textColor-DatePicker--disablednonenone
textColor-DatePicker-defaultnonenone
textColor-DatePicker-default--hovernonenone
textColor-DatePicker-errornonenone
textColor-DatePicker-error--hovernonenone
textColor-DatePicker-successnonenone
textColor-DatePicker-success--hovernonenone
textColor-DatePicker-warningnonenone
textColor-DatePicker-warning--hovernonenone
textColor-placeholder-DatePicker-defaultnonenone
textColor-placeholder-DatePicker-errornonenone
textColor-placeholder-DatePicker-successnonenone
textColor-placeholder-DatePicker-warningnonenone
textColor-value-DatePicker$textColor-primary$textColor-primary
textColor-value-DatePicker$textColor-primary$textColor-primary
This site is an XMLUI™ app.