Date Calendar

The Date Calendar component lets users select a date without any input or popper / modal.

Basic usage

April 2024

SMTWTFS

<DateCalendar />

<DateCalendar />

Press Enter to start editing

Uncontrolled vs. controlled value

The value of the component can be uncontrolled or controlled.

Uncontrolled calendar

April 2022

SMTWTFS

Controlled calendar

April 2022

SMTWTFS

<DemoItem label="Uncontrolled calendar">
  <DateCalendar defaultValue={dayjs('2022-04-17')} />
</DemoItem>
<DemoItem label="Controlled calendar">
  <DateCalendar value={value} onChange={(newValue) => setValue(newValue)} />
</DemoItem>

<DemoItem label="Uncontrolled calendar">
  <DateCalendar defaultValue={dayjs('2022-04-17')} />
</DemoItem>
<DemoItem label="Controlled calendar">
  <DateCalendar value={value} onChange={(newValue) => setValue(newValue)} />
</DemoItem>

Press Enter to start editing

Form props

The component can be disabled or read-only.

disabled

April 2022

SMTWTFS

readOnly

April 2022

SMTWTFS

<DemoItem label="disabled">
  <DateCalendar defaultValue={dayjs('2022-04-17')} disabled />
</DemoItem>
<DemoItem label="readOnly">
  <DateCalendar defaultValue={dayjs('2022-04-17')} readOnly />
</DemoItem>

<DemoItem label="disabled">
  <DateCalendar defaultValue={dayjs('2022-04-17')} disabled />
</DemoItem>
<DemoItem label="readOnly">
  <DateCalendar defaultValue={dayjs('2022-04-17')} readOnly />
</DemoItem>

Press Enter to start editing

Views

The component can contain three views: day, month, and year. By default, only the day and year views are enabled.

You can customize the enabled views using the views prop. Views will appear in the order they're included in the views array.

"year", "month" and "day"

April 2022

SMTWTFS

"day"

April 2024

SMTWTFS

"month" and "year"

April 2022

<DemoItem label={'"year", "month" and "day"'}>
  <DateCalendar
    defaultValue={dayjs('2022-04-17')}
    views={['year', 'month', 'day']}
  />
</DemoItem>
<DemoItem label={'"day"'}>
  <DateCalendar views={['day']} />
</DemoItem>
<DemoItem label={'"month" and "year"'}>
  <DateCalendar
    defaultValue={dayjs('2022-04-17')}
    views={['month', 'year']}
    openTo="month"
  />
</DemoItem>

<DemoItem label={'"year", "month" and "day"'}>
  <DateCalendar
    defaultValue={dayjs('2022-04-17')}
    views={['year', 'month', 'day']}
  />
</DemoItem>
<DemoItem label={'"day"'}>
  <DateCalendar views={['day']} />
</DemoItem>
<DemoItem label={'"month" and "year"'}>
  <DateCalendar
    defaultValue={dayjs('2022-04-17')}
    views={['month', 'year']}
    openTo="month"
  />
</DemoItem>

Press Enter to start editing

Choose the initial year / month

If value or defaultValue contains a valid date, this date will be used to choose which month to render in the day view and which year to render in the month view. If both value and defaultValue contain no valid date, the component will try to find a month and year that satisfies the validation rules.

You can override this date using the referenceDate, in the example below the calendar renders April 2022 even though no date is visually selected:

April 2022

SMTWTFS

<DateCalendar
  referenceDate={dayjs('2022-04-17')}
  views={['year', 'month', 'day']}
/>

<DateCalendar
  referenceDate={dayjs('2022-04-17')}
  views={['year', 'month', 'day']}
/>

Press Enter to start editing

Month and Year Calendar

If you only need the year view or the month view, you can use the YearCalendar / MonthCalendar components:

YearCalendar

MonthCalendar

Day view customization

Show additional days

To show all days of displayed weeks, including those outside of the current month, use showDaysOutsideCurrentMonth.

By default, only weeks of the current month are displayed, but you can provide a total number of weeks to display with fixedWeekNumber prop. This value is usually set to 6 for Gregorian calendars, because month display can vary between 4 and 6 weeks.

April 2024

SMTWTFS

<DateCalendar showDaysOutsideCurrentMonth fixedWeekNumber={6} />

<DateCalendar showDaysOutsideCurrentMonth fixedWeekNumber={6} />

Press Enter to start editing

Display week number

To display week number, use the displayWeekNumber. You can customize the calendar week header by using the localization key localeText.calendarWeekNumberHeaderText. You can also customize what's rendered as a calendar week number, using a callback for the localization key localeText.calendarWeekNumberText.

April 2024

#SMTWTFS

14.

15.

16.

17.

18.

<DateCalendar displayWeekNumber />

<DateCalendar displayWeekNumber />

Press Enter to start editing

Week picker

You can select the whole week using the day component slot:

April 2022

#SMTWTFS

<DateCalendar
  value={value}
  onChange={(newValue) => setValue(newValue)}
  showDaysOutsideCurrentMonth
  displayWeekNumber
  slots={{ day: Day }}
  slotProps={{
    day: (ownerState) =>
      ({
        selectedDay: value,
        hoveredDay,
        onPointerEnter: () => setHoveredDay(ownerState.day),
        onPointerLeave: () => setHoveredDay(null),
      }) as any,
  }}
/>

<DateCalendar
  value={value}
  onChange={(newValue) => setValue(newValue)}
  showDaysOutsideCurrentMonth
  displayWeekNumber
  slots={{ day: Day }}
  slotProps={{
    day: (ownerState) =>
      ({
        selectedDay: value,
        hoveredDay,
        onPointerEnter: () => setHoveredDay(ownerState.day),
        onPointerLeave: () => setHoveredDay(null),
      }) as any,
  }}
/>

Press Enter to start editing

Dynamic data

Sometimes it may be necessary to display additional info right in the calendar. The following demo shows how to add a badge on some day based on server-side data:

April 2022

SMTWTFS

🌚🌚

🌚

<DateCalendar
  defaultValue={initialValue}
  loading={isLoading}
  onMonthChange={handleMonthChange}
  renderLoading={() => <DayCalendarSkeleton />}
  slots={{
    day: ServerDay,
  }}
  slotProps={{
    day: {
      highlightedDays,
    } as any,
  }}
/>

<DateCalendar
  defaultValue={initialValue}
  loading={isLoading}
  onMonthChange={handleMonthChange}
  renderLoading={() => <DayCalendarSkeleton />}
  slots={{
    day: ServerDay,
  }}
  slotProps={{
    day: {
      highlightedDays,
    } as any,
  }}
/>

Press Enter to start editing

Localization

See the Date format and localization and Translated components documentation pages for more details.

Validation

See the Validation documentation page for more details.

API

See the documentation below for a complete reference to all of the props and classes available to the components mentioned here.