DateCalendar

🔒 This component is locked as a private API. We do not yet recommend using this outside of the Gutenberg project.
DateCalendar is a React component that provides a customizable calendar interface for single date selection.
The component is built with accessibility in mind and follows ARIA best practices for calendar widgets. It provides keyboard navigation, screen reader support, and customizable labels for internationalization.
Usage example
import { DateCalendar } from '@wordpress/components';
function MyComponent() {
    const [ selected, setSelected ] = useState< Date >( new Date() );
    return <DateCalendar selected={ selected } onSelect={ setSelected } />;
}
Props
These props are shared between both single date and date range calendar modes.
required
Type: 
boolean
Required: No
Default: 
false
Whether the selection is required. When 
true, there always needs to be a date selected.
selected
Type: 
Date | undefined | null
Required: No
The selected date.
onSelect
Type: 
(selected: Date | undefined, triggerDate: Date, modifiers: Modifiers, e: React.MouseEvent | React.KeyboardEvent) => void
Required: No
Event handler when a day is selected.
defaultSelected
Type: 
Date
Required: No
The default selected date (for uncontrolled usage).
defaultMonth
Type: 
Date
Required: No
Default: Current month
The initial month to show in the calendar view (uncontrolled).
month
Type: 
Date
Required: No
The month displayed in the calendar view (controlled). Use together with 
onMonthChange to change the month programmatically.
numberOfMonths
Type: 
number
Required: No
Default: 
1
The number of months displayed at once.
startMonth
Type: 
Date
Required: No
The earliest month to start the month navigation.
endMonth
Type: 
Date
Required: No
The latest month to end the month navigation.
autoFocus
Type: 
boolean
Required: No
Focus the first selected day (if set) or today’s date (if not disabled). Use this prop when you need to focus the calendar after a user action (e.g. opening the dialog with the calendar).
disabled
Type: 
Matcher | Matcher[] | undefined
Required: No
Specify which days are disabled. Using 
true will disable all dates. See the Matcher Types section for more details.
disableNavigation
Type: 
boolean
Required: No
Disable the navigation buttons.
labels
Type: 
object
Required: No
Use custom labels for internationalization. All labels are optional and have sensible defaults:
{
  labelNav?: () => string; // Navigation toolbar label
  labelGrid?: (date: Date) => string; // Month grid label (default: "LLLL y")
  labelGridcell?: (date: Date, modifiers?: Modifiers) => string; // Grid cell label
  labelNext?: (month: Date | undefined) => string; // Next month button label
  labelPrevious?: (month: Date | undefined) => string; // Previous month button label
  labelDayButton?: (date: Date, modifiers?: Modifiers) => string; // Day button label
  labelWeekday?: (date: Date) => string; // Weekday label
}
Important: For a correct localized experience, consumers should make sure the locale used for the translated labels and 
locale prop are consistent.
locale
Type: 
Locale
Required: No
Default: 
enUS from 
@date-fns/locale
The locale object used to localize dates. Pass a locale from 
@date-fns/locale to localize the calendar.
Important: For a correct localized experience, consumers should make sure the locale used for the translated labels and 
locale prop are consistent.
weekStartsOn
Type: 
0 | 1 | 2 | 3 | 4 | 5 | 6 | undefined
Required: No
Default: Based on the 
locale prop
The index of the first day of the week (0 – Sunday). Overrides the locale’s setting.
onMonthChange
Type: 
(month: Date) => void
Required: No
Event fired when the user navigates between months.
timeZone
Type: 
string
Required: No
The time zone (IANA or UTC offset) to use in the calendar. See Wikipedia for possible values.
When working with time zones, use the 
TZDate object exported by this package instead of the native 
Date object.
import { DateCalendar, TZDate } from '@wordpress/components';
export function WithTimeZone() {
    const timeZone = 'America/New_York';
    const [ selected, setSelected ] = useState< Date | undefined >(
        new TZDate( 2024, 12, 10, timeZone ) // Use `TZDate` instead of `Date`
    );
    return (
        <DateCalendar
            timeZone={ timeZone }
            selected={ selected }
            onSelect={ setSelected }
        />
    );
}
role
Type: 
'application' | 'dialog' | undefined
Required: No
Default: 
'application'
The role attribute to add to the container element.
Matcher Types
The calendar component uses a flexible matching system to determine which days should be disabled or have specific modifiers. Here are the available matcher types:
Boolean Matcher
const booleanMatcher: Matcher = true; // Will always match the day
Date Matcher
const dateMatcher: Matcher = new Date(); // Will match today's date
Array Matcher
const arrayMatcher: Matcher = [
    new Date( 2019, 1, 2 ),
    new Date( 2019, 1, 4 ),
]; // Will match the days in the array
Date After Matcher
const afterMatcher: DateAfter = { after: new Date( 2019, 1, 2 ) }; // Will match days after the 2nd of February 2019
Date Before Matcher
const beforeMatcher: DateBefore = { before: new Date( 2019, 1, 2 ) }; // Will match days before the 2nd of February 2019
Date Interval Matcher
const intervalMatcher: DateInterval = {
    after: new Date( 2019, 1, 2 ),
    before: new Date( 2019, 1, 5 ),
}; // Will match the days between the 2nd and the 5th of February 2019 (exclusive)
Date Range Matcher
const rangeMatcher: DateRange = {
    from: new Date( 2019, 1, 2 ),
    to: new Date( 2019, 1, 5 ),
}; // Will match the days between the 2nd and the 5th of February 2019 (inclusive)
Day of Week Matcher
const dayOfWeekMatcher: DayOfWeek = { dayOfWeek: 0 }; // Will match Sundays
const weekendMatcher: DayOfWeek = { dayOfWeek: [ 0, 6 ] }; // Will match weekends
Function Matcher
const functionMatcher: Matcher = ( day: Date ) => {
    return day.getMonth() === 2; // Will match when month is March
};