HomeGetting StartedColor SystemTypographySpacingIconographyLayoutInstallationUsageAngularBlazorReactSvelteVueThemingTypographyCustomizationCSS-Only ComponentsFormsIconsIllustrationsAccessibilityGlobal ConfigurationTailwind CSSSass LibraryForge MCP ServerDropdown OptionsFocus Indicator ClippingAll componentsButtonButton AreaChipFloating Action ButtonIcon ButtonSplit ButtonAutocompleteButton ToggleCalendarCheckboxChip FieldColor PickerDate PickerDate Range PickerFile PickerLabelRadioSelectSliderSwitchText FieldTime PickerApp BarApp LauncherDrawerMenuPaginatorSkip LinkStepperTabsView SwitcherAccordionApp LayoutCardDividerExpansion PanelScaffoldSplit ViewStackStructured CardToolbarBadgeBannerBusy IndicatorCircular ProgressDialogInline MessageLinear ProgressPage StateSkeletonToastTooltipAvatarIconKeyLabel ValueListMeterSecretTableTimelineTimestampTreeKeyboard ShortcutPopoverIntroductionColorTypographySpacingShapeBorderElevationLayeringAnimationUsageIcon LibraryBlocksRoadmapChangelogBlog

Date Picker

A date input component with an integrated calendar popup for selecting single dates.

Overview

Date pickers allow users to select dates through multiple input methods. They combine a text input field with a calendar dropdown, giving users the flexibility to either manually type familiar dates or visually select dates from a calendar view. The component automatically handles date formatting and validation for manual entries, making it versatile for both quick familiar date entry and visual date selection.

Usage

forge-date-picker wraps a child text field and adds a calendar dropdown, through min/max/disabledDates/disabledDaysOfWeek, masked/maskFormat/showMaskFormat, dateFormat, shortcuts, showToday, and showClear. Use it for a single, specific date; for a start and end date together, use a date range picker instead, and for a time instead of a date, use a time picker.

Rules

Do
Apply an input mask so typed dates are corrected to a consistent format as the user types.Match the field's width to its expected input, not the full width of the form.Let users type a date directly instead of requiring the calendar dropdown.
Don't
Don't stretch a date picker to the full width of a form — size it to the expected input.Don't split day, month, and year into separate fields — use one date picker field instead.Don't restrict entry to the calendar dropdown alone when typed input is reliable for your data.

Basic usage

A date picker’s text field accepts typed input and its trailing icon button opens a calendar dropdown for picking a date instead.

A date picker combining a text field with a calendar dropdown.

Date format

Set dateFormat to control how a typed or selected date is displayed in the field, independent of the calendar’s own locale. The default is MM/DD/YYYY; the built-in formats are:

  • MM/DD/YYYY
  • MM/DD/YY
  • DD/MMM/YYYY
  • MM-DD-YYYY
  • MM-DD-YY
  • DD-MMM-YYYY
  • YYYY-MM-DD
  • YYYY-MMM-DD
  • DD.MM.YYYY
  • DD.MM.YY

Changing dateFormat automatically updates the input mask to match, and handles parsing/formatting for you.

A date picker with an explicit date format.

Custom mask

Set maskFormat for a non-default input mask, pair it with showMaskFormat to display that mask as a placeholder, and set shortcuts="off" to remove the default quick-entry shortcuts when they don’t make sense for a custom format.

A custom mask format shown as a placeholder, with support text describing it.

For a format that isn’t one of the built-in options, pair maskFormat with parseCallback/formatCallback to take over parsing and formatting entirely. maskFormat supports these segment tokens: Mmm (Jan), MMM (JAN), DD, YYYY, and YY.

dateInput.maskFormat = "Mmm DD, YYYY";

dateInput.parseCallback = (str) => {
  const match = str.match(/(\w{3}) (\d{2}), (\d{4})/);
  if (!match) return null;
  const [, monthStr, day, year] = match;
  const month = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"].indexOf(monthStr);
  return new Date(Number(year), month, Number(day));
};

dateInput.formatCallback = (date) =>
  date ? new Intl.DateTimeFormat("en-US", { month: "short", day: "2-digit", year: "numeric" }).format(date) : "";

Constraints

