Form fields

Ready-made date and date range fields that wrap a Material form field and datepicker. Two sets share one template and the same inputs.

Each field provides its own HijriDateAdapter, reading the calendar and locale defaults from provideHijriDateAdapter() when it is present.

The fields inherit the project Material theme. Read Styling.

Values

The value of a date field is a CalendarDate or null. The value of a range field is a CalendarDateRange with start and end, each a CalendarDate or null.

Values are always emitted in valueCalendar, which defaults to the provider calendar. A written value may be in either calendar. Anything other than a CalendarDate, null, or '' throws.

Calendar toggle and hint

With calendarToggle, Hijri and Gregorian icon buttons replace the calendar icon. Pressing one switches the displayed and typed calendar, then opens the picker. Switching does not change the form value and does not mark the control dirty. A typed 20/3/2024 in the Gregorian view stores 10 Ramadan 1445 when valueCalendar is islamic-umalqura.

With the toggle on, the hint shows the selected date in the calendar that is not displayed, such as 10 Ramadan, 1445 AH. Set equivalentHint to false to hide it.

A #calendarToggle template replaces those buttons. Read Calendar toggle.

Displayed format

displayFormat chooses the text in the input. It does not change the CalendarDate stored by the form. numeric is the default: 29/4/1448 and 10/10/2026. month-name writes the month: 29 Rabi al-Thani, 1448 and 10 October, 2026.

Digits and the month language follow locale. With ar-SA, the same two days are ٢٩/٤/١٤٤٨ and ١٠/١٠/٢٠٢٦, or ٢٩ ربيع الثاني، ١٤٤٨ and ١٠ أكتوبر، ٢٠٢٦. Both forms still parse.

Inputs

Input	Description
`label`	The form field label.
`placeholder`	Date fields only.
`startPlaceholder`, `endPlaceholder`	Range fields only.
`valueCalendar`	The calendar of emitted values. Defaults to the provider calendar.
`calendarToggle`	Shows the Hijri and Gregorian buttons.
`equivalentHint`	Shows the date in the other calendar while the toggle is on. Defaults to true.
`locale`	Overrides the provider locale for digits, names, week start, and button text.
`displayFormat`	`numeric` or `month-name`. Defaults to `numeric`.
`minDate`, `maxDate`	A `CalendarDate` in either calendar.
`period`	`'all'`, `'past'`, or `'future'`. Past and future both exclude today.
`dateFilter`	Receives each day in `valueCalendar`.
`touchUi`	Opens the calendar in a dialog.
`calendarLabels`	Overrides accessible names and the letter labels a custom template can show. The default buttons are icons.

Range limits and unreadable dates

When Umm al-Qura is involved, through valueCalendar or the toggle, the picker is limited to AH 1300–1599. A Gregorian date outside that table reports matDatepickerMin or matDatepickerMax, and the value is null. An unreadable date also sets the value to null.