DatePicker

Capture date or dates range from user
Import

Usage

DatePicker component:

import { DatePicker } from '@mantine/dates';
function Demo() {
return <DatePicker placeholder="Pick date" label="Event date" withAsterisk />;
}

DateRangePicker component (supports the same props as DatePicker component):

import { useState } from 'react';
import { DateRangePicker, DateRangePickerValue } from '@mantine/dates';
function Demo() {
const [value, setValue] = useState<DateRangePickerValue>([
new Date(2021, 11, 1),
new Date(2021, 11, 5),
]);
return (
<DateRangePicker
label="Book hotel"
placeholder="Pick dates range"
value={value}
onChange={setValue}
/>
);
}

Controlled

import { useState } from 'react';
import { DatePicker } from '@mantine/dates';
function Demo() {
const [value, onChange] = useState(new Date());
return <DatePicker value={value} onChange={onChange} />;
}

Localization

All @mantine/dates components are built with dayjs library. Default locale is en, to change this follow dayjs localization guide:

// First import locale data
import 'dayjs/locale/ru';

Then set locale prop in component:

import 'dayjs/locale/ru';
import { DatePicker } from '@mantine/dates';
function Demo() {
return (
<DatePicker
locale="ru"
placeholder="Выберите дату"
label="Дата события"
defaultValue={new Date()}
/>
);
}

Custom day renderer

You can provide your own day renderer function with renderDay prop. For example, it can be used to wrap day with Indicator:

import { DatePicker } from '@mantine/dates';
import { Indicator } from '@mantine/core';
function Demo() {
return (
<DatePicker
placeholder="Pick date"
label="Event date"
renderDay={(date) => {
const day = date.getDate();
return (
<Indicator size={6} color="red" offset={8} disabled={day !== 16}>
<div>{day}</div>
</Indicator>
);
}}
/>
);
}

Level change

DatePicker supports three levels: date, month and year. User can access next level by clicking label between next/previous controls. To disable that, set allowLevelChange prop to false:

import { DatePicker } from '@mantine/dates';
function Demo() {
return <DatePicker allowLevelChange={false} placeholder="No level change" label="Event date" />;
}

First day of the week

Change first day of week with firstDayOfWeek prop. It accepts either sunday or monday as values:

import { DatePicker } from '@mantine/dates';
function Demo() {
return (
<DatePicker
label="Sunday as first day of week"
placeholder="Pick date"
firstDayOfWeek="sunday"
/>
);
}

Open calendar within modal

You can change the way calendar pop up on the page. Default variant is popover, set it to modal to display calendar in modal:

import { DatePicker } from '@mantine/dates';
function Demo() {
return <DatePicker dropdownType="modal" placeholder="Pick date" label="Event date" />;
}

In most cases, you would want to switch to modal when a certain breakpoint is reached. To implement this use use-media-query hook:

import { useMediaQuery } from '@mantine/hooks';
import { DatePicker } from '@mantine/dates';
function Demo() {
const isMobile = useMediaQuery('(max-width: 755px)');
return <DatePicker dropdownType={isMobile ? 'modal' : 'popover'} />;
}

Min and max dates

Set minDate and maxDate props to define minimum and maximum possible dates. Dates which are not included in available interval will be disabled:

import dayjs from 'dayjs';
import { DatePicker } from '@mantine/dates';
function Demo() {
return (
<DatePicker
placeholder="Pick date"
label="Event date"
minDate={dayjs(new Date()).startOf('month').add(5, 'days').toDate()}
maxDate={dayjs(new Date()).endOf('month').subtract(5, 'days').toDate()}
/>
);
}

Allow free input

By setting allowFreeInput prop you stop input from being readonly. With this option user is allowed to type date manually:

import { DatePicker } from '@mantine/dates';
function Demo() {
return <DatePicker allowFreeInput placeholder="Pick date" label="Event date" withAsterisk />;
}

By default, DatePicker will try to parse date using dayjs with given inputFormat, to change that provide dateParser function:

import { DatePicker } from '@mantine/dates';
function Demo() {
return (
<DatePicker allowFreeInput dateParser={(dateString) => new Date(Date.parse(dateString))} />
);
}

