Month Picker

Der Month Picker ist ein Eingabefeld, mit dem ein Monat in einem bestimmten Jahr ausgewählt werden kann.

Overview

Intro

Der Month Picker ermöglicht dem Nutzer, einen Monat und das zugehörige Jahr auszuwählen. Üblicherweise wird er innerhalb von Formularen verwendet, beispielsweise zur Angabe von Gültigkeitszeiträumen.

broken_image

Figma

Month Picker

Verwendung

👍 Do	👎 Don't
... wenn ein Monat und ein Jahr erfasst werden soll (z.B. in einem Formular für eine Gültigkeit).	... wenn ein exaktes Datum erfasst werden soll (siehe hierzu Date Picker). ... wenn ein Datumsbereich erfasst werden soll (siehe hierzu Datumsbereich durch Range Selector). ... wenn ein Datum und eine Uhrzeit erfasst werden soll (siehe hierzu Date Time Picker). ... wenn eine Uhrzeit erfasst werden soll (siehe hierzu Time Picker).

Guidelines

Aufbau

Der Month Picker setzt sich aus folgenden Bestandteilen zusammen. Label, Eingabefeld, Toggle button und Month Picker Overlay sind immer vorhanden, die als optional gekennzeichneten Elemente werden nur bei Bedarf ergänzt:

• Label — kennzeichnet das Feld. Für die Barrierefreiheit erforderlich. Unterstützt Plaintext-Inhalt; die Länge ist durch die Breite des Feldes begrenzt.
• Eingabefeld — nimmt Monat und Jahr auf, die der Nutzer eintippt, und zeigt die im Overlay getroffene Auswahl an.
• Toggle button — das Kalender-Icon am Ende des Feldes öffnet und schließt das Overlay. Er ist selbst nicht tastaturfokussierbar und für Screenreader ausgeblendet. In den States Read Only und Disabled bleibt er sichtbar, ist aber ausgegraut und ohne Funktion.
• Month Picker Overlay — oben ein Jahreswechsel mit einem Pfeil nach links und einem nach rechts, darunter das Raster mit den 12 Monaten.
• Helper text (optional) — erscheint unterhalb des Feldes. Geeignet, um das erwartete Format oder den zulässigen Zeitraum zu erläutern.
• Placeholder (optional) — wird angezeigt, solange das Feld leer ist, und gibt einen kurzen Eingabehinweis, z.B. das Format der Eingabe MM.JJJJ . Er ist nur zu verwenden, wenn kein Helper text möglich ist, ersetzt kein sichtbares Label und kann für einen bereits eingegebenen Wert gehalten werden.
• Tooltip (optional) — kleines Text-Pop-up, das bei Hover und bei Tastatur-Fokus angezeigt wird. Helper werden gegenüber Tooltips generell bevorzugt, da sie besser auffindbar und mobil besser unterstützt sind.
• Clear button (optional) — erscheint, sobald das Feld nicht leer ist, und löscht den aktuellen Wert. Der Button selbst ist nicht tastaturfokussierbar.
• Required indicator (bei Bedarf) — Pflichtfelder werden durch einen Indikator neben dem Label gekennzeichnet. Die Kennzeichnung und ihre Erläuterung regelt Formulare .

Prefix- und Suffix-Elemente bietet der Month Picker nicht an.

Die Anordnung des Feldes im Formular und seine Spaltenbelegung regelt das Form Layout .

Info für Dev

Der Month Picker kommt nicht aus dem @vaadin-Namensraum, sondern aus der Vaadin Component Factory. In Web Components ist er das Element <vcf-month-picker> aus dem Paket @vaadin-component-factory/vcf-month-picker; das Paket ist in @mate/bundles enthalten. Intern setzt es ein <vaadin-text-field> als Eingabefeld ein.

In Vue liegt er im Paket @mate-vue/month-picker und heißt MateMonthPicker.

In Flow stammt die Klasse MonthPicker aus dem Maven-Artefakt vcf-month-picker-flow der groupId org.vaadin.addons.componentfactory und dem Paket org.vaadin.addons.componentfactory.monthpicker.

Verhalten

Beim Klick auf das Kalender-Icon oder in das Eingabefeld klappt das Month Picker Overlay auf. Hier kann der Nutzer oben durch die Jahre schalten und darunter einen der 12 Monate auswählen. Bewegt der Nutzer die Maus über einen Monat, wird dieser farblich hervorgehoben. Beim Klick auf einen Monat wird die Auswahl (Monat und Jahr) übernommen und das Overlay schließt sich. Des Weiteren ist es auch möglich, den Monat und das Jahr per Tastatur direkt in das Feld einzutippen. Der aktuelle Monat ist zudem auch farblich und durch einen Unterstrich hervorgehoben.

broken_image Figma	Geöffneter Month Picker
broken_image Figma	Month Picker Hover über Monat
broken_image Figma	Month Picker mit ausgewähltem Monat

Parser Verhalten

Der Parser, der beim Month Picker eingebunden werden kann, verhält sich wie nachfolgend dargestellt:

Aktuelles Verhalten

Beim Verlassen des Feldes wird der Monat immer mit zwei Stellen angegeben. Falls notwendig, wird eine führende Null ergänzt. 7.2025 → 07.2025

