DatePicker
Usage
DatePicker component:
DateRangePicker component (supports the same props as DatePicker component):
Controlled
Localization
All @mantine/dates components are built with dayjs library.
Default locale is en
, to change this follow dayjs localization guide:
Then set locale
prop in component:
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:
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:
First day of the week
Change first day of week with firstDayOfWeek
prop. It accepts either sunday
or monday
as values:
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:
In most cases, you would want to switch to modal when a certain breakpoint is reached. To implement this use use-media-query hook:
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:
Allow free input
By setting allowFreeInput
prop you stop input from being readonly.
With this option user is allowed to type date manually:
By default, DatePicker will try to parse date using dayjs with given inputFormat
,
to change that provide dateParser
function:
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:
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:
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 componentmodifiers
– modifiers that are applied to the day component
Modifiers
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):
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):
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 formatlabelFormat
– calendar month label format
Disallow clear
By default, date picker can be cleared, to disable this, set clearable
prop to false
:
Multiple months
Input props
Icon and right section
Invalid state and error
Disabled state
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:
Get input ref
DatePicker component props
Name | Type | Description |
---|---|---|
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
Name | Type | Description |
---|---|---|
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
Name | Static selector | Description |
---|---|---|
wrapper | .mantine-DatePicker-wrapper | Root Input element |
dropdown | .mantine-DatePicker-dropdown | Dropdown with calendar |
invalid | .mantine-DatePicker-invalid | Invalid input modifier |
disabled | .mantine-DatePicker-disabled | Invalid disabled modifier |
icon | .mantine-DatePicker-icon | Input icon wrapper on the left side of the input, controlled by icon prop |
withIcon | .mantine-DatePicker-withIcon | Input element styles when used with icon, controlled by icon prop |
input | .mantine-DatePicker-input | Main input element |
rightSection | .mantine-DatePicker-rightSection | Input right section, controlled by rightSection prop |
root | .mantine-DatePicker-root | Root element |
label | .mantine-DatePicker-label | Label element styles, defined by label prop |
error | .mantine-DatePicker-error | Error element styles, defined by error prop |
description | .mantine-DatePicker-description | Description element styles, defined by description prop |
required | .mantine-DatePicker-required | Required asterisk element styles, defined by required prop |
calendarBase | .mantine-DatePicker-calendarBase | Root element |
calendarHeader | .mantine-DatePicker-calendarHeader | Calendar header, contains next/previous and level change controls |
calendarHeaderControl | .mantine-DatePicker-calendarHeaderControl | Next/previous controls |
calendarHeaderLevel | .mantine-DatePicker-calendarHeaderLevel | Level change control (year, month, date) |
calendarHeaderLevelIcon | .mantine-DatePicker-calendarHeaderLevelIcon | Level control icon (caret) |
yearPicker | .mantine-DatePicker-yearPicker | Year picker root element |
yearPickerControls | .mantine-DatePicker-yearPickerControls | Year picker controls wrapper |
yearPickerControl | .mantine-DatePicker-yearPickerControl | Year picker control button |
yearPickerControlActive | .mantine-DatePicker-yearPickerControlActive | Year picker control active modifier (currently selected year) |
monthPicker | .mantine-DatePicker-monthPicker | Month picker root element |
monthPickerControls | .mantine-DatePicker-monthPickerControls | Month picker controls wrapper |
monthPickerControl | .mantine-DatePicker-monthPickerControl | Month picker control button |
monthPickerControlActive | .mantine-DatePicker-monthPickerControlActive | Month picker control active modifier (currently selected month) |
month | .mantine-DatePicker-month | Root element |
weekdayCell | .mantine-DatePicker-weekdayCell | Table th element, wraps weekday |
weekday | .mantine-DatePicker-weekday | Weekday title |
cell | .mantine-DatePicker-cell | Table cell, wraps day |
day | .mantine-DatePicker-day | Day button |
DateRangePicker component Styles API
Name | Static selector | Description |
---|---|---|
wrapper | .mantine-DateRangePicker-wrapper | Root Input element |
dropdown | .mantine-DateRangePicker-dropdown | Dropdown with calendar |
invalid | .mantine-DateRangePicker-invalid | Invalid input modifier |
disabled | .mantine-DateRangePicker-disabled | Invalid disabled modifier |
icon | .mantine-DateRangePicker-icon | Input icon wrapper on the left side of the input, controlled by icon prop |
withIcon | .mantine-DateRangePicker-withIcon | Input element styles when used with icon, controlled by icon prop |
input | .mantine-DateRangePicker-input | Main input element |
rightSection | .mantine-DateRangePicker-rightSection | Input right section, controlled by rightSection prop |
root | .mantine-DateRangePicker-root | Root element |
label | .mantine-DateRangePicker-label | Label element styles, defined by label prop |
error | .mantine-DateRangePicker-error | Error element styles, defined by error prop |
description | .mantine-DateRangePicker-description | Description element styles, defined by description prop |
required | .mantine-DateRangePicker-required | Required asterisk element styles, defined by required prop |
calendarBase | .mantine-DateRangePicker-calendarBase | Root element |
calendarHeader | .mantine-DateRangePicker-calendarHeader | Calendar header, contains next/previous and level change controls |
calendarHeaderControl | .mantine-DateRangePicker-calendarHeaderControl | Next/previous controls |
calendarHeaderLevel | .mantine-DateRangePicker-calendarHeaderLevel | Level change control (year, month, date) |
calendarHeaderLevelIcon | .mantine-DateRangePicker-calendarHeaderLevelIcon | Level control icon (caret) |
yearPicker | .mantine-DateRangePicker-yearPicker | Year picker root element |
yearPickerControls | .mantine-DateRangePicker-yearPickerControls | Year picker controls wrapper |
yearPickerControl | .mantine-DateRangePicker-yearPickerControl | Year picker control button |
yearPickerControlActive | .mantine-DateRangePicker-yearPickerControlActive | Year picker control active modifier (currently selected year) |
monthPicker | .mantine-DateRangePicker-monthPicker | Month picker root element |
monthPickerControls | .mantine-DateRangePicker-monthPickerControls | Month picker controls wrapper |
monthPickerControl | .mantine-DateRangePicker-monthPickerControl | Month picker control button |
monthPickerControlActive | .mantine-DateRangePicker-monthPickerControlActive | Month picker control active modifier (currently selected month) |
month | .mantine-DateRangePicker-month | Root element |
weekdayCell | .mantine-DateRangePicker-weekdayCell | Table th element, wraps weekday |
weekday | .mantine-DateRangePicker-weekday | Weekday title |
cell | .mantine-DateRangePicker-cell | Table cell, wraps day |
day | .mantine-DateRangePicker-day | Day button |