DatePicker

Inline date, multiple dates and dates range picker

Import

Source

View source code

Docs

Edit this page

Package

@asuikit/dates

Usage

import { useState } from 'react';
import { Group } from '@asuikit/core';
import { DatePicker } from '@asuikit/dates';

function Demo() {
  const [value, setValue] = useState<Date | null>(null);
  return (
    <Group position="center">
      <DatePicker value={value} onChange={setValue} />
    </Group>
  );
}

Set allowDeselect to allow user to deselect current selected date by clicking on it. allowDeselect is disregarded when type prop is range or multiple. When date is deselected onChange is called with null.

import { useState } from 'react';
import { Group } from '@asuikit/core';
import { DatePicker } from '@asuikit/dates';

function Demo() {
  const [value, setValue] = useState<Date | null>(null);
  return (
    <Group position="center">
      <DatePicker allowDeselect value={value} onChange={setValue} />
    </Group>
  );
}

Multiple dates

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

import { useState } from 'react';
import { Group } from '@asuikit/core';
import { DatePicker } from '@asuikit/dates';

function Demo() {
  const [value, setValue] = useState<Date[]>([]);
  return (
    <Group position="center">
      <DatePicker type="multiple" value={value} onChange={setValue} />
    </Group>
  );
}

Dates range

Set type="range" to allow user to pick dates range:

import { useState } from 'react';
import { Group } from '@asuikit/core';
import { DatePicker } from '@asuikit/dates';

function Demo() {
  const [value, setValue] = useState<[Date | null, Date | null]>([null, null]);
  return (
    <Group position="center">
      <DatePicker type="range" value={value} onChange={setValue} />
    </Group>
  );
}

Single date in range

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

import { useState } from 'react';
import { Group } from '@asuikit/core';
import { DatePicker } from '@asuikit/dates';

function Demo() {
  const [value, setValue] = useState<[Date | null, Date | null]>([null, null]);
  return (
    <Group position="center">
      <DatePicker type="range" allowSingleDateInRange value={value} onChange={setValue} />
    </Group>
  );
}

Default date

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

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

import { useState } from 'react';
import { Group } from '@asuikit/core';
import { DatePicker } from '@asuikit/dates';

function Demo() {
  const [value, setValue] = useState<Date | null>(null);
  return (
    <Group position="center">
      <DatePicker defaultDate={new Date(2015, 1)} value={value} onChange={setValue} />
    </Group>
  );
}

Controlled date

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

import { Group } from '@asuikit/core';
import { DatePicker } from '@asuikit/dates';

function Demo() {
  const [value, setValue] = useState<[Date | null, Date | null]>([null, null]);
  const [date, setDate] = useState(new Date());

  const handleChange = (val: [Date | null, Date | null]) => {
    if (val[0] !== null && val[1] === null) {
      setDate((current) => new Date(current.getFullYear() + 1, 1));
    }

    setValue(val);
  };

  return (
    <Group position="center">
      <DatePicker
        date={date}
        onDateChange={setDate}
        type="range"
        value={value}
        onChange={handleChange}
      />
    </Group>
  );
}

Default level

Set defaultLevel prop to configure initial level that will be displayed:

2020 – 2029

import { Group } from '@asuikit/core';
import { DatePicker } from '@asuikit/dates';

function Demo() {
  return (
    <Group position="center">
      <DatePicker defaultLevel="decade" />
      <DatePicker defaultLevel="year" />
    </Group>
  );
}

Hide outside dates

Set hideOutsideDates prop to remove all dates that do not belong to the current month:

import { Group } from '@asuikit/core';
import { DatePicker } from '@asuikit/dates';

function Demo() {
  return (
    <Group position="center">
      <DatePicker hideOutsideDates />
    </Group>
  );
}

First day of week

Set firstDayOfWeek prop to configure first day of week. The prop accepts number from 0 to 6, where 0 is Sunday and 6 is Saturday. Default value is 1 – Monday. You can also configure this option for all components with DatesProvider.

import { Group } from '@asuikit/core';
import { DatePicker } from '@asuikit/dates';

function Demo() {
  return (
    <Group position="center">
      <DatePicker firstDayOfWeek={0} />
      <DatePicker firstDayOfWeek={6} />
    </Group>
  );
}