Validierung

Die Validierung erfolgt, wenn der Nutzer eine Wertänderung auslöst, z.B. durch Auswahl eines Monats im Overlay oder durch Eingabe und Drücken von Enter . Geprüft wird nur bei einer Wertänderung; ein Fokusverlust ohne Änderung löst keine Prüfung aus. Ist der Wert ungültig, wird das Feld rot hervorgehoben und eine Fehlermeldung erscheint unterhalb des Eingabefeldes; die fehlerhafte Eingabe bleibt im Feld stehen, damit sie korrigiert werden kann.

Die Prüfung läuft in zwei Stufen. Die Pre-Submit-Validierung prüft das einzelne Feld, sobald es den Fokus verliert, und zeigt den Fehler unmittelbar unterhalb des Feldes. Die Post-Submit-Validierung läuft, nachdem der Nutzer das Formular abgeschickt hat: Sie prüft alle Felder erneut, markiert die fehlerhaften und setzt den Fokus auf das erste davon. Beide Stufen und die Formulierung der Fehlermeldungen sind unter Validierung unter Formulare beschrieben.

Folgende Constraints werden unterstützt:

Constraint	Verhalten
Min / Max	Legen den frühesten und den spätesten wählbaren Monat fest. Monate und Jahre außerhalb dieses Bereichs lassen sich im Overlay nicht auswählen; ein Monat außerhalb des Bereichs macht das Feld ungültig. Der erlaubte Bereich sollte über den Helper text kommuniziert werden.
Nicht parsbare Eingabe	Jede Eingabe, die nicht in einen Monat mit Jahr umgesetzt werden kann, macht das Feld ungültig. Dieser Constraint ist nicht konfigurierbar und immer aktiv.

Eine Pflichtfeldprüfung bringt der Month Picker nicht mit: Ein Pflichtfeld wird zwar als solches gekennzeichnet, ein leeres Feld meldet die Gültigkeitsprüfung der Komponente aber nicht als Fehler. Diese Prüfung verantwortet das Produktteam.

Jedes Constraint sollte eine eigene Fehlermeldung haben, damit der Nutzer spezifisches, umsetzbares Feedback erhält.

States

Die Darstellung der States Enabled, Error, Disabled , Read Only , Hover und Focus entspricht der Standarddarstellung (siehe States .). Zudem ist die Verwendung eines Hilfe-Texts unterhalb des Felds möglich.

Barrierefreiheit

Tastaturbedienung

Über die Tabulatortaste ( Tab ) oder Shift + Tab ist der Month Picker fokussierbar.

Das Overlay kann mit der Leertaste geöffnet werden. Innerhalb des Overlays gilt:

• Mit der Tabulatortaste können die Pfeiltasten Links/Rechts fokussiert werden. Durch ein Betätigen von Leertaste oder Enter kann zwischen den Jahren gewechselt werden.
• Innerhalb des Monatsrasters nachdem man dorthin mit der Tabulatortaste navigiert hat, können mit allen Pfeiltasten (Hoch, Runter, Links, Rechts) die einzelnen Monate fokussiert werden. Durch ein Betätigen von Leertaste oder Enter kann ein Monat ausgewählt werden werden. Das Overlay schließt sich dabei.
• Mit der Escape -Taste wird das Overlay geschlossen, ohne eine Auswahl zu treffen.

Spezifische Hinweise

Die Komponente stellt selbst bereit: die Verknüpfung des sichtbaren Labels mit dem Eingabefeld, die Kennzeichnung von Pflichtfeldern über das native required am Eingabefeld, die Verknüpfung von Helper text und Fehlermeldung über aria\-describedby und die Ansage des Overlays über aria\-haspopup und aria\-expanded . Nichts davon wird nachgebaut. Das Produktteam verantwortet die Inhalte:

• Da jedes Eingabefeld ein Label haben muss, ist kein zusätzliches aria\-label nötig. Ein am Feld gesetztes aria\-label ersetzt den Namen aus dem sichtbaren Label und darf deshalb nur bei Feldern ohne sichtbares Label verwendet werden.
• Der Platzhalter ist kein Ersatz für das Label und wird nicht zuverlässig vorgelesen. Formathinweise gehören in das Label oder in den Helper text.
• Ein Feld, das dauerhaft nur der Anzeige dient, wird auf Read Only gesetzt: Es bleibt fokussierbar, für Screenreader sichtbar und sein Wert kopierbar. Ein Feld, das im Laufe des Prozesses wieder bearbeitbar werden kann, wird auf Disabled gesetzt: Es ist nicht fokussierbar und für Screenreader unsichtbar und eignet sich deshalb nicht zur Anzeige von Informationen. Siehe States .
• Fehlermeldung: Die Verknüpfung mit dem Eingabefeld stellt die Komponente her. Das Produktteam verantwortet den Text — er muss sagen, wie der Fehler zu beheben ist (z.B. "Monat im Format MM.JJJJ eingeben" , nicht nur "Fehler" ), und der Fehler darf nicht ausschließlich über Farbe kommuniziert werden.
• Pflichtfeld-Kennzeichnung: Wie Pflichtfelder gekennzeichnet und erklärt werden, regelt Formulare .