Calendar

A flexible calendar component for date selection with support for single dates, ranges, multiple selections, and extensive customization options.

Overview

The calendar component displays dates in a monthly grid format. It allows users to visually navigate and select dates by browsing through months and years, providing an intuitive interface for date-related tasks and temporal data visualization.

Usage

forge-calendar selects one or more dates through mode (single, multiple, or range), plus min/max/disabledDates/disabledDaysOfWeek constraints, events, and view. Use it when the task is calendar-driven and the surrounding days give useful context, like picking a day off. Reach for a date picker instead when a user is typing in a familiar date and screen space is limited, or a date range picker instead for a bounded start/end range in that same compact form.

Rules

Use a calendar when the task is primarily calendar-driven, like a time-off request.

Use a calendar when a user needs to select multiple dates that aren't necessarily chronological.

Show events or disabled dates directly on the grid so context is visible while choosing.

Don't

Don't use a calendar for familiar dates like birthdays or card expirations — use a date picker instead.

Don't use a calendar when the date isn't central to the task at hand — use a date picker instead.

Don't use a calendar where screen space is limited — use a date picker instead.

Selection mode

Set mode to single (the default), multiple for several non-chronological dates, or range for a bounded start and end date.

Single

The default mode — one date at a time.

<forge-calendar view="month" show-header month="7" year="2026" list-years menu-animation="scale" locale="en-US" constrain-to-enabled allow-single-date-range mode="single" year-range="-50:+50">
</forge-calendar>

Constraints

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

A calendar bounded to a range, with weekends disabled.

<forge-calendar min="2026-01-01" max="2026-12-31" disabled-days-of-week="0,6">
</forge-calendar>

Views

Set view to open the calendar directly into its year view instead of the default day grid.

Opening directly into the year view.

<forge-calendar view="year">
</forge-calendar>

Header controls

Set showToday and showClear to add today and clear shortcuts to the calendar’s header.

Today and clear shortcuts in the calendar's header.

<forge-calendar today-button clear-button>
</forge-calendar>

Readonly

Set readonly to show the current selection without allowing the user to change it.

A readonly calendar shows the selection without allowing changes.

<forge-calendar readonly mode="range">
</forge-calendar>

A flexible calendar component for date selection with support for single dates, ranges, multiple selections, and extensive customization options.

import "@tylertech/forge/calendar";

Properties

