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:
Format | Example |
---|---|
MM/dd/yyyy | 05/25/2024 |
MM-dd-yyyy | 05-25-2024 |
yyyy/MM/dd | 2024/05/25 |
yyyy-MM-dd | 2024-05-25 |
dd/MM/yyyy | 25/05/2024 |
dd-MM-yyyy | 25-05-2024 |
yyyyMMdd | 20240525 |
MMddyyyy | 05252024 |
<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:
Pattern | Description | Example |
---|---|---|
Single string | Disable one specific date | "05/25/2024" |
Array of strings | Disable multiple specific dates | ["05/25/2024", "05/26/2024"] |
Boolean | Disable all dates | true |
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:
Pattern | Description | Example |
---|---|---|
Date range | Disable a range of dates | {from: "05/20/2024", to: "05/25/2024"} |
Day of week | Disable specific weekdays (0=Sunday, 6=Saturday) | {dayOfWeek: [0, 6]} |
Before date | Disable all dates before a specific date | {before: "05/25/2024"} |
After date | Disable all dates after a specific date | {after: "05/25/2024"} |
Date interval | Disable 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:
Value | Description |
---|---|
start | The left side of the input (left-to-right) or the right side of the input (right-to-left) |
end | The right side of the input (left-to-right) or the left side of the input (right-to-left) |
top | The top of the input (default) |
bottom | The 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:
Value | Description |
---|---|
valid | Visual indicator for an input that is accepted |
warning | Visual indicator for an input that produced a warning |
error | Visual indicator for an input that produced an error |
Value | Description |
---|---|
valid | Visual indicator for an input that is accepted |
warning | Visual indicator for an input that produced a warning |
error | Visual 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:
Value | Description |
---|---|
0 | Sunday (default) |
1 | Monday |
2 | Tuesday |
3 | Wednesday |
4 | Thursday |
5 | Friday |
6 | Saturday |
Day | Number |
---|---|
Sunday | 0 |
Monday | 1 |
Tuesday | 2 |
Wednesday | 3 |
Thursday | 4 |
Friday | 5 |
Saturday | 6 |
<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
Variable | Default Value (Light) | Default Value (Dark) |
---|---|---|
backgroundColor-DatePicker--disabled | none | none |
backgroundColor-DatePicker-default | none | none |
backgroundColor-DatePicker-default--hover | none | none |
backgroundColor-DatePicker-error | none | none |
backgroundColor-DatePicker-error--hover | none | none |
backgroundColor-DatePicker-success | none | none |
backgroundColor-DatePicker-success--hover | none | none |
backgroundColor-DatePicker-warning | none | none |
backgroundColor-DatePicker-warning--hover | none | none |
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--disabled | none | none |
borderColor-DatePicker-default | none | none |
borderColor-DatePicker-default--hover | none | none |
borderColor-DatePicker-error | none | none |
borderColor-DatePicker-error--hover | none | none |
borderColor-DatePicker-success | none | none |
borderColor-DatePicker-success--hover | none | none |
borderColor-DatePicker-warning | none | none |
borderColor-DatePicker-warning--hover | none | none |
borderColor-selectedItem-DatePicker | $color-primary-200 | $color-primary-200 |
borderColor-selectedItem-DatePicker | $color-primary-200 | $color-primary-200 |
borderRadius-DatePicker-default | none | none |
borderRadius-DatePicker-error | none | none |
borderRadius-DatePicker-success | none | none |
borderRadius-DatePicker-warning | none | none |
borderRadius-menu-DatePicker | $borderRadius | $borderRadius |
borderRadius-menu-DatePicker | $borderRadius | $borderRadius |
borderStyle-DatePicker-default | none | none |
borderStyle-DatePicker-error | none | none |
borderStyle-DatePicker-success | none | none |
borderStyle-DatePicker-warning | none | none |
borderWidth-DatePicker-default | none | none |
borderWidth-DatePicker-error | none | none |
borderWidth-DatePicker-success | none | none |
borderWidth-DatePicker-warning | none | none |
boxShadow-DatePicker-default | none | none |
boxShadow-DatePicker-default--hover | none | none |
boxShadow-DatePicker-error | none | none |
boxShadow-DatePicker-error--hover | none | none |
boxShadow-DatePicker-success | none | none |
boxShadow-DatePicker-success--hover | none | none |
boxShadow-DatePicker-warning | none | none |
boxShadow-DatePicker-warning--hover | none | none |
boxShadow-menu-DatePicker | $boxShadow-md | $boxShadow-md |
boxShadow-menu-DatePicker | $boxShadow-md | $boxShadow-md |
color-adornment-DatePicker-default | none | none |
color-adornment-DatePicker-error | none | none |
color-adornment-DatePicker-success | none | none |
color-adornment-DatePicker-warning | none | none |
fontSize-DatePicker | none | none |
fontSize-placeholder-DatePicker-default | none | none |
fontSize-placeholder-DatePicker-error | none | none |
fontSize-placeholder-DatePicker-success | none | none |
fontSize-placeholder-DatePicker-warning | none | none |
minHeight-DatePicker | none | none |
outlineColor-DatePicker-default--focus | none | none |
outlineColor-DatePicker-error--focus | none | none |
outlineColor-DatePicker-success--focus | none | none |
outlineColor-DatePicker-warning--focus | none | none |
outlineOffset-DatePicker-default--focus | none | none |
outlineOffset-DatePicker-error--focus | none | none |
outlineOffset-DatePicker-success--focus | none | none |
outlineOffset-DatePicker-warning--focus | none | none |
outlineStyle-DatePicker-default--focus | none | none |
outlineStyle-DatePicker-error--focus | none | none |
outlineStyle-DatePicker-success--focus | none | none |
outlineStyle-DatePicker-warning--focus | none | none |
outlineWidth-DatePicker-default--focus | none | none |
outlineWidth-DatePicker-error--focus | none | none |
outlineWidth-DatePicker-success--focus | none | none |
outlineWidth-DatePicker-warning--focus | none | none |
padding-DatePicker | none | none |
paddingBottom-DatePicker | none | none |
paddingHorizontal-DatePicker | $space-2 | $space-2 |
paddingLeft-DatePicker | none | none |
paddingRight-DatePicker | none | none |
paddingTop-DatePicker | none | none |
paddingVertical-DatePicker | $space-2 | $space-2 |
textColor-DatePicker--disabled | none | none |
textColor-DatePicker-default | none | none |
textColor-DatePicker-default--hover | none | none |
textColor-DatePicker-error | none | none |
textColor-DatePicker-error--hover | none | none |
textColor-DatePicker-success | none | none |
textColor-DatePicker-success--hover | none | none |
textColor-DatePicker-warning | none | none |
textColor-DatePicker-warning--hover | none | none |
textColor-placeholder-DatePicker-default | none | none |
textColor-placeholder-DatePicker-error | none | none |
textColor-placeholder-DatePicker-success | none | none |
textColor-placeholder-DatePicker-warning | none | none |
textColor-value-DatePicker | $textColor-primary | $textColor-primary |
textColor-value-DatePicker | $textColor-primary | $textColor-primary |