dateParser function should always return Date object. If parsed date is invalid when input is blurred value will be restored to last valid value.

Note that if you use the default dayjs parser, you will need to import and configure the customParseFormat dayjs plugin:

import customParseFormat from 'dayjs/plugin/customParseFormat';
dayjs.extend(customParseFormat);

Exclude dates

To exclude dates set excludeDate prop with function that receives date as an argument and returns true if date should be disabled. For example, to disable weekends, check if date day is 0 or 6:

import { DatePicker } from '@mantine/dates';
function Demo() {
return <DatePicker excludeDate={(date) => date.getDay() === 0 || date.getDay() === 6} />;
}

Add styles to days

You can apply styles to any day with dayStyle or dayClassName callbacks. Both functions receive two arguments:

  • date – date object which is used to render the day component
  • modifiers – modifiers that are applied to the day component

Modifiers

interface DayModifiers {
/** Is date selected and is first or last in range? */
selectedInRange: boolean;
/** Is date equal to value? */
selected: boolean;
/** Based on minDate, maxDate, excludeDate and disableOutsideEvents props */
disabled: boolean;
/** Is date is range? */
inRange: boolean;
/** Is date first or last in given range? */
firstInRange: boolean;
lastInRange: boolean;
/** Is date Saturday or Sunday? */
weekend: boolean;
/** Is date outside of given month? */
outside: boolean;
}

Styles based on date

dayStyle callback allows you to add inline styles to days. Function must return either styles object or null. In this example, we will add red background to each Friday 13th based on date (first argument):

import { useMantineTheme } from '@mantine/core';
import { DatePicker } from '@mantine/dates';
function Demo() {
const theme = useMantineTheme();
return (
<DatePicker
placeholder="Pick date"
label="Event date"
dayStyle={(date) =>
date.getDay() === 5 && date.getDate() === 13
? { backgroundColor: theme.colors.red[9], color: theme.white }
: null
}
/>
);
}

Styles based on modifiers

dayClassName callback allows you to add className to days. Function must return either className string or null. In this example, we will hide all outside dates and change color of weekends based on modifiers (second argument):

import { createStyles } from '@mantine/core';
import { DatePicker } from '@mantine/dates';
const useStyles = createStyles((theme) => ({
outside: {
opacity: 0,
},
weekend: {
color: `${theme.colors.blue[6]} !important`,
},
selected: {
color: `${theme.white} !important`,
},
}));
function Demo() {
const { classes, cx } = useStyles();
return (
<DatePicker
disableOutsideEvents
placeholder="Pick date"
label="Event date"
dayClassName={(date, modifiers) =>
cx({
[classes.outside]: modifiers.outside,
[classes.weekend]: modifiers.weekend,
[classes.selected]: modifiers.selected,
})
}
/>
);
}

Format labels

By default, DatePicker will display dates in human readable format. To change that provide dayjs format string to the following props:

  • inputFormat – input value date format
  • labelFormat – calendar month label format
import { DatePicker } from '@mantine/dates';
function Demo() {
return (
<DatePicker
placeholder="Pick date"
label="Event date"
inputFormat="MM/DD/YYYY"
labelFormat="MM/YYYY"
defaultValue={new Date()}
/>
);
}

Disallow clear

By default, date picker can be cleared, to disable this, set clearable prop to false:

import { DatePicker } from '@mantine/dates';
function Demo() {
return <DatePicker clearable={false} placeholder="Pick date" label="Event date" />;
}

Multiple months

import { DatePicker } from '@mantine/dates';
function Demo() {
return (
<>
<DatePicker amountOfMonths={2} label="2 months" />
<DatePicker amountOfMonths={3} label="3 months" />
</>
);
}

Input props

Radius
xs
sm
md
lg
xl
Size
xs
sm
md
lg
xl
import { DatePicker } from '@mantine/dates';
function Demo() {
return (
<DatePicker
placeholder="Event date"
label="Pick date"
withAsterisk
/>
);
}

Icon and right section

import { DatePicker } from '@mantine/dates';
import { IconCalendar } from '@tabler/icons';
function Demo() {
return (
<DatePicker
placeholder="Pick date"
label="Event date"
icon={<IconCalendar size={16} />}
/>
);
}

