Mantine UIFAQColors generator

MonthPickerInput

Month, multiple months and months range picker input

Source

View source code

LLM docs

LLM documentation

Docs

Edit this page

PackageIcon

@mantine/dates

MonthPicker props

MonthPickerInput supports most of the MonthPicker props. Read through the MonthPicker documentation to learn about all component features that are not listed on this page.

Usage

import { useState } from 'react';
import { MonthPickerInput } from '@mantine/dates';

function Demo() {
  const [value, setValue] = useState<string | null>(null);
  return (
    <MonthPickerInput
      label="Pick date"
      placeholder="Pick date"
      value={value}
      onChange={setValue}
    />
  );
}

Multiple dates

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

import { useState } from 'react';
import { MonthPickerInput } from '@mantine/dates';

function Demo() {
  const [value, setValue] = useState<string[]>([]);
  return (
    <MonthPickerInput
      type="multiple"
      label="Pick dates"
      placeholder="Pick dates"
      value={value}
      onChange={setValue}
    />
  );
}

Dates range

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

import { useState } from 'react';
import { MonthPickerInput } from '@mantine/dates';

function Demo() {
  const [value, setValue] = useState<[string | null, string | null]>([null, null]);
  return (
    <MonthPickerInput
      type="range"
      label="Pick dates range"
      placeholder="Pick dates range"
      value={value}
      onChange={setValue}
    />
  );
}

Open picker in modal

By default, MonthPicker is rendered inside Popover. You can change that to Modal by setting dropdownType="modal":

import { useState } from 'react';
import { MonthPickerInput } from '@mantine/dates';

function Demo() {
  const [value, setValue] = useState<string | null>(null);
  return (
    <MonthPickerInput
      dropdownType="modal"
      label="Pick date"
      placeholder="Pick date"
      value={value}
      onChange={setValue}
    />
  );
}

Value format

Use the valueFormat prop to change the dayjs format of the value label:

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

function Demo() {
  return (
    <MonthPickerInput
      valueFormat="YYYY MMM"
      type="multiple"
      label="Pick month"
      placeholder="Pick month"
    />
  );
}

Value formatter

valueFormatter is a more powerful alternative to the valueFormat prop. It allows formatting the value label with a custom function. The function is the same for all component types (default, multiple and range) – you need to perform additional checks inside the function to handle different types.

Example of using a custom formatter function with type="multiple":

import dayjs from 'dayjs';
import { useState } from 'react';
import { MonthPickerInput, DateFormatter } from '@mantine/dates';

const formatter: DateFormatter = ({ type, date, locale, format }) => {
  if (type === 'multiple' && Array.isArray(date)) {
    if (date.length === 1) {
      return dayjs(date[0]).locale(locale).format(format);
    }

    if (date.length > 1) {
      return `${date.length} dates selected`;
    }

    return '';
  }

  return '';
};

function Demo() {
  const [value, setValue] = useState<string[]>([]);

  return (
    <MonthPickerInput
      label="Pick 2 dates or more"
      placeholder="Pick 2 dates or more"
      value={value}
      onChange={setValue}
      type="multiple"
      valueFormatter={formatter}
    />
  );
}

Clearable

Set the clearable prop to display a clear button in the right section. Note that if you set the rightSection prop, the clear button will not be displayed.

import dayjs from 'dayjs';
import { MonthPickerInput } from '@mantine/dates';

function Demo() {
  return (
    <MonthPickerInput
      clearable
      defaultValue={dayjs().format('YYYY-MM-DD')}
      label="Pick date"
      placeholder="Pick date"
    />
  );
}

Clear section mode

The clearSectionMode prop determines how the clear button and rightSection are rendered:

  • 'both' (default) – render both the clear button and rightSection
  • 'rightSection' – render only the user-supplied rightSection, ignore clear button
  • 'clear' – render only the clear button, ignore rightSection
import { CaretDownIcon } from '@phosphor-icons/react';
import { Stack } from '@mantine/core';
import { MonthPickerInput } from '@mantine/dates';

function Demo() {
  return (
    <Stack>
      <MonthPickerInput
        label="clearSectionMode='both' (default)"
        placeholder="Pick month"
        defaultValue={new Date()}
        clearable
        rightSection={<CaretDownIcon size={16} />}
        clearSectionMode="both"
      />

      <MonthPickerInput
        label="clearSectionMode='rightSection'"
        placeholder="Pick month"
        defaultValue={new Date()}
        clearable
        rightSection={<CaretDownIcon size={16} />}
        clearSectionMode="rightSection"
      />

      <MonthPickerInput
        label="clearSectionMode='clear'"
        placeholder="Pick month"
        defaultValue={new Date()}
        clearable
        rightSection={<CaretDownIcon size={16} />}
        clearSectionMode="clear"
      />
    </Stack>
  );
}

Disabled state

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

function Demo() {
  return (
    <MonthPickerInput
      valueFormat="YYYY MMM"
      type="multiple"
      label="Disabled"
      placeholder="Pick month"
      disabled
    />
  );
}

Min and max dates

minDate and maxDate props define the minimum and maximum dates that can be picked. You can specify minDate and maxDate as Date objects:

