YearPickerInput

Inline year, multiple years and years range picker

YearPicker props

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

YearPickerInput with uncontrolled forms

Set name to submit the first day of the selected year as YYYY-MM-DD:

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

function Demo() {
  return (
    <form
      onSubmit={(event) => {
        event.preventDefault();
        const data = new FormData(event.currentTarget);
        console.log(data.get('year'));
      }}
    >
      <YearPickerInput name="year" label="Year" defaultValue="2025-01-01" />
      <button type="submit">Submit</button>
    </form>
  );
}

Usage

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

function Demo() {
  const [value, setValue] = useState<string | null>(null);
  return (
    <YearPickerInput
      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 { YearPickerInput } from '@mantine/dates';

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

Set valueDisplay="pills" to show every selected year as a pill with a remove button, the same way MultiSelect shows its values. Backspace in the input removes the last year:

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

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

Dates range

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

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

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

Presets

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

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

function Demo() {
  return (
    <YearPickerInput
      label="With presets"
      placeholder="Select year"
      presets={[
        { value: dayjs().startOf('year').format('YYYY-MM-DD'), label: 'This year' },
        { value: dayjs().add(1, 'year').startOf('year').format('YYYY-MM-DD'), label: 'Next year' },
        { value: dayjs().subtract(1, 'year').startOf('year').format('YYYY-MM-DD'), label: 'Last year' },
        { value: dayjs().add(5, 'year').startOf('year').format('YYYY-MM-DD'), label: 'In 5 years' },
        { value: dayjs().subtract(5, 'year').startOf('year').format('YYYY-MM-DD'), label: '5 years ago' },
      ]}
    />
  );
}

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

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

function Demo() {
  const today = dayjs();

  return (
    <YearPickerInput
      type="range"
      label="With presets"
      placeholder="Select years range"
      presets={[
        {
          value: [today.subtract(2, 'year').startOf('year').format('YYYY-MM-DD'), today.startOf('year').format('YYYY-MM-DD')],
          label: 'Last 2 years',
        },
        {
          value: [today.subtract(5, 'year').startOf('year').format('YYYY-MM-DD'), today.startOf('year').format('YYYY-MM-DD')],
          label: 'Last 5 years',
        },
        {
          value: [today.startOf('year').format('YYYY-MM-DD'), today.add(5, 'year').startOf('year').format('YYYY-MM-DD')],
          label: 'Next 5 years',
        },
        {
          value: [
            today.subtract(10, 'year').startOf('year').format('YYYY-MM-DD'),
            today.startOf('year').format('YYYY-MM-DD'),
          ],
          label: 'Last decade',
        },
      ]}
    />
  );
}

Controlling with useYearPickerInput

YearPickerInput component supports the controller pattern. Use the useYearPickerInput hook to manage YearPickerInput state:

Dropdown closed, displayed decade: none

import { useState } from 'react';
import { Button, Group, Stack, Text } from '@mantine/core';
import { YearPickerInput, useYearPickerInput } from '@mantine/dates';

function Demo() {
  const [value, setValue] = useState<string | null>('2024-01-01');
  const controller = useYearPickerInput();

  return (
    <Stack>
      <Group>
        <Button
          variant="default"
          onClick={() => {
            controller.openDropdown();
            controller.previous();
          }}
        >
          Previous decade
        </Button>
        <Button
          variant="default"
          onClick={() => {
            controller.openDropdown();
            controller.next();
          }}
        >
          Next decade
        </Button>
      </Group>

      <YearPickerInput
        label="Pick year"
        placeholder="Pick year"
        value={value}
        onChange={setValue}
        controller={controller}
      />

      <Text size="sm" c="dimmed">
        Dropdown {controller.isDropdownOpened() ? 'opened' : 'closed'}, displayed{' '}
        {controller.getDisplayedLevel()}: {controller.getDisplayedDate() ?? 'none'}
      </Text>
    </Stack>
  );
}

Every time the dropdown opens, the displayed decade is reset to the selected value (or to defaultDate when there is no value). To open on a different decade, call next, previous or setDate right after openDropdown, as the demo above does. YearPickerInput only displays the decade level, so setLevel has no effect.

The controller does not own the selected value – keep using value/onChange (or your form library) for it. When the controller prop is set, the date, defaultDate, onDateChange, popoverProps.opened and popoverProps.onChange props are ignored – pass them to useYearPickerInput instead (dropdownOpened and onDropdownOpenedChange replace popoverProps.opened and popoverProps.onChange).

openDropdown does nothing while the input is disabled or readOnly. With type="range", closing the dropdown when only the first year of the range is picked clears the value, whether the dropdown is closed by the user or with closeDropdown.

If you only need the dropdown state, popoverProps={{ opened, onChange }} controls it without a controller in every dropdown type (popover, modal and drawer): onChange is called on every open and close, including the input click and the close after a pick, and the input keeps opening and closing the dropdown through it.

The controller is typed as PickerInputController and its options as PickerInputControllerOptions, both exported from @mantine/dates. The same types are used by DatePickerInput, MonthPickerInput, YearPickerInput, WeekPickerInput and QuarterPickerInput.

Dropdown type

The dropdown opens in a bottom Drawer below theme.breakpoints.sm and in a Popover above. Set dropdownType to 'popover', 'modal', 'drawer' or an object with breakpoints:

import { Stack } from '@mantine/core';
import { YearPickerInput } from '@mantine/dates';

function Demo() {
  return (
    <Stack>
      <YearPickerInput dropdownType="drawer" label="Drawer" placeholder="Pick date" />
      <YearPickerInput dropdownType="modal" label="Modal" placeholder="Pick date" />
      <YearPickerInput dropdownType="popover" label="Popover" placeholder="Pick date" />
      <YearPickerInput
        dropdownType={{ base: 'drawer', 600: 'popover' }}
        label="Drawer below 600px, popover above"
        placeholder="Pick date"
      />
    </Stack>
  );
}

Object keys can be theme.breakpoints keys or custom values in px, for example, { base: 'drawer', 600: 'popover' }. Use popoverProps, modalProps and drawerProps to pass props down to the underlying component. If the viewport crosses a breakpoint while the dropdown is open, the dropdown switches to the other type and a selection that was not applied yet is discarded.

Submit button

In drawer and modal dropdowns, the value is applied only when the submit button is pressed, and closing the dropdown discards the selection. Set applyOnSubmit={false} to apply the value on selection:

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

function Demo() {
  return (
    <YearPickerInput
      dropdownType="drawer"
      applyOnSubmit={false}
      label="Applied on selection"
      placeholder="Pick date"
    />
  );
}
  • The label is Save by default – change it with the submitButtonLabel prop or the submitButtonLabel setting of DatesProvider
  • submitButtonProps are passed down to the Button
  • With type="range", the button is disabled until both dates are selected

Value format

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

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

function Demo() {
  return (
    <YearPickerInput valueFormat="YY" type="multiple" label="Pick year" placeholder="Pick year" />
  );
}

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 { YearPickerInput, 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 (
    <YearPickerInput
      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 { YearPickerInput } from '@mantine/dates';

function Demo() {
  return (
    <YearPickerInput
      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 { YearPickerInput } from '@mantine/dates';

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

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

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

Disabled state

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

function Demo() {
  return (
    <YearPickerInput
      valueFormat="YY"
      type="multiple"
      label="Disabled"
      placeholder="Pick year"
      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 { YearPickerInput } from '@mantine/dates';

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

Control props

getYearControlProps prop allows 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 { YearPickerInput, YearPickerInputProps } from '@mantine/dates';

const getYearControlProps: YearPickerInputProps['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 (
    <YearPickerInput
      label="Pick year"
      placeholder="Pick year"
      value={value}
      onChange={setValue}
      getYearControlProps={getYearControlProps}
    />
  );
}

Year label format

yearsListFormat props allow changing the format of the year label in the years list. It accepts a dayjs format string.

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

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

Decade label format

decadeLabelFormat prop allows changing the format of the decade label in the header. It accepts a dayjs format string.

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

function Demo() {
  const [value, setValue] = useState<string | null>(null);
  return (
    <YearPickerInput
      decadeLabelFormat="YY"
      label="Pick year"
      placeholder="Pick year"
      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 { YearPickerInput } from '@mantine/dates';

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

With icon

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

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

Get element ref

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

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

Accessibility

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

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

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

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

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

// Accessible input – it has aria-label
function Demo() {
  return <YearPickerInput 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 { YearPickerInput } from '@mantine/core';

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