Invalid state and error

You must be at least 18 to register
// Error as boolean – red border color
<DatePicker error />
// Error as React node – red border color and message below input
<DatePicker error="You must be at least 18 to register" />

Disabled state

import { DatePicker } from '@mantine/dates';
function Demo() {
return <DatePicker disabled />;
}

Dropdown position

By default, dropdown is placed below the input and when there is not enough space, it flips to be above the input. To change this behavior, set dropdownPosition prop:

import { DatePicker } from '@mantine/dates';
function Demo() {
return <DatePicker placeholder="Pick date" label="Event date" />;
}

Get input ref

import { useRef } from 'react';
import { DatePicker } from '@mantine/dates';
function Demo() {
const ref = useRef<HTMLInputElement>(null);
return <DatePicker ref={ref} />;
}

DatePicker component props

NameTypeDescription
allowFreeInput
boolean
Allow free input
allowLevelChange
boolean
Allow to change level (date – month – year)
amountOfMonths
number
Amount of months
clearButtonLabel
string
aria-label for clear button
clearButtonTabIndex
0 | -1
Set the clear button tab index to disabled or default after input field
clearable
boolean
Allow to clear value
clickOutsideEvents
string[]
Events that should trigger outside clicks
closeCalendarOnChange
boolean
Set to false to force dropdown to stay open after date was selected
dateParser
(value: string) => Date
Parser function for date provided by input typing
dayClassName
(date: Date, modifiers: DayModifiers) => string
Adds className to day button based on date and modifiers
dayStyle
(date: Date, modifiers: DayModifiers) => CSSProperties
Adds style to day button based on date and modifiers
defaultValue
Date
Default value for uncontrolled input
description
ReactNode
Input description, displayed after label
descriptionProps
Record<string, any>
Props spread to description element
disableOutsideEvents
boolean
When true dates that are outside of given month cannot be clicked or focused
disabled
boolean
Disabled input state
dropdownPosition
"flip" | "bottom-start" | "top-start"
Dropdown positioning behavior
dropdownType
"modal" | "popover"
Where to show calendar in modal or popover
error
ReactNode
Displays error message after input
errorProps
Record<string, any>
Props spread to error element
excludeDate
(date: Date) => boolean
Callback function to determine if day should be disabled
firstDayOfWeek
"sunday" | "monday"
Set first day of the week
fixOnBlur
boolean
call onChange with last valid value onBlur
focusable
boolean
Should focusable days have tabIndex={0}?
fullWidth
boolean
Set to true to make calendar take 100% of container width
hideOutsideDates
boolean
Remove outside dates
hideWeekdays
boolean
Set to false to remove weekdays row
icon
ReactNode
Adds icon on the left side of input
iconWidth
Width<string | number>
Width of icon section in px
initialLevel
"date" | "month" | "year"
Initial date selection level
initialMonth
Date
Initial month for uncontrolled calendar
initiallyOpened
boolean
Control initial dropdown opened state
inputContainer
(children: ReactNode) => ReactNode
Input container component, defaults to React.Fragment
inputFormat
string
dayjs input format
inputWrapperOrder
("input" | "label" | "error" | "description")[]
Controls order of the Input.Wrapper elements
label
ReactNode
Input label, displayed before input
labelFormat
string
dayjs Calendar month label format
labelProps
Record<string, any>
Props spread to label element
locale
string
Locale used for labels formatting, defaults to theme.datesLocale
maxDate
Date
Maximum possible date
minDate
Date
Minimum possible date
modalProps
Partial<ModalProps>
Props spread to Modal component
modalZIndex
ZIndex
Modal z-index
name
string
Input name, useful for uncontrolled variant to capture data with native form
nextDecadeLabel
string
Next decade control aria-label
nextMonthLabel
string
Next month control aria-label
nextYearLabel
string
Next year control aria-label
onChange
(value: Date) => void
Called when date changes
onDayMouseEnter
(date: Date, event: MouseEvent<Element, MouseEvent>) => void
Called when onMouseEnter event fired on day button
onDropdownClose
() => void
Called when dropdown closes
onDropdownOpen
() => void
Called when dropdown opens
openDropdownOnClear
boolean
Set to true to open dropdown on clear
paginateBy
number
Paginate by amount of months
placeholder
string
Placeholder, displayed when date is not selected
positionDependencies
any[]
useEffect dependencies to force update dropdown position
preventFocus
boolean
Prevent focusing upon clicking
previousDecadeLabel
string
Previous decade control aria-label
previousMonthLabel
string
Previous month control aria-label
previousYearLabel
string
Previous year control aria-label
radius
number | "xs" | "sm" | "md" | "lg" | "xl"
Input border-radius from theme or number to set border-radius in px
range
[Date, Date]
Selected range
renderDay
(date: Date) => ReactNode
Render day based on the date
required
boolean
Sets required on input element
rightSection
ReactNode
Right section of input, similar to icon but on the right
rightSectionProps
Record<string, any>
Props spread to rightSection div element
rightSectionWidth
Width<string | number>
Width of right section, is used to calculate input padding-right
shadow
MantineShadow
Dropdown shadow from theme or css value for custom box-shadow
size
"xs" | "sm" | "md" | "lg" | "xl"
Input size
transition
MantineTransition
Dropdown appear/disappear transition
transitionDuration
number
Dropdown appear/disappear transition duration
transitionTimingFunction
string
Dropdown appear/disappear transition timing function, defaults to theme.transitionTimingFunction
value
Date
Selected date, required with controlled input
variant
"unstyled" | "default" | "filled"
Defines input appearance, defaults to default in light color scheme and filled in dark
weekdayLabelFormat
string
dayjs label format for weekday heading
weekendDays
number[]
Indices of weekend days
withAsterisk
boolean
Determines whether required asterisk should be rendered, overrides required prop, does not add required attribute to the input
withinPortal
boolean
Whether to render the dropdown in a Portal
wrapperProps
Pick<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "key" | keyof HTMLAttributes<HTMLDivElement>>
Props spread to root element
yearLabelFormat
string
dayjs Calendar year label format
zIndex
ZIndex
Dropdown zIndex

