HelixOverviewComponentsMapsGraphIntroductionInstallationDeriving a themeSandboxTheme builderVisual testingCortexDocsEngramBuildingTraceBuildingRecallDeclaredServicesInsightsGet in touchSource on GitHub
Loading the reference
Date PickerView SourceEdit in SandboxView MarkdownCopy MarkdownOpen in ClaudeOpen in CursorA month calendar for choosing one or more dates.StableSince 0.1.0FormsUsageimport'@fusion.dev/helix/date-picker'import'@fusion.dev/helix-headless/date-picker'Preview
API ReferenceRoothelix-date-pickerA month calendar for choosing one or more dates.
PropTypeDescriptionbadInputMessagestringDefault"{mode, select, single {Enter a date such as {example}.} other {Enter dates such as {example}, separated by commas.}}"The validation message for a value that is not a date.calendar"buddhist"|"gregory"|"iso8601"|"japanese"|"roc"|"chinese"|"coptic"|"dangi"|"ethioaa"|"ethiopic"|"hebrew"|"indian"|"islamic"|"islamic-civil"|"islamic-rgsa"|"islamic-tbla"|"islamic-umalqura"|"persian"The calendar the heading, the days, and the months are written in.dayContent((date: string) => unknown)What each day shows, in place of its number: a function given the date as
YYYY-MM-DD that returns text, an element or a Lit template.defaultMonthstringDefault""The month to open on when month is not set.defaultValuestringDefault""The value the control starts with. A form reset returns it to this value,
and to the value attribute where this one is not written, as a native
control resets to the value it declares.disabledbooleanDefaultfalseWhether the control is disabled and cannot be used.disableDatesstringDefault""Dates that cannot be chosen, as YYYY-MM-DD, separated by commas or
spaces.disableDaysstringDefault""Days of the week that cannot be chosen, 0 for Sunday to 6 for
Saturday, separated by commas or spaces.feedbackstringDefault""A message under the picker, such as what is wrong with the answer.firstDayOfWeeknumberFirst column of the week, 0 for Sunday through 6 for Saturday.invalidbooleanDefaultfalseWhether the answer fails validation, marked on the controls a reader
answers with and as :state(invalid).isDateUnavailable((date: string) => boolean)A rule for which dates cannot be chosen: a function given the date as
YYYY-MM-DD that returns true to bar it.labelstringDefault"Date Picker"Accessible name for the grid.localestringDefault""Locale for month and day names, and the day a week starts on.maxstringDefault""Latest selectable date, as YYYY-MM-DD.maxView"month"|"year"How far the heading lets a reader step back from the days: month to a
year's months, or year to a page of years and then its months.minstringDefault""Earliest selectable date, as YYYY-MM-DD.mode"range"|"multiple"How many dates can be held at once.monthstringThe month shown, as YYYY-MM, or as its first day, YYYY-MM-DD, under a
calendar with months of its own. When it is not set, it follows
value, then the current month.monthsnumberDefault1How many months to show, side by side.monthViewLabelstringDefault"{heading}. Choose a month"The name of the heading where it shows the months, with {heading}
filled in as the month on show.namestringDefault""The name the control's value is submitted under.nextLabelstringDefault"Next month"Accessible name for the control that pages forward.nextYearLabelstringDefault"Next year"Accessible name for the control that moves forward a year, in the months.nextYearsLabelstringDefault"Later years"Accessible name for the control that moves forward a page, in the years.previousLabelstringDefault"Previous month"Accessible name for the control that pages back.previousYearLabelstringDefault"Previous year"Accessible name for the control that moves back a year, in the months.previousYearsLabelstringDefault"Earlier years"Accessible name for the control that moves back a page, in the years.rangeOrderMessagestringDefault"Choose an end on or after {start}."The validation message for a range that ends before it starts. {start}
is replaced with the start, written as a date in locale.rangeOverflowMessagestringDefault"Choose a date on or before {max}."The validation message for a date after max. {max} is replaced with
max, written as a date in locale.rangeUnderflowMessagestringDefault"Choose a date on or after {min}."The validation message for a date before min. {min} is replaced with
min, written as a date in locale.readOnlybooleanDefaultfalseBlocks changes to the dates. The value is still submitted with the form.requiredbooleanDefaultfalseStops the form from submitting while no date is chosen.selectionLabelstringDefault"{kind, select, date {Selected date: {start}} start {Range starts {start}. Choose the day it ends.} range {Selected range: {start} to {end}} other {{count, plural, one {# date selected} other {# dates selected}}}}"What a screen reader hears about the chosen dates: the grid's
description, said again whenever the dates change. {kind} is date,
start while a range holds one end, range, or dates for multiple.
{start} and {end} are dates written in locale, and {count} is how
many dates are chosen.stepnumberDefault1How far apart the selectable dates are, in days.stepMismatchMessagestringDefault"Choose one of the dates the calendar offers."The validation message for a date that step skips.timeZonestringDefault""The time zone today is read in, such as America/New_York, as React
Aria's today(timeZone) reads it. Empty is the reader's own.unavailableMessagestringDefault"Choose a date that is available."The validation message for a date that disable-dates or disable-days
bars.valuestringThe control's current value, which its form submits.valueAsDateDate|nullThe value as a Date, at midnight UTC, or null while there is no date.valueAsNumbernumberThe value as milliseconds since the epoch, or NaN while there is no date.valueMissingMessagestringDefault"Choose a date."The validation message for a required date picker with no date chosen.view"day"|"month"|"year"Default"day"What the calendar shows: the days of a month, the months of a year, or a
page of years. day unless max-view lets a reader step back.yearViewLabelstringDefault"{heading}. Choose a year"The name of the heading where it shows a page of years, with {heading}
filled in as the year on show.
ReadTypeDescriptionformHTMLFormElement|nullThe form the control belongs to, or null.labelsNodeListThe labels associated with the control.validationMessagestringThe message the browser would show for the control, or an empty string.validityValidityStateWhether the control meets its constraints, and why not.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.willValidatebooleanWhether the control is checked when its form is submitted.
SlotDescriptionfooterContent under the calendar, such as buttons for today or a common range.headerContent above the calendar, such as a note on what the date is for.next-iconThe glyph on the control that moves forward a month, usually a caret.previous-iconThe glyph on the control that moves back a month, usually a caret.
EventTypeDescriptionchangeEventFired after the value changes.helix-before-changeHelixBeforeChangeEventFired before the dates change, and cancelable.helix-navigateHelixNavigateEventFired before the month on show changes, and cancelable.inputEventFired after the value changes.
MethodTypeDescriptioncheckValidity() => booleanReturns whether the control is valid, and fires invalid on it when it is
not. The control shows no message for it: reportValidity() does that.focus(options: FocusOptions) => voidMoves focus to the control, as focusing a native control does.reportValidity() => booleanReturns whether the control is valid, and when it is not, fires invalid
and shows the browser's message at the control.requestValue(next: string) => booleanRequests a new value, and returns whether the change was applied.setCustomValidity(message: string) => voidMarks the control invalid with message, or clears that with an empty
string, as on a native control. The form does not submit while it is set.showChosen() => voidShows the days again, on the month of the chosen date, with the tab stop
on that date, forgetting the month and the day the reader browsed to.
PartDescriptioncellOne column of a week row. A range is painted on the cells.cell-range-endThe cell of a range's last day, beside cell, or of the day a waiting range is drawn to.cell-range-middleA cell between a range's ends, beside cell.cell-range-startThe cell of a range's first day, beside cell.dayThe shape inside a cell. A single chosen date is painted on it.day-disabledA day that cannot be chosen, beside day.day-outsideA day from a neighboring month, filling the grid out, beside day.day-selectedThe chosen day, or either end of a chosen range, beside day.day-todayToday, beside day.day-weekendA day of the weekend where the calendar's language is spoken, beside day: Saturday and Sunday in en-US, Friday and Saturday in ar-EG.feedbackThe message under the calendar, while feedback is set.gridThe grid of days.headerThe month name and its controls.headingThe month and year being shown.heading-buttonThe heading as a button that shows the months or the years, where max-view is set.monthOne month, its header and its grid.monthsThe run of months.nextThe control that moves to the next month.next-markThe glyph on the next month control, where none is slotted.periodOne month in the months view, or one year in the years view.period-currentThis month or this year, beside period.period-disabledA month or a year wholly outside min and max, beside period.period-rowOne row of three months or years.period-selectedThe month or the year on show, beside period.periodsThe grid of months or years.previousThe control that moves to the previous month.previous-markThe glyph on the previous month control, where none is slotted.selectionThe chosen date or range in words, which screen readers hear when it changes. Drawn for screen readers only.weekOne row of days.weekdayA column header naming a day of the week. It shows the short name and says the full one.
CSS PropertyDescription--date-picker-column-countHow many month columns are drawn, capped at two. --date-picker-columns overrides it.--date-picker-columnsMonths per row. Two unless there is only one.--date-picker-day-sizeWidth and height of a day.--date-picker-feedback-colorThe color of the message under the calendar, while feedback is set.--date-picker-period-sizeHeight of a month or a year in the months and years views, where max-view is set.--date-picker-range-colorBand behind the days in a range.--date-picker-range-preview-colorBand behind the days a waiting range is drawn to, before its second end is chosen.--date-picker-row-sizeHeight of a week row.--date-picker-selected-colorFill behind a selected day.--date-picker-track-sizeWidth of a column, which is what sets the space between days.
Custom stateDescriptionblankWhile no date is chosen.invalidWhile invalid is set, feedback says what is wrong, the picker holds a date outside min and max or one it bars, or it is required, holds no date, and the reader has answered once or a form has refused it.month-viewWhile the months of a year are shown, where max-view is set.range-pendingWhile a range holds its first end and waits for the second.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.year-viewWhile a page of years is shown, where max-view is year.
Roothelix-headless-date-pickerA month calendar for choosing one or more dates.
PropTypeDescriptionbadInputMessagestringDefault"{mode, select, single {Enter a date such as {example}.} other {Enter dates such as {example}, separated by commas.}}"The validation message for a value that is not a date.calendar"buddhist"|"gregory"|"iso8601"|"japanese"|"roc"|"chinese"|"coptic"|"dangi"|"ethioaa"|"ethiopic"|"hebrew"|"indian"|"islamic"|"islamic-civil"|"islamic-rgsa"|"islamic-tbla"|"islamic-umalqura"|"persian"The calendar the heading, the days, and the months are written in.dayContent((date: string) => unknown)What each day shows, in place of its number: a function given the date as
YYYY-MM-DD that returns text, an element or a Lit template.defaultMonthstringDefault""The month to open on when month is not set.defaultValuestringDefault""The value the control starts with. A form reset returns it to this value,
and to the value attribute where this one is not written, as a native
control resets to the value it declares.disabledbooleanDefaultfalseWhether the control is disabled and cannot be used.disableDatesstringDefault""Dates that cannot be chosen, as YYYY-MM-DD, separated by commas or
spaces.disableDaysstringDefault""Days of the week that cannot be chosen, 0 for Sunday to 6 for
Saturday, separated by commas or spaces.feedbackstringDefault""A message under the picker, such as what is wrong with the answer.firstDayOfWeeknumberFirst column of the week, 0 for Sunday through 6 for Saturday.invalidbooleanDefaultfalseWhether the answer fails validation, marked on the controls a reader
answers with and as :state(invalid).isDateUnavailable((date: string) => boolean)A rule for which dates cannot be chosen: a function given the date as
YYYY-MM-DD that returns true to bar it.labelstringDefault"Date Picker"Accessible name for the grid.localestringDefault""Locale for month and day names, and the day a week starts on.maxstringDefault""Latest selectable date, as YYYY-MM-DD.maxView"month"|"year"How far the heading lets a reader step back from the days: month to a
year's months, or year to a page of years and then its months.minstringDefault""Earliest selectable date, as YYYY-MM-DD.mode"range"|"multiple"How many dates can be held at once.monthstringThe month shown, as YYYY-MM, or as its first day, YYYY-MM-DD, under a
calendar with months of its own. When it is not set, it follows
value, then the current month.monthsnumberDefault1How many months to show, side by side.monthViewLabelstringDefault"{heading}. Choose a month"The name of the heading where it shows the months, with {heading}
filled in as the month on show.namestringDefault""The name the control's value is submitted under.nextLabelstringDefault"Next month"Accessible name for the control that pages forward.nextYearLabelstringDefault"Next year"Accessible name for the control that moves forward a year, in the months.nextYearsLabelstringDefault"Later years"Accessible name for the control that moves forward a page, in the years.previousLabelstringDefault"Previous month"Accessible name for the control that pages back.previousYearLabelstringDefault"Previous year"Accessible name for the control that moves back a year, in the months.previousYearsLabelstringDefault"Earlier years"Accessible name for the control that moves back a page, in the years.rangeOrderMessagestringDefault"Choose an end on or after {start}."The validation message for a range that ends before it starts. {start}
is replaced with the start, written as a date in locale.rangeOverflowMessagestringDefault"Choose a date on or before {max}."The validation message for a date after max. {max} is replaced with
max, written as a date in locale.rangeUnderflowMessagestringDefault"Choose a date on or after {min}."The validation message for a date before min. {min} is replaced with
min, written as a date in locale.readOnlybooleanDefaultfalseBlocks changes to the dates. The value is still submitted with the form.requiredbooleanDefaultfalseStops the form from submitting while no date is chosen.selectionLabelstringDefault"{kind, select, date {Selected date: {start}} start {Range starts {start}. Choose the day it ends.} range {Selected range: {start} to {end}} other {{count, plural, one {# date selected} other {# dates selected}}}}"What a screen reader hears about the chosen dates: the grid's
description, said again whenever the dates change. {kind} is date,
start while a range holds one end, range, or dates for multiple.
{start} and {end} are dates written in locale, and {count} is how
many dates are chosen.stepnumberDefault1How far apart the selectable dates are, in days.stepMismatchMessagestringDefault"Choose one of the dates the calendar offers."The validation message for a date that step skips.timeZonestringDefault""The time zone today is read in, such as America/New_York, as React
Aria's today(timeZone) reads it. Empty is the reader's own.unavailableMessagestringDefault"Choose a date that is available."The validation message for a date that disable-dates or disable-days
bars.valuestringThe control's current value, which its form submits.valueAsDateDate|nullThe value as a Date, at midnight UTC, or null while there is no date.valueAsNumbernumberThe value as milliseconds since the epoch, or NaN while there is no date.valueMissingMessagestringDefault"Choose a date."The validation message for a required date picker with no date chosen.view"day"|"month"|"year"Default"day"What the calendar shows: the days of a month, the months of a year, or a
page of years. day unless max-view lets a reader step back.yearViewLabelstringDefault"{heading}. Choose a year"The name of the heading where it shows a page of years, with {heading}
filled in as the year on show.
ReadTypeDescriptionformHTMLFormElement|nullThe form the control belongs to, or null.labelsNodeListThe labels associated with the control.validationMessagestringThe message the browser would show for the control, or an empty string.validityValidityStateWhether the control meets its constraints, and why not.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.willValidatebooleanWhether the control is checked when its form is submitted.
SlotDescriptionfooterContent under the calendar, such as buttons for today or a common range.headerContent above the calendar, such as a note on what the date is for.next-iconThe glyph on the control that moves forward a month, usually a caret.previous-iconThe glyph on the control that moves back a month, usually a caret.
EventTypeDescriptionchangeEventFired after the value changes.helix-before-changeHelixBeforeChangeEventFired before the dates change, and cancelable.helix-navigateHelixNavigateEventFired before the month on show changes, and cancelable.inputEventFired after the value changes.
MethodTypeDescriptioncheckValidity() => booleanReturns whether the control is valid, and fires invalid on it when it is
not. The control shows no message for it: reportValidity() does that.focus(options: FocusOptions) => voidMoves focus to the grid's tab stop: the selected day, or the day last
moved to, or the first of the month.reportValidity() => booleanReturns whether the control is valid, and when it is not, fires invalid
and shows the browser's message at the control.requestValue(next: string) => booleanRefuses every change while read-only. See readOnly.setCustomValidity(message: string) => voidMarks the control invalid with message, or clears that with an empty
string, as on a native control. The form does not submit while it is set.showChosen() => voidShows the days again, on the month of the chosen date, with the tab stop
on that date, forgetting the month and the day the reader browsed to.
PartDescriptioncellOne column of a week row. A range is painted on the cells.cell-range-endThe cell of a range's last day, beside cell, or of the day a waiting range is drawn to.cell-range-middleA cell between a range's ends, beside cell.cell-range-startThe cell of a range's first day, beside cell.dayThe shape inside a cell. A single chosen date is painted on it.day-disabledA day that cannot be chosen, beside day.day-outsideA day from a neighboring month, filling the grid out, beside day.day-selectedThe chosen day, or either end of a chosen range, beside day.day-todayToday, beside day.day-weekendA day of the weekend where the calendar's language is spoken, beside day: Saturday and Sunday in en-US, Friday and Saturday in ar-EG.feedbackThe message under the calendar, while feedback is set.gridThe grid of days.headerThe month name and its controls.headingThe month and year being shown.heading-buttonThe heading as a button that shows the months or the years, where max-view is set.monthOne month, its header and its grid.monthsThe run of months.nextThe control that moves to the next month.next-markThe glyph on the next month control, where none is slotted.periodOne month in the months view, or one year in the years view.period-currentThis month or this year, beside period.period-disabledA month or a year wholly outside min and max, beside period.period-rowOne row of three months or years.period-selectedThe month or the year on show, beside period.periodsThe grid of months or years.previousThe control that moves to the previous month.previous-markThe glyph on the previous month control, where none is slotted.selectionThe chosen date or range in words, which screen readers hear when it changes. Drawn for screen readers only.weekOne row of days.weekdayA column header naming a day of the week. It shows the short name and says the full one.
CSS PropertyDescription--date-picker-column-countHow many month columns are drawn, capped at two. --date-picker-columns overrides it.
Custom stateDescriptionblankWhile no date is chosen.invalidWhile invalid is set, feedback says what is wrong, the picker holds a date outside min and max or one it bars, or it is required, holds no date, and the reader has answered once or a form has refused it.month-viewWhile the months of a year are shown, where max-view is set.range-pendingWhile a range holds its first end and waits for the second.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.year-viewWhile a page of years is shown, where max-view is year.
Examples
NameDescriptionBoundedA calendar that only allows dates between min and max.CalendarsThe Persian and Hebrew calendars, each drawn and paged by its own months.Controlled MonthThe month shown is set by your code, so your own controls can page it.DisabledA disabled date picker, which shows its date and cannot be changed.EventsPaging the month sends helix-navigate, and choosing a day sends helix-before-change, input, and change.Header And FooterContent above and under the calendar, in the header and footer slots.InvalidA date picker marked invalid, with its chosen date.MultipleSeveral days chosen in one calendar, in a locale that starts on Monday.PreviewA month, with a day already chosen.PreviewA month, with a day already chosen.RangeA start and an end across two months.RestrictedA month with one date and the weekends blocked from being chosen.