(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

Structure

• Consists of two linked input fields for selecting a start date and an end date
• Integrated calendar view allows users to pick dates directly from a calendar interface
• Supports configuration for default values

(Configured in Non-Visual Properties)

• dataField – Defines the field name that will be used when submitting form data. For example, setting to "reportingPeriod" ensures the selected date range is submitted with this field name in the data object.
• controlsRequestType – Specifies how the date range field data is sent in HTTP requests: 'BODY', 'HEADER', or 'PATH'. For example, setting to "BODY" includes the date range in the request body, which is standard for most form submissions.

(Configured in Visual Properties)

• defaultValue – Sets the initial date range that will be used when the form is reset. For example, setting this to a specific date range ensures consistent starting values for the form.
• saveInLocalStorage – Determines whether the component's selected date range is preserved in local storage between sessions. When enabled, the range selection persists between page reloads, improving user experience for complex forms that may take time to complete.

Styling

(Configured in Visual Properties)

• label – The shown label of the element.
• labelTranslations – Sets the label text displayed above the date range picker with support for multiple languages. For example, {"en-US": "Reporting Period", "de-DE": "Berichtszeitraum"} ensures proper localization of the field label for users in different regions.
• format – Determines how the selected dates will be displayed and parsed. Various formats are available, such as "DD/MM/YYYY" or "YYYY-MM-DD HH:mm". For example, setting to "DD.MM.YYYY" would display dates like "25.04.2025" regardless of the user's locale.
• minZoomMode – Sets the minimum zoom level available in the calendar view. Options include "DAY", "MONTH", and "YEAR". For example, setting to "MONTH" restricts users from zooming in to view individual days, which is useful for selecting broader time ranges.
• maxZoomMode – Sets the maximum zoom level available in the calendar view. Options include "DAY", "MONTH", and "YEAR". For example, setting to "YEAR" prevents users from viewing monthly calendars, which is useful when precise day selection isn't required.
• showTime – Controls whether the time selection components are displayed alongside the date pickers. When set to true, users can select both dates and times for more precise range selection, which is useful for scheduling or reporting that requires time precision.
• showNowButton – Adds buttons that allow users to quickly select the current date and time. When enabled, this provides a convenient shortcut for users who need to input the current date without manually navigating the calendar.
• initializeWithCurrentDate – Determines whether the date range picker should pre-fill with the current date when first displayed. When set to true, the field will initialize with today as the start date and tomorrow as the end date, which is helpful for forms where the current period is the most common selection.
• type – Sets the visual appearance of the date range picker between "NORMAL" (standard dropdown picker) and "INLINE" (always-visible calendar). For example, using "INLINE" mode displays a persistent calendar directly on the form rather than requiring a click to open it.

Actions & Variants

(Configured in Events)

• events – Configures the events that the component can trigger and respond to:
• ON_VALUE_CHANGE – Triggered when the user modifies the date range. Can be used to perform immediate actions based on the new selection, such as loading data for the selected period.
• ON_INIT_BASED_ON_USER_VIEW – Triggered specifically when the component initializes in user view mode rather than edit mode.
• ON_INIT – Triggered when the date range picker component is initialized. Can be used to perform setup operations or initial state calculations.
• ON_DESTROY – Triggered when the component is removed from the DOM. Useful for cleanup operations and releasing resources.

(Configured in Visual Properties)

• readonly – Controls whether the date range picker can be interacted with by users. When set to true, the field displays its value but cannot be modified, which is useful for display-only scenarios or when date ranges are determined programmatically.
• hidden – Controls whether the component is visible in the form. When set to true, the component remains in the form structure but is not displayed, which is useful for conditional rendering based on other field values.

Authorization

(Configured in Authorization)

• authorizationDisable – Specifies a policy set that determines when the component should be disabled based on user permissions. For example, setting to "readOnlyPolicy" will disable the date range picker for users who don't have edit permissions according to the specified policy.

Validation

(Configured in Validation)

• 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.

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 dataField and controlsRequestType.
• Enable time precision only when required. Turn on showTime so users can pick hours/minutes alongside dates.
• Prefer a predictable, explicit display/parse format. Set format (e.g., DD.MM.YYYY or YYYY-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 explicit defaultValue for common ranges.

Sizing & Layout

• Choose calendar presence based on frequency of use. Use type="INLINE" for always-visible picking; use type="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 format to 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 required within validation.
• Centralize validity rules in the component. Configure validation so the range conforms to business logic (e.g., disallow empty or invalid ranges).
• Keep reset behavior predictable. Define defaultValue so 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 format to match regional conventions while staying parseable by the app.

Dos & Don’ts

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.