DateRangePicker component props

NameTypeDescription
allowLevelChange
boolean
Allow to change level (date – month – year)
allowSingleDateInRange
boolean
Allow one date to be selected as range
amountOfMonths
number
Allows to show multiple months
clearButtonLabel
string
aria-label for clear button
clearButtonTabIndex
0 | -1
Set the clear button tab index to disabled or default after input field
clearable
boolean
Allow to clear value
clickOutsideEvents
string[]
Events that should trigger outside clicks
closeCalendarOnChange
boolean
Set to false to force dropdown to stay open after date was selected
dayClassName
(date: Date, modifiers: DayModifiers) => string
Adds className to day button based on date and modifiers
dayStyle
(date: Date, modifiers: DayModifiers) => CSSProperties
Adds style to day button based on date and modifiers
defaultValue
DateRangePickerValue
Default value for uncontrolled input
description
ReactNode
Input description, displayed after label
descriptionProps
Record<string, any>
Props spread to description element
disableOutsideEvents
boolean
When true dates that are outside of given month cannot be clicked or focused
disabled
boolean
Disabled input state
dropdownPosition
"flip" | "bottom-start" | "top-start"
Dropdown positioning behavior
dropdownType
"modal" | "popover"
Where to show calendar in modal or popover
error
ReactNode
Displays error message after input
errorProps
Record<string, any>
Props spread to error element
excludeDate
(date: Date) => boolean
Callback function to determine if day should be disabled
firstDayOfWeek
"sunday" | "monday"
Set first day of the week
focusable
boolean
Should focusable days have tabIndex={0}?
fullWidth
boolean
Set to true to make calendar take 100% of container width
hideOutsideDates
boolean
Remove outside dates
hideWeekdays
boolean
Set to false to remove weekdays row
icon
ReactNode
Adds icon on the left side of input
iconWidth
Width<string | number>
Width of icon section in px
initialLevel
"date" | "month" | "year"
Initial date selection level
initialMonth
Date
Initial month for uncontrolled calendar
initiallyOpened
boolean
Control initial dropdown opened state
inputContainer
(children: ReactNode) => ReactNode
Input container component, defaults to React.Fragment
inputFormat
string
dayjs input format
inputWrapperOrder
("input" | "label" | "error" | "description")[]
Controls order of the Input.Wrapper elements
label
ReactNode
Input label, displayed before input
labelFormat
string
dayjs Calendar month label format
labelProps
Record<string, any>
Props spread to label element
labelSeparator
string
Separator between dates
locale
string
Locale used for labels formatting, defaults to theme.datesLocale
maxDate
Date
Maximum possible date
minDate
Date
Minimum possible date
modalProps
Partial<ModalProps>
Props spread to Modal component
modalZIndex
ZIndex
Modal z-index
name
string
Input name, useful fon uncontrolled variant to capture data with native form
nextDecadeLabel
string
Next decade control aria-label
nextMonthLabel
string
Next month control aria-label
nextYearLabel
string
Next year control aria-label
onChange
(value: DateRangePickerValue) => void
Called when date range changes
onDayMouseEnter
(date: Date, event: MouseEvent<Element, MouseEvent>) => void
Called when onMouseEnter event fired on day button
onDropdownClose
() => void
Called when dropdown closes
onDropdownOpen
() => void
Called when dropdown opens
openDropdownOnClear
boolean
Set to true to open dropdown on clear
paginateBy
number
Paginate by amount of months
placeholder
string
Placeholder, displayed when date is not selected
positionDependencies
any[]
useEffect dependencies to force update dropdown position
preventFocus
boolean
Prevent focusing upon clicking
previousDecadeLabel
string
Previous decade control aria-label
previousMonthLabel
string
Previous month control aria-label
previousYearLabel
string
Previous year control aria-label
radius
number | "xs" | "sm" | "md" | "lg" | "xl"
Input border-radius from theme or number to set border-radius in px
range
[Date, Date]
Selected range
renderDay
(date: Date) => ReactNode
Render day based on the date
required
boolean
Sets required on input element
rightSection
ReactNode
Right section of input, similar to icon but on the right
rightSectionProps
Record<string, any>
Props spread to rightSection div element
rightSectionWidth
Width<string | number>
Width of right section, is used to calculate input padding-right
shadow
MantineShadow
Dropdown shadow from theme or css value for custom box-shadow
size
"xs" | "sm" | "md" | "lg" | "xl"
Input size
transition
MantineTransition
Dropdown appear/disappear transition
transitionDuration
number
Dropdown appear/disappear transition duration
transitionTimingFunction
string
Dropdown appear/disappear transition timing function, defaults to theme.transitionTimingFunction
value
DateRangePickerValue
Selected date, required with controlled input
variant
"unstyled" | "default" | "filled"
Defines input appearance, defaults to default in light color scheme and filled in dark
weekdayLabelFormat
string
dayjs label format for weekday heading
weekendDays
number[]
Indices of weekend days
withAsterisk
boolean
Determines whether required asterisk should be rendered, overrides required prop, does not add required attribute to the input
withinPortal
boolean
Whether to render the dropdown in a Portal
wrapperProps
Pick<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "key" | keyof HTMLAttributes<HTMLDivElement>>
Props spread to root element
yearLabelFormat
string
dayjs Calendar year label format
zIndex
ZIndex
Dropdown zIndex

