Month Picker - Mantine

import { MonthPickerDemos } from '@docs/demos'; import { Layout } from '@/layout'; import { MDX_DATA } from '@/mdx';

export default Layout(MDX_DATA.MonthPicker);

Usage

Allow deselect

Set allowDeselect to allow users to deselect the currently selected date by clicking on it. allowDeselect is disregarded when the type prop is range or multiple. When a date is deselected, onChange is called with null.

Multiple dates

Set type="multiple" to allow users to pick multiple dates:

Dates range

Set type="range" to allow users to pick a date range:

Single date in range

By default, it is not allowed to select a single date as a range – when the user clicks the same date a second time, it is deselected. To change this behavior, set the allowSingleDateInRange prop. allowSingleDateInRange is ignored when the type prop is not range.

Presets

Use the presets prop to add custom month presets. Presets are displayed next to the calendar:

To use presets with type="range", define the value as a tuple of two dates:

Default date

Use the defaultDate prop to set the date value that will be used to determine which year should be displayed initially. For example, to display the 2015 year, set defaultDate={new Date(2015, 1)}. If the value is not specified, then defaultDate will use new Date(). Month, day, minutes and seconds are ignored in the provided date object, only the year is used – you can specify any date value.

Note that if you set the date prop, then the defaultDate value will be ignored.

Controlled date

Set the date and onDateChange props to make the currently displayed year and decade controlled. By doing so, you can customize the date picking experience. For example, when the user selects the first date in a range, you can add one year to the current date value:

Min and max date

Set the minDate and maxDate props to define minimum and maximum dates. If the previous/next page is not available, then the corresponding control will be disabled.

Add props to year and month control

You can add props to year and month controls with the getYearControlProps and getMonthControlProps functions. Both functions accept a date as a single argument, and props returned from the function will be added to the year/month control. For example, it can be used to disable a specific control or add styles:

Number of columns

Set the numberOfColumns prop to define the number of pickers that will be rendered side by side:

Max level

To disallow users from going to the decade level, set maxLevel="year":

Full width

Set the fullWidth prop to make the month picker stretch to fill 100% of its parent container width:

Size

Change year and months controls format

Use the yearsListFormat and monthsListFormat props to change the dayjs format of year/month controls:

Change label format

Use decadeLabelFormat and yearLabelFormat to change the dayjs format of the decade/year label:

Localization

Usually it is better to specify the @mantine/dates package locale in DatesProvider, but you can also override the locale per component:

Accessibility

Aria labels

Set the ariaLabels prop to specify aria-label attributes for next/previous controls:

tsx

import { MonthPicker } from '@mantine/dates';

function Demo() {
  return (
    <MonthPicker
      ariaLabels={{
        nextDecade: 'Next decade',
        previousDecade: 'Previous decade',
        nextYear: 'Next year',
        previousYear: 'Previous year',
        yearLevelControl: 'Change to decade view',
      }}
    />
  );
}

Year/month control aria-label

Use getYearControlProps/getMonthControlProps to customize the aria-label attribute:

tsx

import { MonthPicker } from '@mantine/dates';

function Demo() {
  return (
    <MonthPicker
      getYearControlProps={(date) => ({
        'aria-label': `Select year ${date.getFullYear()}`,
      })}
      getMonthControlProps={(date) => ({
        'aria-label': `Select month ${date.getFullYear()}/${date.getMonth()}`,
      })}
    />
  );
}

Keyboard interactions

Note that the following events will only trigger if focus is on a month control.