Page History
(this page was created automatically. In case of formatting issues, please visit the official Wiki Page)
Date Range Picker
Link to Figma: https://www.figma.com/design/yck1tcUXgdQ5aYX6iUAwrO/GE---Astronaut-Design-System?node-id=11525-89949&t=iosNC2AkSTGs5lMh-1
Overview
- The Date Range Picker allows users to select a start and end date within forms.
- It supports formatting, display options, and validation rules.
- It is useful for scenarios such as reporting periods, booking ranges, or filtering data by timeframes.
- The component can also handle time selection when precision is required.
Specs
Tokens
| Token | Description |
|---|---|
| labelTranslations | Sets the label text displayed above the picker with support for multiple languages. |
| format | Determines how selected dates are displayed and parsed (e.g., "DD/MM/YYYY"). |
| minZoomMode | Sets the minimum zoom level in the calendar (DAY, MONTH, YEAR). |
| maxZoomMode | Sets the maximum zoom level in the calendar (DAY, MONTH, YEAR). |
| showTime | Controls whether time selection is available. |
| showNowButton | Adds a button to quickly select the current date and time. |
| initializeWithCurrentDate | Pre-fills the picker with today as start and tomorrow as end when first displayed. |
| type | Sets the appearance to "NORMAL" (dropdown) or "INLINE" (always visible calendar). |
| hidden | Controls whether the component is visible in the form. |
| saveInLocalStorage | Preserves the selected range in local storage between sessions. |
| defaultValue | Sets the initial date range used when the form is reset. |
| readonly | Displays the value but prevents user changes. |
| dataField | Defines the field name used when submitting form data. |
| controlsRequestType | Specifies how the date range data is sent in HTTP requests (BODY, HEADER, PATH). |
| validation | Configures validation rules for the date range. |
| required | Ensures a date range must be selected before submission. |
| authorizationDisable | Applies a policy set that disables the component based on user permissions. |
| events | Configures events the component can trigger or respond to. |
| ON_VALUE_CHANGE (Events) | Triggered when the user changes the date range. |
| ON_INIT_BASED_ON_USER_VIEW (Events) | Triggered when the component initializes in user view mode. |
| ON_INIT (Events) | Triggered when the component is initialized. |
| ON_DESTROY (Events) | Triggered when the component is removed from the DOM. |
...
- validation – Configures validation rules for the date range picker, including:
- required – When set to true, a date range must be selected before the form can be submitted. This ensures users provide this important information before proceeding.
Links
- Figma: https://www.figma.com/design/yck1tcUXgdQ5aYX6iUAwrO/GE---Astronaut-Design-System?node-id=11525-89949&t=iosNC2AkSTGs5lMh-1
- Live style guide: https://e1-dev.k8s.myapp.de/live-style-guide/id3/9-date-picker/date-range-picker
Guidelines
Usage
- Use for selecting a start and end date (optionally with time) when forms must submit a single range value. Bind the submitted field and transport to backends using
dataFieldandcontrolsRequestType. - Enable time precision only when required. Turn on
showTimeso users can pick hours/minutes alongside dates. - Prefer a predictable, explicit display/parse format. Set
format(e.g.,DD.MM.YYYYorYYYY-MM-DD HH:mm) so values read consistently and parse reliably. - Pre-fill when “current period” is the dominant choice. Use
initializeWithCurrentDate(today → tomorrow) or set an explicitdefaultValuefor common ranges.
...
| Do | Don’t | Article setting(s) |
|---|---|---|
Use showTime: true when hours/minutes matter. | Encode time in help text while leaving time selection off. | showTime |
| Constrain zoom to match the task (e.g., MONTH↔YEAR). | Leave default zoom so users must click through days for month-level picks. | minZoomMode, maxZoomMode |
| Pre-fill common ranges with today→tomorrow or a known default. | Start empty when most users pick “today”. | initializeWithCurrentDate, defaultValue |
| Persist the last chosen range across sessions when useful. | Clear the range on reload, forcing users to re-enter. | saveInLocalStorage |
| Use a compact explicit format to avoid truncation. | Rely on ambiguous, locale-dependent browser defaults. | format |
| Inline the calendar when range entry is frequent. | Force extra clicks with a dropdown in workflows that need constant adjustment. | type |
| Validate at the component level and mark as required when needed. | Depend solely on downstream validation to catch empty/invalid ranges. | validation, required |
| Wire downstream updates to value changes. | Require a separate “Apply” button to sync data. | events, ON_VALUE_CHANGE |
| Disable on policy while keeping it visible when awareness is needed. | Hide it when users should understand they lack edit rights. | authorizationDisable |
| Set a stable field name and request location for submissions. | Let backends infer where the range will appear. | dataField, controlsRequestType |
Accessibility
- Localize the field name so screen readers announce the correct label in the user’s language.
- Use an explicit, unambiguous date format to reduce misinterpretation by assistive technologies.
- Reduce keyboard navigation load by limiting calendar granularity to what the task needs (e.g., month/year only).
- Minimize unnecessary focus stops by enabling time inputs only when time precision is needed.
- Offer a quick “current date/time” action to reduce input effort for motor and cognitive accessibility.
- Provide a predictable initial value so the control announces meaningful content on first focus when helpful.
- Avoid re-entry burden across sessions by persisting the last valid range.
- Hide irrelevant inputs entirely to prevent confusion in the accessibility tree when the control is not applicable.
- Reflect permission states clearly by disabling interaction while leaving the value visible when policy requires it.
