react-calendar

Control how dates are returned to your handlers using these props:

• selectRange: Set to true to allow selecting a start and end date.
• returnValue: Determines which part of the date is returned when selectRange is false. Options are 'start', 'end', or 'range' (returns an array of two values).
• allowPartialRange: When selectRange is true, setting this to true allows onChange to be called with a partial result (e.g., only the start date).

The Calendar component is the primary entry point for react-calendar. It can be used in both controlled (using value and view) and uncontrolled (using defaultValue and defaultView) modes.

Key configuration categories include:

• Date Range & Limits: Control selectable dates using minDate, maxDate, and selectRange (for selecting two dates).
• View Control: Manage the visible granularity using view, maxDetail, and minDetail (options: 'month', 'year', 'decade', 'century').
• Formatting: Override default date labels using functions like formatDay, formatMonth, formatYear, etc.
• Customization: Inject custom styles or content into tiles using tileClassName, tileContent, and tileDisabled.

You can access the internal state and methods of the Calendar component using a ref. The ref exposes the following properties and methods:

• activeStartDate: The current beginning of the displayed period.
• value: The currently selected value(s).
• view: The current view granularity.
• drillDown(): Programmatically drills down to a more detailed view.
• drillUp(): Programmatically drills up to a less detailed view.
• onChange(value, event): Programmatically triggers a change.
• setActiveStartDate(date, action): Programmatically changes the active start date.

In addition to the main Calendar component, the package exports specific view components that can be used for different calendar perspectives:

• CenturyView
• DecadeView
• MonthView
• YearView
• Navigation

The Calendar component provides several event handlers to respond to user interactions:

• onChange: Called when a user selects a date. If selectRange is enabled, it returns an array of two dates.
• onActiveStartDateChange: Called when the user navigates between periods (e.g., clicking next/prev).
• onViewChange: Called when the user changes the view granularity (e.g., drilling up or down).
• onDrillDown / onDrillUp: Specific handlers for view depth changes.
• onClickDay, onClickMonth, onClickYear, onClickDecade: Specific handlers for clicking items in their respective views.
• onClickWeekNumber: Called when a user clicks a week number in the MonthView.

The WEEKDAYS constant provides a standard array of numeric indices representing the days of the week, ranging from 0 to 6.

export const WEEKDAYS = [0, 1, 2, 3, 4, 5, 6] as const;

The react-calendar library supports several calendar systems via the CALENDAR_TYPES constant. You can use these values to specify the calendar type in your configuration.

export const CALENDAR_TYPES = {
  GREGORY: 'gregory',
  HEBREW: 'hebrew',
  ISLAMIC: 'islamic',
  ISO_8601: 'iso8601',
} as const;

The package exports several types for configuring the calendar and defining callback functions. Use these for type safety in your React components:

Component Props

• CalendarProps: The configuration object for the Calendar component.

Callback and Utility Types

• CalendarType: Represents the calendar instance/type.
• NavigationLabelFunc: Function type for generating navigation labels.
• OnArgs: Arguments passed to event handlers.
• OnClickFunc: Function type for click events.
• OnClickWeekNumberFunc: Function type for clicking week numbers.
• TileArgs: Arguments passed to tile-related functions.
• TileClassNameFunc: Function type for determining tile CSS classes.
• TileContentFunc: Function type for rendering custom content inside tiles.
• TileDisabledFunc: Function type for determining if a tile should be disabled.

The CALENDAR_TYPE_LOCALES object maps specific CalendarType values to arrays of supported locale strings. This can be used to understand which locales are compatible with specific calendar systems (e.g., hebrew supports ['he', 'he-IL']).

export const CALENDAR_TYPE_LOCALES: Partial<Record<CalendarType, string[]>> = {
  gregory: [
    'en-CA',
    'en-US',
    // ... other en/es/pt locales
  ],
  hebrew: ['he', 'he-IL'],
  islamic: [
    'ar',
    'ar-AE',
    // ... other ar/dv/ps locales
  ],
};

The Range<T> type represents a tuple of two values of type T. In the context of the calendar, this is typically used to represent a start and end date.

export type Range<T> = [T, T];