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 Range Picker

A date input component with an integrated calendar popup for selecting date ranges with separate "from" and "to" date values.

Overview

The date range picker allows users to select a start and end date to define a continuous date range. It combines text input fields with a calendar, giving users the flexibility to either manually type familiar dates or visually select date ranges from a calendar view.

The component automatically handles date formatting and validation for manual entries while ensuring the end date cannot be earlier than the start date.

Usage

forge-date-range-picker wraps a text field with two inputs — “from” and “to” — and adds a calendar popup for picking both ends of a range, through from, to, min, max, disabledDates, disabledDaysOfWeek, masked, showToday, and showClear. Use it whenever a user is entering a span of dates, like time off or a project’s start and end; for a single date, use a date picker instead.

Rules

Do
Let a user type both dates directly as well as pick them from the calendar.Show which end of the range — from or to — a given input represents.Constrain the range with min and max when dates outside it are genuinely invalid, not just unlikely.Validate that the from date doesn't fall after the to date, and surface a clear, actionable error if it does.
Don't
Don't use a date range picker for a single date — use a date picker instead.Don't rely on the calendar popup alone — typed input needs to work for users who know the exact dates already.Don't hide which input is from and which is to.

Basic usage

Type into either input or use the trailing calendar button to open the popup and pick both ends of the range.

A date range picker with typed inputs and a calendar popup.

Constraints

Set min and max to bound both ends of the range to a valid window.

A date range picker bounded to a min/max range.

Masking

Set masked to apply an input mask, shown as a placeholder in each field, so typed dates are corrected to a consistent format as the user types.

A masked date range picker showing its format as a placeholder.

Today and clear shortcuts

Set showToday and showClear to add shortcuts to the calendar popup — disable the Today shortcut for a range that only accepts future dates.

Disabling the Today shortcut for a future-only range.

Disabled

Set disabled to prevent typing or opening the calendar popup.

A disabled date range picker.

A date input component with integrated calendar popup for selecting date ranges with separate "from" and "to" date values.

import "@tylertech/forge/date-range-picker";
Properties
PropertyAttributeTypeDefaultDescription
from—Date | string | null | undefinednullGets/sets the "from" date range value.
to—Date | string | null | undefinednullGets/sets the "to" date range value.
value—TValuenullGets/sets the date range value.
minminstringnullThe minimum date the calendar will allow.
maxmaxstringnullThe maximum date the calendar will allow.
disabledDates—Date | Date[] | null | undefinednullGets/sets the disabled date range values.
openopenbooleanfalseWhether the calendar dropdown is open.
parseCallback—DatePickerParseCallbackparseDateGets/sets the callback used to parse date strings.
formatCallback—DatePickerFormatCallbackformatDateGets/sets the callback used to format date strings.
prepareMaskCallback—DatePickerPrepareMaskCallbackprepareDateMaskGets/sets the callback used to prepare the mask for the date input.
disableDayCallback—(date: Date) => booleanundefinedGets/sets the callback used to disable days in the calendar.
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`.
valueModevalue-modeDatePickerValueModestringThe type for the `value` property and `forge-date-picker-change` event.
notifyInputValueChanges—booleanfalseGets/sets the state of whether to notify input value changes.
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.
disabledDaysOfWeekdisabled-days-of-weekstring[]The days of the week to disable from selection.
yearRangeyear-rangestring''The year range.
localelocalestringundefinedThe locale to use.
dateFormatdate-formatDatePickerDateFormatMM/DD/YYYYThe date format to use for the date picker.
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.
calendarTextcalendar-textDatePickerCalendarDropdownText—Customized strings to display in the calendar dropdown UI.
Events
NameTypeDescription
forge-date-range-picker-changeCustomEvent<IDateRangePickerChangeEventData>Emits when the value of the date range picker changes.
forge-date-range-picker-openCustomEvent<void>Emits when the date range picker calendar opens.
forge-date-range-picker-closeCustomEvent<void>Emits when the date range picker calendar closes.
forge-date-range-picker-inputCustomEvent<string>Emits when the user inputs a value into the date range 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 range picker automatically applies aria-live, aria-atomic, aria-haspopup, aria-expanded, aria-owns, and aria-disabled to both the start and end <input> elements for you. You’re still responsible for adding an aria-label to each input if it doesn’t have an associated <label> element.

Loading Forge chat…