React components, that implements material design pickers for material-ui v4

npm install @material-ui/pickers


Material-ui-pickers logo

Material-UI pickers

Accessible, customizable, delightful date & time pickers for @material-ui/core

npm package npm download codecov Bundle Size CircleCI Cypress.io tests This project is using Percy.io for visual regression testing. code style: prettier


Note that this package requires @material-ui/core v4. It will not work with the old v3. Please read the migration guide if you are updating from v2

// via npm
npm i @material-ui/pickers

// via yarn
yarn add @material-ui/pickers

Now choose the library that pickers will use to work with date. We are providing interfaces for moment, luxon, dayjs and date-fns v2. If you are not using moment in the project (or don’t have it in the bundle already) we suggest using date-fns or luxon, because they are much lighter and will be correctly tree-shaked from the bundle. Note, that we are fully relying on date-io for supporting different libraries.

npm i [email protected] @date-io/date-fns
// or
npm i moment @date-io/moment
// or
npm i luxon @date-io/luxon
// or
npm i dayjs @date-io/dayjs

Then teach pickers which library to use with MuiPickerUtilsProvider. This component takes a utils property, and makes it available down the React tree thanks to React context. It should preferably be used at the root of your component tree.

import MomentUtils from '@date-io/moment';
import DateFnsUtils from '@date-io/date-fns';
import LuxonUtils from '@date-io/luxon';
import { MuiPickersUtilsProvider } from '@material-ui/pickers';