Property	Attribute	Type	Default	Description
`activeDate`	—	`Date`	—	The currently active date in the calendar.
`allowSingleDateRange`	`allow-single-date-range`	`boolean`	`true`	Whether to allow a single date range to be selected.
`clearButton`	`clear-button`	`boolean`	`false`	Whether to show a button to clear the selected date(s).
`clearCallback`	—	`() => void \| undefined`	—	Callback function to call when the clear button is clicked.
`constrainToEnabled`	`constrain-to-enabled`	`boolean`	`true`	Whether to constrain the selected date(s) to the enabled dates.
`dateBuilder`	—	`CalendarDateBuilder \| undefined`	—	Function to build the date content.
`dateSelectCallback`	—	`CalendarDateSelectCallback \| undefined`	—	Callback function to call when a date is selected.
`dayBuilder`	—	`CalendarDayBuilder \| undefined`	—	Function to build the day content.
`disabledDateBuilder`	—	`(date: Date) => boolean \| undefined`	—	Function to determine if a date is disabled.
`disabledDates`	—	`Date \| Date[] \| null \| undefined`	`[]`	Dates that are disabled from being selected.
`disabledDaysOfWeek`	—	`DayOfWeek \| DayOfWeek[] \| null \| undefined`	`[]`	Days of the week that are disabled from being selected.
`eventBuilder`	—	`CalendarEventBuilder \| undefined`	—	Function to build the event content.
`events`	—	`ICalendarEvent[] \| null \| undefined`	`[]`	Events to display on the calendar.
`firstDayOfWeek`	`first-day-of-week`	`DayOfWeek`	—	The first day of the week.
`fixedHeight`	`fixed-height`	`boolean`	`false`	Whether to fix the height of the calendar.
`listYears`	`list-years`	`boolean`	`true`	Whether to list the years in the year view.
`locale`	`locale`	`string`	—	The locale to use for formatting dates.
`max`	`max`	`Date \| string \| null`	—	The maximum date that can be selected.
`menuAnimation`	`menu-animation`	`CalendarMenuAnimationType`	`"scale"`	The animation to use for the menu.
`min`	`min`	`Date \| string \| null`	—	The minimum date that can be selected.
`mode`	`mode`	`CalendarMode`	`"single"`	The mode of the calendar.
`month`	`month`	`number`	`<current month>`	The month to display.
`preventFocus`	`prevent-focus`	`boolean`	`false`	Whether to prevent the calendar from taking focus.
`readonly`	`readonly`	`boolean`	`false`	Whether the calendar is readonly.
`selectionFollowsMonth`	`selection-follows-month`	`boolean`	`false`	Whether the selection follows the month.
`showHeader`	`show-header`	`boolean`	`true`	Whether to show the header.
`showOtherMonths`	`show-other-months`	`boolean`	`false`	Whether to show days from other months.
`showToday`	`show-today`	`boolean`	`true`	Whether to show the today button.
`todayButton`	`today-button`	`boolean`	`fakse`	Whether to show a button to select today.
`todayCallback`	—	`() => void \| undefined`	—	Callback function to call when the today button is clicked.
`tooltipBuilder`	—	`CalendarTooltipBuilder \| undefined`	—	Function to build the tooltip content.
`value`	—	`Date \| Date[] \| DateRange \| null \| undefined`	`[]`	The selected date(s).
`view`	`view`	`CalendarView`	`"date"`	The view of the calendar.
`weekendDays`	—	`DayOfWeek[] \| null \| undefined`	—	The days of the week that are considered weekends.
`year`	`year`	`number`	`<current year>`	The year to display.
`yearRange`	`year-range`	`string`	`"-50:+50"`	The range of years to display.

Events

Name	Type	Description
`forge-calendar-date-select`	`CustomEvent<ICalendarDateSelectEventData>`	Event fired when a date is selected.
`forge-calendar-focus-change`	`CustomEvent<ICalendarFocusChangeEventData>`	Event fired when the focus changes.
`forge-calendar-month-change`	`CustomEvent<ICalendarMonthChangeEventData>`	Event fired when the month changes.
`forge-calendar-view-change`	`CustomEvent<CalendarView>`	Event fired when the view changes.

Slots

Name	Description
`today-button-text`	Text to display in the today button.
`clear-button-text`	Text to display in the clear button.
`next-month-button-text`	Text to display in the next month button's tooltip.
`previous-month-button-text`	Text to display in the previous month button's tooltip.
`next-year-button-text`	Text to display in the next year button's tooltip.
`previous-year-button-text`	Text to display in the previous year button's tooltip.
`next-years-button-text`	Text to display in the next years button's tooltip.
`previous-years-button-text`	Text to display in the previous years button's tooltip.

Methods

Name	Returns	Description
`clear()`	`void`	Clears the selected date(s).
`deselectDate(date)`	`void`	Deselects a date.
`goToDate(date, setFocus)`	`void`	Navigates to a specific date.
`handleKey(evt)`	`void`	Handles a keyboard event.
`layout()`	`void`	Lays out the calendar.
`selectDate(date)`	`void`	Selects a date.
`setActiveDate(date, setFocus)`	`boolean`	Sets the active date.
`today()`	`void`	Sets the calendar to today.
`toggleDate(date, force)`	`void`	Toggles a date selection.

Keyboard interaction

Days must be navigable by keyboard.

Each day should be announced individually, including whether it’s currently selected.