Set min, max, and disabledDaysOfWeek to bound selectable dates and exclude specific days, such as weekends.

A date picker bounded to a range, with weekends disabled.

Shortcuts, today, and clear

Set showToday and showClear to add dedicated shortcuts to the calendar dropdown, alongside the default quick-entry shortcuts.

Shortcuts for today and a clear button, alongside the default quick-entry shortcuts.

The date picker ships one default quick-entry shortcut — typing t jumps to today. Set shortcuts="off" to remove it, or set the shortcuts property to your own map of key names to callbacks that return a Date given the current date:

dateInput.shortcuts = {
  t: (currentDate) => new Date(currentDate.getFullYear(), currentDate.getMonth(), currentDate.getDate()),
  y: (currentDate) => new Date(currentDate.getFullYear(), 0, 1),
  e: (currentDate) => new Date(currentDate.getFullYear(), 11, 31),
};

Disabled

Set disabled to prevent typing or opening the calendar dropdown.

A disabled date picker.

A date input component with an integrated calendar popup for selecting single dates.

import "@tylertech/forge/date-picker";
Properties
PropertyAttributeTypeDefaultDescription
valuevaluestring—The value of the date picker.
minminstring—The minimum date the calendar will allow.
maxmaxstring—The maximum date the calendar will allow.
disabledDates—Date | Date[] | null | undefined—The dates that are restricted from being selected.
openopenbooleanfalseWhether the calendar dropdown is open.
popupClassespopup-classesstring—The CSS classes that are applied to the popup element.
disableddisabledbooleanfalseWhether the date picker is disabled or not.
maskedmaskedbooleanfalseWhether the input mask is applied or not.
maskFormatmask-formatstringMM/DD/YYYYThe mask format that displayed in the input.
showMaskFormatshow-mask-formatbooleanfalseWhether the mask format is displayed in the input or not. Only applies if `masked` is `true`.
dateFormatdate-formatDatePickerDateFormatMM/DD/YYYYThe date format to use for the date picker.
valueModevalue-modeDatePickerValueModestringThe type for the `value` property and `forge-date-picker-change` event.
shortcutsshortcutsDatePickerShortcuts—When specifies as an attribute you can only use the `off` value to disable shortcuts. Otherwise, you can use the `shortcuts` property to set your own shortcuts.
notifyInputValueChanges—booleanfalseWhether the native input will be notified of value changes via the `input` and `change` events.
allowInvalidDateallow-invalid-datebooleanfalseWhether to allow an invalid date to be input. When true, the date picker will not clear out the value of the input if the date was invalid (i.e. could not be parsed).
showTodayshow-todaybooleanfalseWhether the today button is visible in the popup.
showClearshow-clearbooleanfalseWhether the clear button is visible in the popup.
parseCallback—DatePickerParseCallback—The callback to use for parsing a date value string to a `Date` object.
formatCallback—DatePickerFormatCallback—The callback to use for formatting `Date` value to a custom string format.
prepareMaskCallback—DatePickerPrepareMaskCallback—The callback to use when altering default mask entry.
disabledDaysOfWeekdisabled-days-of-weekstring—The days of the week to disable from selection.
disableDayCallback—(date: Date) => boolean—The callback to use for testing whether a specific date should be disabled or not.
yearRangeyear-rangestring—The year range.
localelocalestring—The locale to use.
calendarTextcalendar-textDatePickerCalendarDropdownText—Customized strings to display in the calendar dropdown UI.
Events
NameTypeDescription
forge-date-picker-changeCustomEvent<Date | string | null>Emits when the value of the date picker changes.
forge-date-picker-openCustomEvent<void>Emits when the date picker opens.
forge-date-picker-closeCustomEvent<void>Emits when the date picker closes.
forge-date-picker-inputCustomEvent<string>Emits when the user inputs a value into the date picker.

Screen reader behavior

Verify that keyboard navigation within the calendar popup is announced by a screen reader as the user moves between days.

The date picker automatically applies aria-live, aria-atomic, aria-haspopup, aria-expanded, aria-owns, and aria-disabled to its <input> for you. You’re still responsible for adding an aria-label to the input if it doesn’t have an associated <label> element.

Loading Forge chat…