import { useState } from 'react';
import { MonthPickerInput } from '@mantine/dates';

function Demo() {
  const [value, setValue] = useState<string | null>(null);
  return (
    <MonthPickerInput
      label="Pick month"
      placeholder="Pick month"
      value={value}
      onChange={setValue}
      minDate={new Date(2022, 1)}
      maxDate={new Date(2022, 8)}
    />
  );
}

Control props

getYearControlProps and getMonthControlProps props allow passing props to the control component based on the date. It is useful for disabling specific dates or customising styles/className.

import dayjs from 'dayjs';
import { useState } from 'react';
import { MonthPickerInput, MonthPickerInputProps } from '@mantine/dates';

const getYearControlProps: MonthPickerInputProps['getYearControlProps'] = (date) => {
  if (dayjs(date).year() === new Date().getFullYear()) {
    return {
      style: {
        color: 'var(--mantine-color-blue-filled)',
        fontWeight: 700,
      },
    };
  }

  if (dayjs(date).year() === new Date().getFullYear() + 1) {
    return { disabled: true };
  }

  return {};
};

const getMonthControlProps: MonthPickerInputProps['getMonthControlProps'] = (date) => {
  if (dayjs(date).month() === 1) {
    return {
      style: {
        color: 'var(--mantine-color-blue-filled)',
        fontWeight: 700,
      },
    };
  }

  if (dayjs(date).month() === 5) {
    return { disabled: true };
  }

  return {};
};

function Demo() {
  const [value, setValue] = useState<string | null>(null);
  return (
    <MonthPickerInput
      label="Pick month"
      placeholder="Pick month"
      value={value}
      onChange={setValue}
      getYearControlProps={getYearControlProps}
      getMonthControlProps={getMonthControlProps}
    />
  );
}

Label format

decadeLabelFormat and yearLabelFormat props allow changing the format of the label in the header. The props accept a dayjs format string.

import { useState } from 'react';
import { MonthPickerInput } from '@mantine/dates';

function Demo() {
  const [value, setValue] = useState<string | null>(null);
  return (
    <MonthPickerInput
      decadeLabelFormat="YY"
      yearLabelFormat="YYYY [year]"
      label="Pick month"
      placeholder="Pick month"
      value={value}
      onChange={setValue}
    />
  );
}

List format

monthsListFormat and yearsListFormat props allow changing the format of the month and year labels in the list. The props accept a dayjs format string.

import { useState } from 'react';
import { MonthPickerInput } from '@mantine/dates';

function Demo() {
  const [value, setValue] = useState<string | null>(null);
  return (
    <MonthPickerInput
      monthsListFormat="MM"
      yearsListFormat="YY"
      label="Pick month"
      placeholder="Pick month"
      value={value}
      onChange={setValue}
    />
  );
}

Max level

maxLevel prop allows to set the maximum level that can be reached by clicking on the label in the header.

import { useState } from 'react';
import { MonthPickerInput } from '@mantine/dates';

function Demo() {
  const [value, setValue] = useState<string | null>(null);
  return (
    <MonthPickerInput
      maxLevel="year"
      label="Pick month"
      placeholder="Pick month"
      value={value}
      onChange={setValue}
    />
  );
}

Input props

MonthPickerInput component supports Input and Input.Wrapper component features and all button element props. The MonthPickerInput documentation does not include all features supported by the component – see the Input documentation to learn about all available features.

Radius
Size
import { MonthPickerInput } from '@mantine/dates';

function Demo() {
  return (
    <MonthPickerInput
      placeholder="Pick date"
      label="Pick date"
      withAsterisk
    />
  );
}

With icon

import { useState } from 'react';
import { CalendarBlankIcon } from '@phosphor-icons/react';
import { MonthPickerInput } from '@mantine/dates';

function Demo() {
  const [value, setValue] = useState<string | null>(null);
  const icon = <CalendarBlankIcon size={18} />;
  return (
    <MonthPickerInput
      leftSection={<CalendarBlankIcon size={18} />}
      leftSectionPointerEvents="none"
      label="Pick date"
      placeholder="Pick date"
      value={value}
      onChange={setValue}
    />
  );
}

Get element ref

import { useRef } from 'react';
import { MonthPickerInput } from '@mantine/dates';

function Demo() {
  const ref = useRef<HTMLButtonElement>(null);
  return <MonthPickerInput ref={ref} />;
}

Accessibility

If MonthPickerInput is used without the label prop, it will not be announced properly by screen readers:

import { MonthPickerInput } from '@mantine/core';

// Inaccessible input – screen reader will not announce it properly
function Demo() {
  return <MonthPickerInput />;
}

Set aria-label to make the input accessible. In this case the label will not be visible, but screen readers will announce it:

import { MonthPickerInput } from '@mantine/core';

// Accessible input – it has aria-label
function Demo() {
  return <MonthPickerInput aria-label="My input" />;
}

If the label prop is set, the input will be accessible and it is not required to set aria-label:

import { MonthPickerInput } from '@mantine/core';

// Accessible input – it has associated label element
function Demo() {
  return <MonthPickerInput label="My input" />;
}

MonthPicker

YearPicker