DatePicker component Styles API

NameStatic selectorDescription
wrapper.mantine-DatePicker-wrapperRoot Input element
dropdown.mantine-DatePicker-dropdownDropdown with calendar
invalid.mantine-DatePicker-invalidInvalid input modifier
disabled.mantine-DatePicker-disabledInvalid disabled modifier
icon.mantine-DatePicker-iconInput icon wrapper on the left side of the input, controlled by icon prop
withIcon.mantine-DatePicker-withIconInput element styles when used with icon, controlled by icon prop
input.mantine-DatePicker-inputMain input element
rightSection.mantine-DatePicker-rightSectionInput right section, controlled by rightSection prop
root.mantine-DatePicker-rootRoot element
label.mantine-DatePicker-labelLabel element styles, defined by label prop
error.mantine-DatePicker-errorError element styles, defined by error prop
description.mantine-DatePicker-descriptionDescription element styles, defined by description prop
required.mantine-DatePicker-requiredRequired asterisk element styles, defined by required prop
calendarBase.mantine-DatePicker-calendarBaseRoot element
calendarHeader.mantine-DatePicker-calendarHeaderCalendar header, contains next/previous and level change controls
calendarHeaderControl.mantine-DatePicker-calendarHeaderControlNext/previous controls
calendarHeaderLevel.mantine-DatePicker-calendarHeaderLevelLevel change control (year, month, date)
calendarHeaderLevelIcon.mantine-DatePicker-calendarHeaderLevelIconLevel control icon (caret)
yearPicker.mantine-DatePicker-yearPickerYear picker root element
yearPickerControls.mantine-DatePicker-yearPickerControlsYear picker controls wrapper
yearPickerControl.mantine-DatePicker-yearPickerControlYear picker control button
yearPickerControlActive.mantine-DatePicker-yearPickerControlActiveYear picker control active modifier (currently selected year)
monthPicker.mantine-DatePicker-monthPickerMonth picker root element
monthPickerControls.mantine-DatePicker-monthPickerControlsMonth picker controls wrapper
monthPickerControl.mantine-DatePicker-monthPickerControlMonth picker control button
monthPickerControlActive.mantine-DatePicker-monthPickerControlActiveMonth picker control active modifier (currently selected month)
month.mantine-DatePicker-monthRoot element
weekdayCell.mantine-DatePicker-weekdayCellTable th element, wraps weekday
weekday.mantine-DatePicker-weekdayWeekday title
cell.mantine-DatePicker-cellTable cell, wraps day
day.mantine-DatePicker-dayDay button

