InputDate
Synonyme: Date Picker, Datumsfeld, Datumseingabe, Datumsauswahl, Date Input
Beschreibung: Mit der InputDate-Komponente können Nutzende Datums- und Zeitwerte erfassen.
Die Komponente basiert auf den nativen HTML5-Eingabetypen date, datetime-local, month, time und week und übernimmt deren Semantik, Tastatursteuerung sowie Unterstützung durch Browser und assistive Technologien.
Die Eingabe erfolgt direkt im Eingabefeld oder über einen Auswahldialog. Die konkrete Darstellung und Tastaturbedienung ist dabei abhängig vom verwendeten Browser und Betriebssystem.
Beispiel
Standard-Datumsfeld mit dem Typ date. Die Eingabe erfolgt über direkte Zahleneingabe mit Automatisierung oder über die gerätespezifische Auswahlhilfe.
<KolInputDate _label="Geburtsdatum" _type="date" />Barrierefreiheit
- Die nativen HTML5-Eingabetypen werden von Browsern und assistiven Technologien standardisiert unterstützt.
- Das Eingabefeld muss mit einer aussagekräftigen Beschriftung (
_label) versehen werden. Zusätzliche Hinweise können über_hint, Fehlermeldungen über_msgbereitgestellt werden. - Darstellung, Bedienung und Funktionsumfang der nativen Auswahldialoge können sich je nach Browser, Betriebssystem und Endgerät unterscheiden.
Konkrete Designentscheidungen
| Entscheidung | Begründung |
|---|---|
| Verwendung nativer HTML5-Eingabetypen | Die Komponente nutzt bewusst native HTML5-Eingabetypen und profitiert dadurch von deren standardisierter Unterstützung durch Browser und assistive Technologien. |
| Kein eigener Datepicker bzw. Zeitwähler | Die Komponente verzichtet bewusst auf eine eigene Implementierung und nutzt stattdessen die nativen Auswahldialoge des Browsers bzw. Betriebssystems. Dadurch profitieren Nutzende von einer vertrauten Bedienung und einer guten Unterstützung durch assistive Technologien. |
Links und Referenzen
Verwendung
- Verwenden Sie InputDate zur Eingabe von Datums- und Zeitwerten in strukturierter Form. Wählen Sie hierfür den zum Anwendungsfall passenden Eingabetyp (
date,datetime-local,month,timeoderweek). - Nutzen Sie
_minund_max, um zulässige Werte fachlich einzuschränken. Verwenden Sie_stepfür den Eingabetyptime, um zulässige Zeitintervalle festzulegen. - Ergänzen Sie keine zusätzlichen ARIA-Rollen oder ARIA-Attribute, um das Verhalten nativer HTML5-Eingabetypen zu verändern.
Tastatursteuerung
Die Tastaturbedienung wird vollständig durch den Browser und das Betriebssystem bestimmt. Daher können sich die unterstützten Tastaturfunktionen und Tastenkombinationen je nach Browser, Betriebssystem und Eingabetyp unterscheiden.
Typischerweise werden folgende Funktionen unterstützt:
| Taste | Funktion |
|---|---|
Tab | Fokus auf das Eingabefeld bzw. das nächste fokussierbare Element setzen. |
Shift+Tab | Fokus auf das vorherige fokussierbare Element setzen. |
Pfeiltasten | Innerhalb des Eingabefeldes oder eines geöffneten Auswahldialogs zwischen den verfügbaren Werten navigieren bzw. den Wert ändern. |
Enter / Leertaste | Eingabe oder Auswahl bestätigen. |
Esc | Geöffneten Auswahldialog schließen. |
Best Practices / Empfehlungen
- Verwenden Sie aussagekräftige Beschriftungen (
_label), damit der erwartete Datums- oder Zeitwert eindeutig erkennbar ist. - Ergänzen Sie bei Bedarf zusätzliche Hinweise über
_hint, beispielsweise zu zulässigen Eingaben oder fachlichen Einschränkungen. - Berücksichtigen Sie, dass sich Darstellung und Bedienung der nativen Auswahldialoge je nach Browser, Betriebssystem und Endgerät unterscheiden können.
Anwendungsfälle
- Eingabe eines Geburtsdatums in Registrierungs- oder Kontaktformularen
- Auswahl eines Datums für Terminvereinbarungen oder Reservierungen
- Erfassung von Uhrzeiten, beispielsweise für Öffnungs-, Start- oder Endzeiten
- Auswahl eines Monats oder einer Kalenderwoche für Planungs- und Auswertungszeiträume
- Erfassung eines Datums mit Uhrzeit, beispielsweise für Termine oder Ereignisse
FAQ
Kann die InputDate mit einem Wert vorbelegt werden?
Ja. Über _value kann die Komponente mit einem zum gewählten Eingabetyp passenden Wert initialisiert werden.
Wie kann InputDate geleernt werden?
Setzen Sie _value auf null oder undefined, um den aktuellen Wert zu entfernen.
Warum sieht InputDate je nach Browser unterschiedlich aus?
Die Komponente nutzt die nativen HTML5-Eingabetypen des Browsers. Darstellung und Bedienung der Auswahldialoge werden daher vom jeweiligen Browser und Betriebssystem bestimmt und können variieren.
Konstruktion / Technik
Playground
<KolInputDate _label="Erstellungsdatum" _type="date" />Funktionalitäten (mit Code)
Beschriftung und Hinweistexte
Das Eingabefeld wird mit einer Beschriftung über _label versehen. Zusätzliche Informationen können über _hint bereitgestellt werden.
<KolInputDate _hint="Bitte geben Sie Ihr Geburtsdatum ein." _label="Geburtsdatum" _type="date" />Eingabetypen
Das Attribut _type bestimmt das Format und den Auswahldialog:
<KolInputDate _label="Datum" _type="date" />Verfügbare Typen:
date: Vollständiges Datum (Standard)datetime-local: Datum und Uhrzeit ohne Zeitzonemonth: Nur Monat und Jahrtime: Nur Uhrzeit (HH:MM)week: Kalenderwoche und Jahr
Bereichsbeschränkung
Die Attribute _min und _max definieren den gültigen Datumsbereich. Sie greifen zuverlässig nur bei der Auswahl über den Kalenderdialog (Datepicker). Bei manueller Texteingabe kann ein Wert außerhalb des definierten Bereichs eingegeben werden, ohne dass automatisch eine Korrektur oder Fehlermeldung erfolgt. Die Validierung manueller Eingaben liegt in der Verantwortung der einbindenden Anwendung.
<KolInputDate _label="Reservierungsdatum" _max="2025-12-31" _min="2025-01-01" _type="date" />Schrittgröße bei Zeiteingabe
Für Typ time kann die Schrittgröße über _step festgelegt werden:
<KolInputDate _label="Uhrzeit" _step="15" _type="time" />Formularattribute
Standard-Formularattribute für Validierung und Interaktion:
<KolInputDate _label="Datum" _required={true} _type="date" />Verfügbare Attribute:
_disabled: Deaktiviert das Eingabefeld (mit Begründung verwenden!)_readOnly: Verhindert Bearbeitung, erlaubt aber den Fokus_required: Kennzeichnet Pflichtfelder_hideLabel: Blendet das Label visuell aus (bleibt für assistive Technologien sichtbar)
Fehlermeldungen
Validierungsfehler oder Hinweismeldungen werden über das Attribut _msg ausgegeben:
<KolInputDate _label="Datum" _msg="Das eingegebene Datum liegt außerhalb des zulässigen Bereichs." _type="date" />Events
Zur Behandlung von Events bzw. Callbacks siehe
| Event | Auslöser | Value |
|---|---|---|
click | Eingabefeld wird angeklickt | - |
focus | Eingabefeld wird fokussiert | - |
blur | Eingabefeld verliert Fokus | - |
input | Wert wird durch Eingabe oder Auswahl geändert | Aktueller Wert in ISO8601-Format |
change | Eingabe wurde durch Fokusabzug oder Enter abgeschlos. | Aktueller Wert in ISO8601-Format |
API
Overview
The Date input type creates an input field for date values. These can be specific dates as well as weeks, months, or time values.
Properties
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
_accessKey | _access-key | Defines the key combination that can be used to trigger or focus the component's interactive element. | string | undefined | undefined |
_autoComplete | _auto-complete | Defines whether the input can be auto-completed. | string | undefined | 'off' |
_disabled | _disabled | Makes the element not focusable and ignore all events. | boolean | undefined | false |
_hideLabel | _hide-label | Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it. | boolean | undefined | false |
_hideMsg | _hide-msg | Hides the error message but leaves it in the DOM for the input's aria-describedby. | boolean | undefined | false |
_hint | _hint | Defines the hint text. | string | undefined | '' |
_icons | _icons | Defines the icon classnames (e.g. _icons="fa-solid fa-user"). | string | undefined | { right?: IconOrIconClass | undefined; left?: IconOrIconClass | undefined; } | undefined |
_label (required) | _label | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to false to enable the expert slot. | string | undefined |
_max | _max | Defines the maximum value of the element. | Date | `${number}-${number}-${number}T${number}:${number}:${number}` | `${number}-${number}-${number}T${number}:${number}` | `${number}-${number}-${number}` | `${number}-${number}` | `${number}-W${number}` | `${number}:${number}:${number}` | `${number}:${number}` | undefined | undefined |
_min | _min | Defines the smallest possible input value. | Date | `${number}-${number}-${number}T${number}:${number}:${number}` | `${number}-${number}-${number}T${number}:${number}` | `${number}-${number}-${number}` | `${number}-${number}` | `${number}-W${number}` | `${number}:${number}:${number}` | `${number}:${number}` | undefined | undefined |
_msg | _msg | Defines the properties for a message rendered as Alert component. | Omit<AlertProps, "_on" | "_label" | "_level" | "_variant" | "_hasCloser"> & { _description: string; } | string | undefined | undefined |
_name | _name | Defines the technical name of an input field. | string | undefined | undefined |
_on | -- | Gibt die EventCallback-Funktionen für das Input-Event an. | InputTypeOnBlur & InputTypeOnClick & InputTypeOnChange & InputTypeOnFocus & InputTypeOnInput & InputTypeOnKeyDown | undefined | undefined |
_readOnly | _read-only | Makes the input element read only. | boolean | undefined | false |
_required | _required | Makes the input element required. | boolean | undefined | false |
_shortKey | _short-key | Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud. | string | undefined | undefined |
_smartButton | _smart-button | Allows to add a button with an arbitrary action within the element (_hide-label only). | string | undefined | { _label: string; } & { _type?: "button" | "reset" | "submit" | undefined; _accessKey?: string | undefined; _on?: ButtonCallbacksPropType<StencilUnknown> | undefined; _ariaExpanded?: boolean | undefined; _tabIndex?: number | undefined; _value?: StencilUnknown; _role?: "tab" | "treeitem" | undefined; _ariaControls?: string | undefined; _ariaDescription?: string | undefined; _ariaSelected?: boolean | undefined; _customClass?: string | undefined; _disabled?: boolean | undefined; _hideLabel?: boolean | undefined; _icons?: IconsPropType | undefined; _id?: string | undefined; _inline?: boolean | undefined; _name?: string | undefined; _shortKey?: string | undefined; _syncValueBySelector?: string | undefined; _tooltipAlign?: AlignPropType | undefined; _variant?: string | undefined; } | undefined |
_step | _step | Defines the step size for value changes. | `${number}.${number}` | `${number}` | number | undefined | undefined |
_suggestions | _suggestions | Suggestions to provide for the input. | W3CInputValue[] | string | undefined | undefined |
_tooltipAlign | _tooltip-align | Defines where to show the Tooltip preferably: top, right, bottom or left. | "bottom" | "left" | "right" | "top" | undefined | 'top' |
_touched | _touched | Shows if the input was touched by a user. | boolean | undefined | false |
_type | _type | Defines either the type of the component or of the components interactive element. | "date" | "datetime-local" | "month" | "time" | "week" | 'date' |
_value | _value | Defines the value of the element. | Date | `${number}-${number}-${number}T${number}:${number}:${number}` | `${number}-${number}-${number}T${number}:${number}` | `${number}-${number}-${number}` | `${number}-${number}` | `${number}-W${number}` | `${number}:${number}:${number}` | `${number}:${number}` | null | undefined | undefined |
_variant | _variant | Defines which variant should be used for presentation. | string | undefined | undefined |
Methods
click
click() => Promise<void>
Clicks the primary interactive element inside this component.
Returns
Type: Promise<void>
focus() => Promise<void>
Sets focus on the internal element.
Returns
Type: Promise<void>
getValue() => Promise<string | Date | undefined | null>
Returns the current value.
Returns
Type: Promise<string | Date | null | undefined>
reset() => Promise<void>
Resets the component's value.
Returns
Type: Promise<void>
Slots
| Slot | Description |
|---|---|
| The label of the input field. |