function App() {
  return (
    <MuiPickersUtilsProvider utils={DateFnsUtils}>
      <Root />

render(<App />, document.querySelector('#app'));


Check out the documentation website

Recently updated?

Changelog available here


For information about how to contribute, see the CONTRIBUTING file.


The project is licensed under the terms of MIT license

Release Notes

By Dmitriy Kovalenko β€’ Published on August 4, 2020

It is the last release of @material-ui/pickers from the https://github.com/mui-org/material-ui-pickers. Starting from this point, we will work on migrating pickers to https://github.com/mui-org/material-ui repo πŸ˜‹

Breaking changes

  • [typescript] We made all of our components to be generic. That means that from now type inference works for all the props like renderDay and for side components.

Bugfixes and enhancements

  • [typescript] Fix typing for date values as unknown (by making all components generic)
  • [MonthView] Fix crashing when null was passed to the month selection view
  • [chore] Fix various peer dependency warnings (#2054) @eps1lon
  • [docs] Fix docs colors for v4.0.0-alpha.11 (#2065)
By Olivier Tassinari β€’ Published on August 1, 2020
Aug 1, 2020

Big thanks to the 9 contributors who made this release possible.

@material-ui/[email protected]

Breaking changes

  • Require Material-UI v5 alpha (#2053) @eps1lon


  • [DateTimePicker] Allow same date selection (#2016) @dmtrKovalenko


  • [docs] Fix inputRef date picker customization demo (#2028) @Chee7ah
  • [docs] Migrate demos to TypeScript (#2030) @dmtrKovalenko
  • [docs] Remove mention of removed autoOk prop (#2020) @dandv
  • [docs] Update guides links to point to next (#2048) @aamirafridi


  • [test] Add test for textbox aria-invalid (#1955) @PaulSavignano
  • [test] check prettier on CI (#2025) @dmtrKovalenko
  • [test] Add yarn deduplicate step (#2036) @oliviertassinari
  • [Security] Bump codecov from 3.6.5 to 3.7.1 (#2014) @dependabot-preview
  • [Security] Bump elliptic from 6.5.1 to 6.5.3 (#2049) @dependabot-preview
  • [core] Batch small changes (#2034) @oliviertassinari
  • [core] Continue eslint sync with main repo (#2004) @oliviertassinari
  • [core] Upgrade prettier (#2005) @oliviertassinari
By Dmitriy Kovalenko β€’ Published on July 17, 2020

Breaking changes

Consolidate classes naming to match the convention with @material-ui/core

We are changed all of our internal components to use:

  1. Unique component name and display name in component namespace
  2. All internal components of pickers are named with prefix MuiPickers from now
  3. Every component have style option called root which points to the root
  4. Using pseudo-classes (e.g. .Mui-disabled) to improve the overriding experience
MuiPickersDay: {
     // provide any disabled styles

Avoid localized time formats

In order to get rid of unexpected falling back to the unmasked input and warnings – we must avoid usage of localized time format (e.g. "p") and use predefined formats. We do have support for it via date-io and simply use hh:mm for 24h clock and hh:mm a for 12h.

Fixes / enhancements πŸ›

  • [DatePicker] Don't run onChange if same date selected (#1967) @tdranv
  • [Calendar] Fix not rerendering days when reduceAnimations provided (#1994)
  • [docs] Update examples formatting to match main v2 (#1977)
By Dmitriy Kovalenko β€’ Published on July 10, 2020

Breaking changes ⚠️

Migrate from <Popover /> to <Popper /> for desktop components.

We migrated our components to the core Popper + TrapFocus. Related to this all the components will not block scroll from now and also PopoverProps was removed in favor of PopperProps.

[typescript] Generic date type (#1966)

We got rid of dynamically attaching @date-io/type module declaration for the adapter's date engine type. From now on pickers will automatically infer the type of value or onChange props. But it is also possible to force using pickers with generic JSX components notation.

  // You can pass any value right here that can be parsed
  onChange={newValue => newValue?.getDate()} 

Change date selection flow (#1923)

  • From now on we will dispatch onChange when each view is filled (when the next view needs to open). This allows the developer to understand which value is already filled and also improves UX with. Cancel button – if cancel clicked already filled part will be saved. (closes #1909)
  • autoOk prop was removed and now picker will automatically close after selection for Desktop mode. It is possible to control this behavior with the new disableCloseOnSelectProp (closes #1651)

Fixes / Enhancments πŸ›

  • Add missing props for DateRangePickerToolbar (#1914) @fhessenberger
  • [typescript] Fix theme overrides type failing @bopfer
  • [YearSelection] Do not call shouldDisableDate on year selection view for each year. (#1954)
  • [DateRangePicker] Fix not working renderDay prop (#1953)
  • [DateTimePicker] Always show arrow switcher in clock (#1949)
  • [material design] Replace theme.palette.text.hint with theme.palette.text.secondary (#1952)
  • [docs] Fix crash on DatePicker 'Customization' example (#1904) @bertrandp
  • [docs] Improve Responsiveness sections (#1884) @xiaoyu-tamu
  • [docs] Fix crash on DatePicker 'Customization' example (#1904) @bertrandp
By Dmitriy Kovalenko β€’ Published on June 4, 2020


This release is a part of our ongoing breaking changes list implementation. We are working on making v4 stable before beta. And mostly all of out breaking changes are already done πŸŽ‰. Hopefully the next v4-alpha.9 will be the last alpha release

Documentation: https://v4-0-0-alpha-8.material-ui-pickers.dev/

πŸ”§ Breaking changes

  • Support "empty" value in pickers' UX (#1770) From now when the value={null} passed picker will not render any selected date (instead of highlighting today)
  • Rename text-props from ok{Label} to ok{Text} (okLabel => okText)
  • Global theme default props support (#1796)
  • Remove onMonthChange promise-based API in favor of loading prop (#1829)
  • [DateTimePicker] New desktop UI (#1771) image

πŸ₯³ Features

  • Improve renderInput spreading experience for custom inputs (#1760)
  • [DX] Add missing prop types (#1761)
  • Export the default Toolbar components (closes #1694) (#1707) @Philipp91

πŸ› Bugfixes & improvements

  • Fix TrapFocus import with @material-ui/core v4.10.1 (#1857)
  • [Calendar] Disable year in the list if it cannot be selected (#1848)
  • [DateTimePicker] Fix not working minDateTime and maxDateTime props (#1834)
  • [docs] improve English, move moment.js last due to bundle size (#1816)
  • Fix ternary condition for default mask values (#1797) @Philipp91
  • [docs] Add missing space to the date-io override example
  • [docs] Update parsing.mdx to use day.js document website (#1831) @ducthienbui97
  • [docs] Improve English and fix 404 link (#1815) @dandv
  • [docs] Removed outdated docs (#1838) @stunaz
  • [typescript] Reexport additional public props (#1846)
  • [Day] Accept font-family from typography (#1847)
By Dmitriy Kovalenko β€’ Published on May 7, 2020

Hotfix for v4.0.0-alpha.6


  • [DateRangePicker] Fix an issue when typed invalid value in input, then closed and reopened (#1755) @dmtrKovalenko
  • [DateRangePicker] Improve validation experience (#1755) @dmtrKovalenko
  • [DateRangePicker] Disable auto-selecting closest enable date (#1755) @dmtrKovalenko


  • [docs] Fix minDate error message in Formik example (#1746) @jozsi
By Dmitriy Kovalenko β€’ Published on May 6, 2020

πŸ§™ renderInput API

Our new API to render the text field input, that solves a lot of problems! Like spreading props down to text field, override them, override classes for the picker – and saves a lot of bundlesize for people who use custom text fields.

β›” Breaking changes

  • renderInput prop is required for any picker. For the compatibility (no user-facing changes) it will be
+  renderInput={props => <TextField {...props} />}

For DateRangePicker it includes 2 arguments (startProps and endProps respectively)

  renderInput={(startProps, endProps) => (
      <TextField {...startProps} />
      <DateRangeDelimiter> to </DateRangeDelimiter>
      <TextField {...endProps} />
  • Change the signature of onError callback to return a reason why the error must be displayed. We are not displaying English error messages by default anymore. If the input is invalid picker will only show red-colored TextField. So from now form validation with sharing internal pickers logic will look like this (reason is well-typed string union). More info in this guide

Removed props

  1. minDateMessage
  2. maxDateMessage
  3. invalidDateMessage
  4. strictCompareDates
  5. emptyText – it has been adding more confusing than what it's worth
  6. maskChar – because it is not visible for your users anymore and needs only to generate and parse mask pattern.

Prop renames

  • keyboardIcon => openPickerIcon
  • KeyboardButtonProps => OpenPickerButtonProps

✨ Features

  • Significantly improved form integration experience with the new onError prop. Checkout new form integration guideline
  • Export special DateRangeDelimiter component that can be used for renderInput of DateRangePicker
  • Better recognition of touch devices, using media (pointer: fine) (#1653)
  • Introduce new shouldDisableYear prop in order to dynamically disable years (#1743)
  • Improve input mask UX and a11y (#1661)

We have changed the logic of the input mask to be more accessible and less noisy:

  1. It is not rendering the whole mask from now (12/1_/____) for partial input it will show only typed part and the next delimiter (12/12/). And still does not allow to enter invalid symbols and type outside of date format.
  2. Generate user-readable placeholder and helper text thanks to https://github.com/dmtrKovalenko/date-io/pull/340. This should significantly increase UX for keyboard input

Screen Recording 2020-04-15 at 17 38 50

πŸ‘©β€βš•οΈ Fixes & Enhancements

  • Fix importing error for reexported adapters (#1634)
  • Make disabled years properly highlighted (#1743)
  • Do not open year by clicking space right of the arrow icon button (#1702)
  • Fix unexpected month switching on tabbing from the 1st day of the month (#1702)
  • Make impossible to focus disabled day/year via keyboard (#1702)
  • Reexport DateRangePickerProps [#1666] (#1668)
  • Align DateRangePicker inputs by baseline (#1689) @Philipp91
  • Rerender picker input when inputFormat changed @vdyachenko
  • [core] Align internal icons with mono-repository (#1692) @oliviertassinari
  • [docs] Fix DateFnsAdapter import docs typo (#1699) @Domino987
  • [docs] Fix Shortcat -> Shortcut typo(#1663) @Philipp91
By Dmitriy Kovalenko β€’ Published on April 9, 2020

This release finally introducing <DateRangePicker /> component. Check out the live demo at https://next.material-ui-pickers.dev/demo/daterangepicker



  • New <DateRangePicker /> component

Fixes & Enhancements

  • Fix warning "Invalid prop children supplied to LocalizationProvider"
  • Fix [email protected] support with createSvgIcon (#1629)
  • Fix crash when component used without <ThemeProvider />
  • Improve rendering performance for days (#1306)
By Dmitriy Kovalenko β€’ Published on March 19, 2020

API improvements release

Breaking changes


Rename and changes in API for MuiPickersUtilsProvider. It is renamed to LocalizationProvider. In future this provider may be moved to the @material-ui/core

- <MuiPickersUtilsProvider utils={DateFnsUtils} />
+ <LocalizationProvider dateAdapter={DateFnsUtils}  />

Also, libInstance from now renamed to dateLibInstance which is a more meaningful name in case of reusable LocalizationProvider

- <MuiPickersUtilsProvider utils={MomentUtils} libInstance={moment}  />
+ <LocalizationProvider dateAdapter={MomentUtils} dateLibInstance={moment} />

Forward refs

From now all refs passed directly to any picker component will be automatically forwarded down to input

Props API changes

We did a bunch of props API changes. Hopefully, we will provide a codemod scripts closer to the stable release.

New props

  • toolbarFormat - easily customize date string displaying in toolbar (#1345)
  • disableHighlightToday - disable highlighting of today date with a circle
  • showDaysOutsideCurrentMonth - show days outside of current month in calendar
  • disableMargin - (only Day prop) disable margin between days, useful for range displaying when days are linked together with background color

Remove props

  • labelFunc - completely unusable function with current keyboard input design
  • invalidLabel - pretty same, unusable with keyboard input, use error and helperText instead


  • format => inputFormat
  • emptyLabel => emptyInputText
  • initialFocusedDate => defaultHighlight
  • title => toolbarTitle (+ make it accept value from label as default)

Change signatures

  • renderDay
    (date: DateIOType, selectedDate: DateIOType, dayInCurrentMonth: boolean, defaultDay: React.ReactNode) => React.ReactNode 
    (date: DateIOType, selectedDate: DateIOType,  DayComponentProps:  DayProps) => React.ReactNode 

Better customization of the day displaying, by allowing to spread down and override any props you need, before it was possible only by React.cloneElement, but it was not so powerful like spreading props down. This also better from performance perspective when overriding days, because we are not rendering day by ourselves if needs to render something different.

  renderDay={(day, selectedDate, DayComponentProps) => {
     return (
        <Badge overlap="circle" badgeContent={isSelected ? '🌚' : undefined}>
          <Day {...DayComponentProps} isToday disableMargin aria-label="Something"  />


πŸ• Time validation

From now it is possible to validate TimePicker or DateTimePicker with a help of corresponding props:

  • maxTime: TDate (date part by default, will be ignored)
  • minTime: TDate (date part by default, will be ignored)
  • maxDateTime: TDate - Maximal selectable moment of time with binding to date
  • minDateTime: TDate - Minimal selectable moment of time with binding to date
  • shouldDisableTime: (timeValue: number, clockType: "hours" | "minutes" | "seconds") => boolean - Dynamically disable a clock value


dateAdapter prop

There is a new prop dateAdapter in each component which allows passing configured date adapter object without context

const memoizedDateAdapter = React.useMemo(() => {
   return new DateFnsAdapter({ locale });
}, [locale]);

  onChange={date => handleDateChange(date)}

Better global format customization

Also, new LocalizationProvider now accepts special dateFormats prop that allows globally override formats used for displaying dates

const formats = {
  normalDate: 'd MMM yyy',
  keyboardDate: 'd MMM yyy',


πŸ› Bugfixes and improvements

  • Make set today button works properly with autoOk (#1555)
  • Remove @material-ui/styles dependency
  • Better material-ui core components import strategy (#1590)

Wow you read all these changelog release notes! It's impressive :) The next release will be smaller, I promise 😈

By Dmitriy Kovalenko β€’ Published on February 17, 2020

Improvements for v4.0.0-alpha.2

This release is a part of v4 (#1293) development. v4 is in active development right now and we are planning to create more breaking changes. So please, update wisely 😸

Checkout latest documentation πŸ“ at https://next.material-ui-pickers.dev/


  • [a11y] Improved keyboard focus management and focus displaying. We are not using the ripple effect for focus anymore - just changing the background color.
  • πŸ› Fixed hosting adapters, so now they are properly reexported by pickers: We are now hosting date-io adapter by ourselves. So you need to import it from @material-ui/pickers/adapter/date-fns instead of right from @date-io/date-fns
-import DateFnsUtils from '@date-io/date-fns'
+import DateFnsUtils from '@material-ui/pickers/adapter/date-fns'

<MuiPickersUtilsProvider utils={DateFnsUtils}> 
  • πŸ› Fixed conflicts in imports between root ("@material-ui/pickers") vs path imports ("@material-ui/pickers/DatePicker"), so now mixing imports will not fail the application


Typescript Types
None found


GitHub Stargazers
Community Interest
Number of Forks


Last Commit
Mar 25, 2021
Open Issues
Closed Issues
Open Pull Requests
Closed Pull Requests


Versions Released
Latest Version Released
Mar 12, 2021
Current Tags


Commits: 1,118
Commits: 142
Commits: 55
Commits: 29
Commits: 28
Commits: 26
Commits: 20
Commits: 19
Commits: 15
Commits: 14
Commits: 9
Commits: 9
Commits: 8
Commits: 6
Commits: 5