Provides an input field that triggers a popover date picker.
The q2-calendar element has one or more properties that support text localization. Those properties are indicated by the localizable badge in the description.
assumeDetects the year automatically based on today's date when the user presses the Escape key or the Blur mouse event occurs.
Setting future or past as the value will increase or decrease the year by one, respectively.
calendarLabelcalendar-labelA label shown at the top of the popover date picker.
clearableDisplay a button in the input field allowing the user to clear their selection.
cutoffTimecutoff-timeSpecifies a time of day after which a date is no longer valid.
Must be a valid ISO date string.
daysOfWeekChecksumdays-of-week-checksumThe most concise way to define valid days of the week for calendar. Each day of the week has a checksum value:
Add the checksum values of your desired valid days together, and set daysOfWeekChecksum to that summed value.
Example:
element.daysOfWeekChecksum = 127 // All days of the week are valid
element.daysOfWeekChecksum = 62; // Only weekdays are valid
element.daysOfWeekChecksum = 65; // Only Saturday and Sunday are validdisabledDisable the input field.
disabledMsgdisabled-msgText that displays as the placeholder when the field is marked disabled.
disclaimerText that appears at the bottom of the popover date picker.
displayFormatdisplay-formatDetermines the display format of the date field value.
Must follow the date-fns token specification.
endDateend-dateDefines the last selectable date in the date picker popover.
Must be a valid ISO date string.
errorsEach item in the errors array will appear below the input field when the field is focused and typeable is true.
hideLabelhide-labelHide the input field's <label> element from view.
hintsEach item in the hints array will appear below the input field when the field is focused and typeable is true.
invalidShow error styles when the calendar is in an errant state.
invalidDatesinvalid-datesDefines an explicit date blacklist.
Must be a valid ISO date string.
When explicit date definitions like invalidDates is used, other date validity methods like daysOfWeekChecksum are overriden.
labelThe visible label for the q2-calendar input field.
openDetermine whether the popover is open or closed.
optionalAppends "(optional)" to the label and sets aria-required="false".
placeholderText that appears within the input field when it is blurred and empty. Placeholder text disappears when the user focuses on the field and provides input.
popoverAlignmentpopover-alignmentAligns the popover date picker to the left or right side of the input field.
popoverDirectionpopover-directionForce the direction of the popover date picker when it opens. If no value is passed, the component will auto-detect the direction based on available space.
popoverModepopover-modeDetermines the display mode of the popover.
Providing a value of legacy instructs the popover to use absolute positioning instead of fixed positioning.
This is a temporary solution to work around styling issues related to using fixed positioning for the popover when nested inside of elements with transform properties. This will be removed once the popover API is available for use.
readonlyThe field's content is not editable, but the field remains focusable.
Appends "(readonly)" to the field label. Supersedes optional if both are true.
startDatestart-dateDefines the first selectabe date in the date picker popover.
Must be a valid ISO date string.
typeableThe user can type in the field. Only available in desktop browsers.
validDatesvalid-datesDefines an explicit date whitelist.
Must be a valid ISO date string.
When explicit date definitions like validDates is used, other date validity methods like daysOfWeekChecksum are overriden.
valueThe value of the q2-calendar element, e.g. the selected date.
How to change or clear the value with javascript:
// change date
element.value = '2022-12-21';
// clear date
element.value = null;The q2-calendar element exposes events that can be used to send and receive data from the component based on user interaction.
Emitted when a date is selected or typed in the input field.
{ value: string; }If an event handler is bound to the element using:
onchange property - The default handler will not fire, and the value must be updated in the custom handler.addEventListener("change") method - The default handler will fire alongside the custom handler.Emitted when an invalid date is entered into the field.
{ errors: { message: string; errorCode: string; }[]; }Emitted when a valid date is entered or selected.
{ value: string; }The q2-calendar element exposes methods that can be used to perform various actions on the component.
Emulates clicking the <input> to hide the popover if it is visible.
closePopover() => Promise<void>Emulates clicking the <input> to display the popover if it is hidden.
openPopover() => Promise<void>Emulates clicking the <input> to display the popover, moving to the correct month and year, and clicking the
provided date.
While a string value can be passed, we recommended passing a Date object. If the value is invalid, the method
will not select the date.
setValue(value: string | Date) => Promise<void>Emulates focusing the <input>, entering the provided value, and emitting an input event.
While a string value can be passed, we recommended passing a Date object. If the value is invalid, the method
will not select the date.
typeValue(value: string | Date) => Promise<void>Only applicable when the input is typeable.
Initial Release
Support typeable on mobile
Improve hint and error messaging when typeable
Added support for being clearable
The following CSS variables are available to override the default theme styles of the q2-calendarcomponent.
Many Tecton components consume other components to maintain visual and functional consistency. If you are looking for a CSS variable you think should exist but are not seeing it, it may be defined in one of the dependent components below. Either way, if you think it's something we should expose more conveniently, let us know!
There is 1 frequently asked question related to this page.