Hide weekdays

Set hideWeekdays prop to hide weekdays names:

import { Group } from '@asuikit/core';
import { DatePicker } from '@asuikit/dates';

function Demo() {
  return (
    <Group position="center">
      <DatePicker hideWeekdays />
    </Group>
  );
}

Weekend days

Use weekendDays prop to configure weekend days. The prop accepts an array of numbers from 0 to 6, where 0 is Sunday and 6 is Saturday. Default value is [0, 6] – Saturday and Sunday. You can also configure this option for all components with DatesProvider.

import { Group } from '@asuikit/core';
import { DatePicker } from '@asuikit/dates';

function Demo() {
  return (
    <Group position="center">
      <DatePicker weekendDays={[1, 2]} />
    </Group>
  );
}

Render day function

You can customize day rendering with renderDay prop. For example, it can be used to add Indicator to certain days.

import { Group, Indicator } from '@asuikit/core';
import { DatePicker } from '@asuikit/dates';

function Demo() {
  return (
    <Group position="center">
      <DatePicker
        renderDay={(date) => {
          const day = date.getDate();
          return (
            <Indicator size={6} color="red" offset={-5} disabled={day !== 16}>
              <div>{day}</div>
            </Indicator>
          );
        }}
      />
    </Group>
  );
}

Min and max date

Set minDate and maxDate props to define min and max dates. If previous/next page is not available then corresponding control will be disabled.

import { useState } from 'react';
import { Group } from '@asuikit/core';
import { DatePicker } from '@asuikit/dates';

function Demo() {
  const [value, setValue] = useState<Date | null>(null);
  return (
    <Group position="center">
      <DatePicker
        value={value}
        onChange={setValue}
        defaultDate={new Date(2022, 1)}
        minDate={new Date(2022, 1, 1)}
        maxDate={new Date(2022, 8, 1)}
      />
    </Group>
  );
}

Add props to year and month control

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

import { useState } from 'react';
import { Group } from '@asuikit/core';
import { DatePicker } from '@asuikit/dates';

function Demo() {
  const [value, setValue] = useState<Date | null>(null);
  return (
    <Group position="center">
      <DatePicker
        value={value}
        onChange={setValue}
        defaultDate={new Date(2021, 7)}
        getDayProps={(date) => {
          if (date.getDay() === 5 && date.getDate() === 13) {
            return {
              sx: (theme) => ({
                backgroundColor: theme.colors.red[theme.fn.primaryShade()],
                color: theme.white,
                ...theme.fn.hover({ backgroundColor: theme.colors.red[7] }),
              }),
            };
          }

          return {};
        }}
        getYearControlProps={(date) => {
          if (date.getFullYear() === new Date().getFullYear()) {
            return {
              sx: (theme) => ({
                color: theme.fn.primaryColor(),
                fontWeight: 700,
              }),
            };
          }

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

          return {};
        }}
        getMonthControlProps={(date) => {
          if (date.getMonth() === 1) {
            return {
              sx: (theme) => ({
                color: theme.fn.primaryColor(),
                fontWeight: 700,
              }),
            };
          }

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

          return {};
        }}
      />
    </Group>
  );
}

Number of columns

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

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

import { useState } from 'react';
import { Group } from '@asuikit/core';
import { DatePicker } from '@asuikit/dates';

function Demo() {
  const [value, setValue] = useState<[Date | null, Date | null]>([null, null]);
  return (
    <Group position="center">
      <DatePicker type="range" numberOfColumns={2} value={value} onChange={setValue} />
    </Group>
  );
}

Max level

April 2024

import { Group } from '@asuikit/core';
import { DatePicker } from '@asuikit/dates';

function Demo() {
  return (
    <Group position="center">
      <DatePicker maxLevel="year" />
      <DatePicker maxLevel="month" />
    </Group>
  );
}

Size

import { DatePicker } from '@asuikit/dates';

function Demo() {
  return <DatePicker defaultValue={new Date()} />
}

Change year and months controls format

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

import { Group } from '@asuikit/core';
import { DatePicker } from '@asuikit/dates';

function Demo() {
  return (
    <Group position="center">
      <DatePicker monthsListFormat="MM" yearsListFormat="YY" />
    </Group>
  );
}

Change label format

