(this page was created automatically. In case of formatting issues, please visit the official Wiki Page)

Date Picker

Overview

• The Date Picker component lets users select a date and, if needed, a time.
• It provides configuration options for display format, labels, and behavior.
• The component supports validation rules to ensure correct input.

Specs

Tokens

Structure

• Consists of a calendar interface for selecting a date, with an optional time selector for choosing hours and minutes.
• Can be shown as a dropdown picker that opens on click or as an inline calendar always visible on the form.
• May include quick-action buttons such as “Now” to select the current date and time.

(Configured in Non-Visual Properties)

• dataField – Defines the field name that will be used when submitting form data. For example, setting to "appointmentDate" ensures the selected date is submitted with this field name in the data object.
• saveInLocalStorage – Determines whether the component's selected date is preserved in local storage between sessions. When enabled, the date selection persists between page reloads, improving user experience for complex forms that may take time to complete.
• controlsRequestType – Specifies how the date field data is sent in HTTP requests: 'BODY', 'HEADER', or 'PATH'. For example, setting to "BODY" includes the date in the request body, which is standard for most form submissions.

Styling

(Configured in Visual Properties)

• labelTranslations – Sets the label text displayed above the date picker with support for multiple languages. For example, {"en-US": "Appointment Date", "de-DE": "Terminsdatum"} ensures proper localization of the field label for different language settings.
• timeLabelTranslations – Sets the label text displayed for the time portion of the date picker with support for multiple languages. For example, {"en-US": "Appointment Time", "de-DE": "Terminzeit"} creates clear labeling for time selection when that option is enabled.
• format – Determines how the selected date (and time) 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.
• type – Sets the visual appearance of the date 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.
• initializeWithCurrentDate – Determines whether the date picker should pre-fill with the current date when first displayed. When set to true, the field will initialize with today's date rather than being empty, which is helpful for forms where today is the most common selection.
• showTime – Controls whether the time selection component is displayed alongside the date picker. When set to true, users can select both date and time values, which is useful for scheduling precise appointments or events.
• showNowButton – Adds a button that allows users to quickly select the current date and time. When enabled, this provides a convenient shortcut for users who need to input the current time without manually selecting values.

Actions & Variants

(Configured in Non-Visual Properties)

• readonly – Controls whether the date 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 dates 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.

(Configured in Events)

• events – Configures the events that the component can trigger and respond to:
• ON_INIT – Triggered when the date 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.

Validation

(Configured in Validation)

• validation – Configures validation rules for the date picker, including:
• required – When set to true, a date must be selected before the form can be submitted.
• compareFields – Enables validation against other date fields, allowing for date range validations like ensuring an end date comes after a start date.

Tests

(Configured in Testing Hooks)

• dataTestId – Sets the testing hook ID for automated testing. For example, setting to "appointment-date-picker" allows test scripts to reliably locate this component during automated test runs.

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-picker

Guidelines

Usage

• Use the Date Picker to capture a single calendar date; enable the time selector only when needed by turning on showTime and supplying timeLabelTranslations with a time-inclusive format (e.g., YYYY-MM-DD HH:mm).
• Default to today when that’s the most common value by enabling initializeWithCurrentDate; pair with showNowButton if users often need the current timestamp.
• Choose the visual mode intentionally: set type="INLINE" when an always-visible calendar aids scanning/comparison; use type="NORMAL" when conserving space or the picker should open on interaction.
• Persist work-in-progress for long or multi-step flows with saveInLocalStorage: true so users don’t lose their selection after reloads.
• Ensure back-end integration is correct by naming the field via dataField and selecting how it’s sent using controlsRequestType (BODY, HEADER, or PATH).

Sizing & Layout

• Choose a format that yields predictable character length (e.g., YYYY-MM-DD vs DD.MM.YYYY) to avoid truncation in tight layouts.

States & Feedback

• Switch between interactive and non-editable states using readonly.
• Control presence vs absence using hidden (keeps the field in the form model but not visible).
• Guard data quality through validation rules, including required and compareFields, to surface errors at validation time.

Visibility & Authorization

• Show a system-controlled value without allowing edits by setting readonly: true.
• Hide the control from the UI while retaining it in the submission model with hidden: true.

Content & Localization

• Localize all human-facing text via labelTranslations and, when showTime: true, timeLabelTranslations.
• Choose an unambiguous format that users recognize; if ambiguity is a concern, prefer ISO-like YYYY-MM-DD (or add time via YYYY-MM-DD HH:mm).
• Keep labels short and specific to reduce wrapping; avoid color-only meaning—use explicit labels and validation feedback.

Dos & Don’ts

Accessibility

• Provide explicit, localized labels so assistive tech announces purpose correctly (labelTranslations, timeLabelTranslations).
• Communicate requiredness via component validation (validation.required).
• Expose a non-editable state while keeping values visible for context (readonly).
• Avoid placing critical information in non-persistent affordances; use clear labels and built-in validation for essential meaning (labelTranslations, timeLabelTranslations, validation).