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: