Status
The status of the component
The Date and Time Picker is not a separate component. It belongs to the Date Picker.
Component checklist
Ready for use!
Figma component
A link to the Figma library where the component lives.
Repository
A link to the repo where the component lives.
Date and time can be combined into one picker both for selecting a single date and time or a range.
- The Date Picker can be used as a standard Date Picker.
- Changing the type property from date to date-and-time transforms it into a Date and Time Picker.
- This applies to both Day and Range variations.
General Guidelines
Using Date and Time Together
The combined Date and Time Picker ensures consistency and reduces complexity compared to using separate components.
- Use the Date Picker with type: date-and-time when both values are required.
- Keep date and time selection in a single flow instead of separate components.
Do
Use a single Date and Time Picker with date-and-time type.
Don't
Avoid combining a Date Picker and a standalone Time Picker.
Do
Provide clear labels and placeholders to distinguish fields.
Don't
Avoid using the component without a label.
Default Values
Date and Time Picker (Day)
The default view highlights today but does not preselect any values.
- By default, the calendar opens to the current month.
- Today is focused when navigating with the keyboard.
- No date or time is selected by default.
Date and Time Picker (Range)
The default view shows a two-month span without preselected values.
- By default, the calendar opens to the current and next month.
- Today is focused when navigating with the keyboard.
- No date or time is selected by default.
Presets
Presets only affect date values, time remains unchanged.
- Selecting a preset fills the date range automatically.
- Time input keeps its default state.
Empty States
Empty inputs indicate the expected format until a value is selected.
- Time field shows placeholder in HH:MM AM/PM format.
- Date field shows placeholder for the date format.
Depending on the region, the date formats can be the following:
- YYYY/MM/DD
- DD/MM/YYYY
- MM/DD/YYYY
CTA Buttons States and Effects
Clear Button
The Clear button resets the component without closing the calendar.
- Always enabled: Clears all input fields when clicked.
- Calendar remains open after clearing.
Cancel Button
The Cancel button discards changes and restores the previous state.
- Always enabled: Reverts to the last confirmed selection.
- Clicking outside the calendar has the same effect as Cancel.
Apply Button
The Apply button confirms the current selection.
- Enabled when:
- A single date is selected in date picker.
- A date is selected in date and time picker (time optional by default).
- A range is selected in date range picker.
- A range is selected in date range and time picker (time optional by default).
- A range or preset is selected in date range, time and presets picker.
- If no time is chosen, applying defaults to a standard fallback time.
Key Flows Overview
Logic of Date Range Selection
Date range selection is flexible and can begin from either the start or end date. The second selection determines whether the chosen dates are treated as a start or an end.
- If the first click is followed by an earlier date, that earlier date becomes the start.
- If the first click is followed by a later date, that later date becomes the end.
- Selection is complete when both start and end dates are defined.
|
|
First Selected Input Field |
Second Date Click |
Is Range Selection Done? |
Third Date Click |
|---|---|---|---|---|
|
1 |
START ➡️ |
later than first selected |
True ✅ |
later than selected start date - changing end date ⬅️ |
|
2 |
START ➡️ |
later than first selected |
True ✅ |
sooner than selected start date - changing start date ➡️❗️end date should be selected again |
|
3 |
START ➡️ |
sooner than first selected |
False ❌ |
end date active ⬅️ |
|
4 |
END ⬅️️ |
sooner than first selected |
True ✅ |
later than selected start date - changing end date ⬅️ |
|
5 |
END ⬅️️ |
sooner than first selected |
True ✅ |
sooner than selected start date - changing start date ➡️❗️end date should be selected again |
|
6 |
END ⬅️️ |
later than first selected |
False ❌ |
start date active ⬅️ |
The component allows selecting the same value for both the start and end date. This supports use cases where the interval occurs within a single day and only the time values differentiate the start and end of the range.
If a specific product use case requires preventing users from setting identical dates, this restriction can be enforced and documented at the implementation level.
If a specific product use case requires preventing users from setting identical dates, this restriction can be enforced and documented at the implementation level.
Time Picking First
When users start by interacting with the time field, the flow remains consistent with date-first selection.
- Selecting the time input does not open a dropdown directly.
- Instead, it opens the full calendar interface.
- Within the calendar, users can choose either the date or the time.
- This logic applies to both Day and Range variations.
Do
Clicking the time input field opens the full calendar for selecting date or time.
Don't
Clicking the time input field opens a standalone dropdown.
Guidelines for Error Messages and Helper
For the full set of general error management guidelines, please visit the dedicated Error Management page.
Preventing Errors
Clear labels and instructions
Provide a clear label above or next to the component that indicates the field type (e.g., Date, Date & Time, Date Range).
Use helper text to support understanding of the expected format, e.g.:
- “Format: YYYY-MM-DD”
- “Select a start and end date”
The placeholder should offer an example only and must not contain critical instructions.
Detecting & Displaying Errors
Inline errors as the primary method
Inline error messages should appear directly below the date/time input, displayed with a red icon and clear error text.
Typical error types include:
- Invalid date format
- Date out of the allowed range (e.g., past/future limits)
- Missing required dat
Preserving user input
The user’s entered value should always be preserved, even if invalid, until they correct it.
Range-specific error handling
If only one field in the range is invalid (e.g., the end date is invalid), the error appears below that specific field.
If the logic between the two fields is incorrect (e.g., end date < start date), the error may appear on both fields, but primarily under the one where the issue originated.
Validation Timing
On Change
When the user leaves the input field or closes the date picker panel, run:
- format validation
- range logic validation
Recovery
Errors should disappear automatically as soon as the user corrects the invalid input.
Focus should return to a logical place (typically the corrected field).
For range components: if one field is corrected and the overall range becomes valid, the associated error should be removed immediately.
Component-Specific Error Types
Date Picker
- Invalid date format
- Date out of allowed range
- Required date missing
Date & Time Picker
- All of the above, plus:
- Invalid time format
- Time outside allowed hour
Date Range Picker
- Invalid start or end date
- Start > End
- Missing either start or end date
- Range exceeds allowed limits (e.g., max 30 days)
Date & Time Range Picker
- All of the above, plus:
- Invalid datetime combination
- Start datetime after end datetime