Use decadeLabelFormat, yearLabelFormat and monthLabelFormat props to change dayjs format of decade/year label:

20 – 29

import { useState } from 'react';
import { Group } from '@asuikit/core';
import { DatePicker } from '@asuikit/dates';

function Demo() {
  const [value, setValue] = useState<Date | null>(null);
  return (
    <Group position="center">
      <DatePicker
        defaultLevel="decade"
        decadeLabelFormat="YY"
        yearLabelFormat="YYYY [year]"
        monthLabelFormat="MM/YY"
        value={value}
        onChange={setValue}
      />
    </Group>
  );
}

Localization

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

import 'dayjs/locale/ru';
import { Group } from '@asuikit/core';
import { DatePicker } from '@asuikit/dates';

function Demo() {
  return (
    <Group position="center">
      <DatePicker locale="ru" />
    </Group>
  );
}

Accessibility

Aria labels

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

import { DatePicker } from '@asuikit/dates';

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

Year/month control aria-label

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

import { DatePicker } from '@asuikit/dates';

function Demo() {
  return (
    <DatePicker
      getDayProps={(date) => ({
        'aria-label': `Select date ${date.getMonth() + 1}/${date.getDate()}/${date.getFullYear()}`,
      })}
      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 date control.

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

Go back

DateInput – @asuikit/dates

Up next

DatePickerInput – @asuikit/dates

DatePicker component props

Name	Type	Description
allowDeselect	boolean	Determines whether user can deselect the date by clicking on selected item, applicable only when type="default"
allowSingleDateInRange	boolean	Determines whether single year can be selected as range, applicable only when type="range"
ariaLabels	CalendarAriaLabels	aria-label attributes for controls on different levels
columnsToScroll	number	Number of columns to scroll when user clicks next/prev buttons, defaults to numberOfColumns
date	Date	Date that is displayed, used for controlled component
decadeLabelFormat	string \| ((startOfDecade: Date, endOfDecade: Date) => ReactNode)	dayjs label format to display decade label or a function that returns decade label based on date value, defaults to "YYYY"
defaultDate	Date	Initial date that is displayed, used for uncontrolled component
defaultLevel	"month" \| "year" \| "decade"	Initial level displayed to the user (decade, year, month), used for uncontrolled component
defaultValue	Date \| DatesRangeValue \| Date[]	Default value for uncontrolled component
excludeDate	(date: Date) => boolean	Callback function to determine whether the day should be disabled
firstDayOfWeek	0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6	number 0-6, 0 – Sunday, 6 – Saturday, defaults to 1 – Monday
getDayAriaLabel	(date: Date) => string	Assigns aria-label to days based on date
getDayProps	(date: Date) => Partial<DayProps>	Adds props to Day component based on date
getMonthControlProps	(date: Date) => Partial<PickerControlProps>	Adds props to month picker control based on date
getYearControlProps	(date: Date) => Partial<PickerControlProps>	Adds props to year picker control based on date
hideOutsideDates	boolean	Determines whether outside dates should be hidden, defaults to false
hideWeekdays	boolean	Determines whether weekdays row should be hidden, defaults to false
level	"month" \| "year" \| "decade"	Current level displayed to the user (decade, year, month), used for controlled component
locale	string	dayjs locale, defaults to value defined in DatesProvider
maxDate	Date	Maximum possible date
maxLevel	"month" \| "year" \| "decade"	Max level that user can go up to (decade, year, month), defaults to decade
minDate	Date	Minimum possible date
monthLabelFormat	string \| ((month: Date) => ReactNode)	dayjs label format to display month label or a function that returns month label based on month value, defaults to "MMMM YYYY"
monthsListFormat	string	dayjs format for months list
nextIcon	ReactNode	Change next icon
nextLabel	string	aria-label for next button
numberOfColumns	number	Number of columns to render next to each other
onChange	(value: DatePickerValue<Type>) => void	Called when value changes
onDateChange	(date: Date) => void	Called when date changes
onLevelChange	(level: CalendarLevel) => void	Called when level changes
onMonthMouseEnter	(event: MouseEvent<HTMLButtonElement, MouseEvent>, date: Date) => void	Called when mouse enters month control
onMonthSelect	(date: Date) => void	Called when user clicks month on year level
onNextDecade	(date: Date) => void	Called when next decade button is clicked
onNextMonth	(date: Date) => void	Called when next month button is clicked
onNextYear	(date: Date) => void	Called when next year button is clicked
onPreviousDecade	(date: Date) => void	Called when previous decade button is clicked
onPreviousMonth	(date: Date) => void	Called when previous month button is clicked
onPreviousYear	(date: Date) => void	Called when previous year button is clicked
onYearMouseEnter	(event: MouseEvent<HTMLButtonElement, MouseEvent>, date: Date) => void	Called when mouse enters year control
onYearSelect	(date: Date) => void	Called when user clicks year on decade level
previousIcon	ReactNode	Change previous icon
previousLabel	string	aria-label for previous button
renderDay	(date: Date) => ReactNode	Controls day value rendering
size	"xs" \| "sm" \| "md" \| "lg" \| "xl"	Component size
type	"default" \| "multiple" \| "range"	Picker type: range, multiple or default
value	Date \| DatesRangeValue \| Date[]	Value for controlled component
weekdayFormat	string \| ((date: Date) => ReactNode)	dayjs format for weekdays names, defaults to "dd"
weekendDays	DayOfWeek[]	Indices of weekend days, 0-6, where 0 is Sunday and 6 is Saturday, defaults to value defined in DatesProvider
withCellSpacing	boolean	Determines whether controls should be separated by spacing, true by default
yearLabelFormat	string \| ((year: Date) => ReactNode)	dayjs label format to display year label or a function that returns year label based on year value, defaults to "YYYY"
yearsListFormat	string	dayjs format for years list

DatePicker component Styles API

Name	Static selector	Description
calendar	.asuikit-DatePicker-calendar	Calendar root element
calendarHeader	.asuikit-DatePicker-calendarHeader	Calendar header root element
calendarHeaderControl	.asuikit-DatePicker-calendarHeaderControl	Previous/next calendar header controls
calendarHeaderControlIcon	.asuikit-DatePicker-calendarHeaderControlIcon	Icon of previous/next calendar header controls
calendarHeaderLevel	.asuikit-DatePicker-calendarHeaderLevel	Level control (changes levels when clicked, month -> year -> decade)
decadeLevelGroup	.asuikit-DatePicker-decadeLevelGroup	Group of decades levels
decadeLevel	.asuikit-DatePicker-decadeLevel	Decade level root element
pickerControl	.asuikit-DatePicker-pickerControl	Button used to pick months and years
yearsList	.asuikit-DatePicker-yearsList	Years list table element
yearsListRow	.asuikit-DatePicker-yearsListRow	Years list row element
yearsListCell	.asuikit-DatePicker-yearsListCell	Years list cell element
yearLevelGroup	.asuikit-DatePicker-yearLevelGroup	Group of year levels
yearLevel	.asuikit-DatePicker-yearLevel	Year level root element
monthsList	.asuikit-DatePicker-monthsList	Months list table element
monthsListRow	.asuikit-DatePicker-monthsListRow	Months list table row element
monthsListCell	.asuikit-DatePicker-monthsListCell	Months list table cell element
monthLevelGroup	.asuikit-DatePicker-monthLevelGroup	Group or month levels
monthLevel	.asuikit-DatePicker-monthLevel	Month level root element
monthThead	.asuikit-DatePicker-monthThead	thead element of month table
monthRow	.asuikit-DatePicker-monthRow	tr element of month table
monthTbody	.asuikit-DatePicker-monthTbody	tbody element of month table
monthCell	.asuikit-DatePicker-monthCell	td element of month table
month	.asuikit-DatePicker-month	Month table element
weekdaysRow	.asuikit-DatePicker-weekdaysRow	Weekdays tr element
weekday	.asuikit-DatePicker-weekday	Weekday th element
day	.asuikit-DatePicker-day	Month day control

Learn more about Styles API

Build fully functional accessible web applications faster than ever

About

Contribute About Mantine Changelog Releases

Community

Chat on Discord Follow on Twitter Follow on GitHub GitHub discussions

Project

Mantine UI Documentation GitHub organization npm organization

Built by Vitaly Rtishchev and these awesome people

Join Discord community

Follow Mantine on Twitter

пн	вт	ср	чт	пт	сб	вс