YearPicker

Inline year, multiple years and years range picker

Source

View source code

LLM docs

LLM documentation

Docs

Edit this page

PackageIcon

@mantine/dates

Usage

2020 – 2029

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

function Demo() {
  const [value, setValue] = useState<string | null>(null);
  return <YearPicker value={value} onChange={setValue} />;
}

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.

2020 – 2029

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

function Demo() {
  const [value, setValue] = useState<string | null>(null);
  return <YearPicker allowDeselect value={value} onChange={setValue} />;
}

Multiple dates

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

2020 – 2029

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

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

Dates range

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

2020 – 2029

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

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

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.

2020 – 2029

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

function Demo() {
  const [value, setValue] = useState<[string | null, string | null]>([null, null]);
  return (
    <YearPicker type="range" allowSingleDateInRange value={value} onChange={setValue} />
  );
}

Default date

Use the defaultDate prop to set the date value that will be used to determine which decade should be displayed initially. For example, to display the 2040 – 2049 decade, set defaultDate={new Date(2040, 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.

2040 – 2049

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

function Demo() {
  const [value, setValue] = useState<string | null>(null);
  return <YearPicker defaultDate="2040-02-01" value={value} onChange={setValue} />;
}

Controlled date

Set the date and onDateChange props to make the currently displayed 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 20 years to the current date value:

2020 – 2029

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

function Demo() {
  const [value, setValue] = useState<[string | null, string | null]>([null, null]);
  const [date, setDate] = useState(dayjs().format('YYYY-MM-DD'));

  const handleChange = (val: [string | null, string | null]) => {
    if (val[0] !== null && val[1] === null) {
      setDate((current) => dayjs(current).add(20, 'year').format('YYYY-MM-DD'));
    }

    setValue(val);
  };

  return (
    <YearPicker
      date={date}
      onDateChange={setDate}
      type="range"
      value={value}
      onChange={handleChange}
    />
  );
}

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.

2020 – 2029

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

function Demo() {
  const [value, setValue] = useState<string | null>(null);
  return (
    <YearPicker
      value={value}
      onChange={setValue}
      minDate="2021-02-01"
      maxDate="2028-02-01"
    />
  );
}

Add props to year control

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

2020 – 2029

import dayjs from 'dayjs';
import { useState } from 'react';
import { YearPicker, YearPickerProps } from '@mantine/dates';

const getYearControlProps: YearPickerProps['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 {};
};

function Demo() {
  const [value, setValue] = useState<string | null>(null);
  return <YearPicker value={value} onChange={setValue} getYearControlProps={getYearControlProps} />;
}

Number of columns

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

2020 – 2029

2030 – 2039

Demo is not available on small screens. Make your screen larger to see the demo.

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

function Demo() {
  const [value, setValue] = useState<[string | null, string | null]>([null, null]);
  return (
    <YearPicker type="range" numberOfColumns={2} value={value} onChange={setValue} />
  );
}

Full width

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

2020 – 2029

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

function Demo() {
  const [value, setValue] = useState<string | null>(null);
  return <YearPicker fullWidth value={value} onChange={setValue} />;
}

Size

2020 – 2029

Size

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

function Demo() {
  return <YearPicker defaultValue={dayjs().format('YYYY-MM-DD')} />;
}

Change year controls format

Use yearsListFormat to change the dayjs format of the year control:

2020 – 2029

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

function Demo() {
  const [value, setValue] = useState<string | null>(null);
  return <YearPicker yearsListFormat="YY" value={value} onChange={setValue} />;
}

Change decade label format

Use decadeLabelFormat to change the dayjs format of the decade label:

20 – 29

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

function Demo() {
  const [value, setValue] = useState<string | null>(null);
  return <YearPicker decadeLabelFormat="YY" value={value} onChange={setValue} />;
}

Accessibility

Aria labels

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

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

function Demo() {
  return (
    <YearPicker
      ariaLabels={{
        nextDecade: 'Next decade',
        previousDecade: 'Previous decade',
      }}
    />
  );
}

Year control aria-label

Use getYearControlProps to customize the aria-label attribute:

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

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

Keyboard interactions

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

Key	Description
`ArrowRight`	Focuses next non-disabled year
`ArrowLeft`	Focuses previous non-disabled year
`ArrowDown`	Focuses next non-disabled year in the same column
`ArrowUp`	Focuses previous non-disabled year in the same column

MonthPickerInput

YearPickerInput