Page History
...
- 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
[NO DATA AVAILABLE]
Accessibility
...
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.
Sizing & Layout
- Choose calendar presence based on frequency of use. Use
type="INLINE"for always-visible picking; usetype="NORMAL"for a compact dropdown. - Match selection granularity to the task. Constrain navigation and zoom with
minZoomMode/maxZoomMode(e.g., lock to MONTH↔YEAR for coarse ranges). - Keep inputs compact via date string shape. Use
formatto avoid overly long month names if space is tight.
States & Feedback
- Make ranges view-only when edits aren’t allowed. Set
readonly: true. - Provide a quick “now” affordance for real-time workflows. Enable
showNowButton. - Preserve user progress between sessions when appropriate. Set
saveInLocalStorage: true.
Data-Driven / Conditional Behavior
- Enforce required entry at the component level. Turn on
requiredwithinvalidation. - Centralize validity rules in the component. Configure
validationso the range conforms to business logic (e.g., disallow empty or invalid ranges). - Keep reset behavior predictable. Define
defaultValueso form resets return to a known range.
Visibility & Authorization
- Temporarily remove the control from the UI when it should not appear. Set
hidden: true. - Keep it visible but non-interactive when policy calls for visibility without edit. Use
authorizationDisable.
Content & Localization
- Localize the field label. Provide
labelTranslations. - Align date strings with audience expectation. Configure
formatto match regional conventions while staying parseable by the app.
Dos & Don’ts
| 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.