DateRangePicker component Styles API

NameStatic selectorDescription
wrapper.mantine-DateRangePicker-wrapperRoot Input element
dropdown.mantine-DateRangePicker-dropdownDropdown with calendar
invalid.mantine-DateRangePicker-invalidInvalid input modifier
disabled.mantine-DateRangePicker-disabledInvalid disabled modifier
icon.mantine-DateRangePicker-iconInput icon wrapper on the left side of the input, controlled by icon prop
withIcon.mantine-DateRangePicker-withIconInput element styles when used with icon, controlled by icon prop
input.mantine-DateRangePicker-inputMain input element
rightSection.mantine-DateRangePicker-rightSectionInput right section, controlled by rightSection prop
root.mantine-DateRangePicker-rootRoot element
label.mantine-DateRangePicker-labelLabel element styles, defined by label prop
error.mantine-DateRangePicker-errorError element styles, defined by error prop
description.mantine-DateRangePicker-descriptionDescription element styles, defined by description prop
required.mantine-DateRangePicker-requiredRequired asterisk element styles, defined by required prop
calendarBase.mantine-DateRangePicker-calendarBaseRoot element
calendarHeader.mantine-DateRangePicker-calendarHeaderCalendar header, contains next/previous and level change controls
calendarHeaderControl.mantine-DateRangePicker-calendarHeaderControlNext/previous controls
calendarHeaderLevel.mantine-DateRangePicker-calendarHeaderLevelLevel change control (year, month, date)
calendarHeaderLevelIcon.mantine-DateRangePicker-calendarHeaderLevelIconLevel control icon (caret)
yearPicker.mantine-DateRangePicker-yearPickerYear picker root element
yearPickerControls.mantine-DateRangePicker-yearPickerControlsYear picker controls wrapper
yearPickerControl.mantine-DateRangePicker-yearPickerControlYear picker control button
yearPickerControlActive.mantine-DateRangePicker-yearPickerControlActiveYear picker control active modifier (currently selected year)
monthPicker.mantine-DateRangePicker-monthPickerMonth picker root element
monthPickerControls.mantine-DateRangePicker-monthPickerControlsMonth picker controls wrapper
monthPickerControl.mantine-DateRangePicker-monthPickerControlMonth picker control button
monthPickerControlActive.mantine-DateRangePicker-monthPickerControlActiveMonth picker control active modifier (currently selected month)
month.mantine-DateRangePicker-monthRoot element
weekdayCell.mantine-DateRangePicker-weekdayCellTable th element, wraps weekday
weekday.mantine-DateRangePicker-weekdayWeekday title
cell.mantine-DateRangePicker-cellTable cell, wraps day
day.mantine-DateRangePicker-dayDay button