@mui/x-date-pickers

What is @mui/x-date-pickers?

The @mui/x-date-pickers package provides date and time selection components that integrate with Material-UI. It allows developers to implement date pickers, time pickers, date-time pickers, and calendar views with ease, offering a consistent design language and user experience aligned with Material Design guidelines.

What are @mui/x-date-pickers's main functionalities?

DatePicker

The DatePicker component allows users to select a date from a calendar dialog.

import * as React from 'react';
import TextField from '@mui/material/TextField';
import { DatePicker } from '@mui/x-date-pickers/DatePicker';

function BasicDatePicker() {
  const [value, setValue] = React.useState(null);

  return (
    <DatePicker
      label="Basic example"
      value={value}
      onChange={(newValue) => {
        setValue(newValue);
      }}
      renderInput={(params) => <TextField {...params} />}
    />
  );
}

TimePicker

The TimePicker component provides a way for users to select a time.

import * as React from 'react';
import TextField from '@mui/material/TextField';
import { TimePicker } from '@mui/x-date-pickers/TimePicker';

function BasicTimePicker() {
  const [value, setValue] = React.useState(null);

  return (
    <TimePicker
      label="Basic example"
      value={value}
      onChange={(newValue) => {
        setValue(newValue);
      }}
      renderInput={(params) => <TextField {...params} />}
    />
  );
}

DateTimePicker

The DateTimePicker combines date and time selection in one control.

import * as React from 'react';
import TextField from '@mui/material/TextField';
import { DateTimePicker } from '@mui/x-date-pickers/DateTimePicker';

function BasicDateTimePicker() {
  const [value, setValue] = React.useState(null);

  return (
    <DateTimePicker
      label="Basic example"
      value={value}
      onChange={(newValue) => {
        setValue(newValue);
      }}
      renderInput={(params) => <TextField {...params} />}
    />
  );
}

Calendar

The Calendar component displays a full calendar view for date selection without a text field.

import * as React from 'react';
import { Calendar } from '@mui/x-date-pickers/Calendar';

function BasicCalendar() {
  const [date, setDate] = React.useState(new Date());

  return (
    <Calendar
      date={date}
      onChange={(newDate) => setDate(newDate)}
    />
  );
}

Other packages similar to @mui/x-date-pickers

react-datepicker

react-datepicker is a simple and reusable datepicker component for React. It is similar to @mui/x-date-pickers but does not require Material-UI and has its own styling and layout.

react-dates

react-dates is an accessible, easily internationalizable, mobile-friendly datepicker library for the web. It is different from @mui/x-date-pickers in that it is built by Airbnb and has a different design aesthetic.

antd

antd, or Ant Design, is a design system that includes a DatePicker component. It is similar to @mui/x-date-pickers but is part of a larger design system with a different design language.

react-day-picker

react-day-picker is a flexible date picker component for React. Unlike @mui/x-date-pickers, it does not rely on Material-UI and offers more customization options for the calendar component.

README

MUI X Date Pickers

This package is the Community plan edition of the Date and Time Picker components. It's part of MUI X, an open-core extension of our Core libraries, with advanced components.

Installation

Install the package in your project directory with:

npm install @mui/x-date-pickers

Then install the date library of your choice (if not already installed). The pickers currently support the following date libraries:

• date-fns
• Day.js
• Luxon
• Moment.js

# date-fns
npm install date-fns

# or dayjs
npm install dayjs

# or luxon
npm install luxon

# or moment
npm install moment

This component has the following peer dependencies that you need to install as well.

"peerDependencies": {
  "@mui/material": "^5.15.14 || ^6.0.0",
  "react": "^17.0.0 || ^18.0.0 || ^19.0.0",
  "react-dom": "^17.0.0 || ^18.0.0 || ^19.0.0"
},

After completing the installation, you have to set the dateAdapter prop of the LocalizationProvider accordingly. The supported adapters are exported from @mui/x-date-pickers.

import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
// date-fns
import { AdapterDateFns } from '@mui/x-date-pickers/AdapterDateFns';
// or for dayjs
import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';
// or for luxon
import { AdapterLuxon } from '@mui/x-date-pickers/AdapterLuxon';
// or for moment
import { AdapterMoment } from '@mui/x-date-pickers/AdapterMoment';

function App({ children }) {
  return <LocalizationProvider dateAdapter={AdapterDateFns}>{children}</LocalizationProvider>;
}

Documentation

Visit https://mui.com/x/react-date-pickers/ to view the full documentation.

Changelog

8.0.0-alpha.10

Jan 30, 2025

We'd like to offer a big thanks to the 10 contributors who made this release possible. Here are some highlights ✨:

• 🎨 Data Grid theming improvements and default background color
• 📚 Documentation improvements
• 🐞 Bugfixes

Special thanks go out to the community contributors who have helped make this release possible: @k-rajat19, @lauri865, @mateuseap. Following are all team members who have contributed to this release: @alexfauquette, @flaviendelangle, @JCQuintas, @KenanYusuf, @MBilalShafi, @romgrk, @arminmeh.

<!--/ HIGHLIGHT_ABOVE_SEPARATOR /-->

Data Grid

Breaking changes

• viewportInnerSize.width now includes pinned columns' widths (fixes recursive loops in updating dimensions <-> columns)

• The Data Grid now has a default background color, and its customization has moved from theme.mixins.MuiDataGrid to theme.palette.DataGrid with the following properties:

  • bg: Sets the background color of the entire grid (new property)
  • headerBg: Sets the background color of the header (previously named containerBackground)
  • pinnedBg: Sets the background color of pinned rows and columns (previously named pinnedBackground)

   const theme = createTheme({
  -  mixins: {
  -    MuiDataGrid: {
  -      containerBackground: '#f8fafc',
  -      pinnedBackground: '#f1f5f9',
  -    },
  -  },
  +  palette: {
  +    DataGrid: {
  +      bg: '#f8fafc',
  +      headerBg: '#e2e8f0',
  +      pinnedBg: '#f1f5f9',
  +    },
  +  },
   });
  

• The detailPanels, pinnedColumns, and pinnedRowsRenderZone classes have been removed.

• Return type of the useGridApiRef() hook and the type of apiRef prop are updated to explicitly include the possibilty of null. In addition to this, useGridApiRef() returns a reference that is initialized with null instead of {}.

  Only the initial value and the type are updated. Logic that initializes the API and its availability remained the same, which means that if you could access API in a particular line of your code before, you are able to access it as well after this change.

  Depending on the context in which the API is being used, you can decide what is the best way to deal with null value. Some options are:

  • Use optional chaining
  • Use non-null assertion operator if you are sure your code is always executed when the apiRef is not null
  • Return early if apiRef is null
  • Throw an error if apiRef is null

@mui/x-data-grid@8.0.0-alpha.10

• [DataGrid] Fix renderContext calculation with scroll bounce / over-scroll (#16297) @lauri865
• [DataGrid] Remove unused classes from gridClasses (#16256) @mateuseap
• [DataGrid] Add default background color to grid (#16066) @KenanYusuf
• [DataGrid] Add missing style overrides (#16272) @KenanYusuf
• [DataGrid] Add possibility of null in the return type of the useGridApiRef() hook (#16353) @arminmeh
• [DataGrid] Fix header filters keyboard navigation when there are no rows (#16126) @k-rajat19
• [DataGrid] Fix order of onClick prop on toolbar buttons (#16356) @KenanYusuf
• [DataGrid] Refactor row state propagation (#15627) @lauri865
• [DataGrid] Refactor: create TextField props (#16174) @romgrk
• [DataGrid] Remove outdated warning (#16360) @MBilalShafi
• [DataGrid] Respect width of iconContainer during autosizing (#16399) @michelengelen

@mui/x-data-grid-pro@8.0.0-alpha.10

Same changes as in @mui/x-data-grid@8.0.0-alpha.10, plus:

• [DataGridPro] Fetch new rows only once when multiple models are changed in one cycle (#16101) @arminmeh
• [DataGridPro] Fix the return type of useGridApiRef for Pro and Premium packages on React < 19 (#16328) @arminmeh

@mui/x-data-grid-premium@8.0.0-alpha.10

Same changes as in @mui/x-data-grid-pro@8.0.0-alpha.10.

Date and Time Pickers

Breaking changes

• The component passed to the field slot no longer receives the ref, disabled, className, sx, label, name, formatDensity, enableAccessibleFieldDOMStructure, selectedSections, onSelectedSectionsChange and inputRef props — Learn more
• The MuiPickersPopper theme entry have been renamed MuiPickerPopper and some of its props have been removed — Learn more

@mui/x-date-pickers@8.0.0-alpha.10

• [pickers] Clean the internals and the public API of <PickersPopper /> (#16319) @flaviendelangle
• [pickers] Improve the JSDoc of the PickerContextValue properties (#16327) @flaviendelangle
• [pickers] Move more field props to the context (#16278) @flaviendelangle
• [pickers] Do not close the picker when doing keyboard editing (#16402) @flaviendelangle

@mui/x-date-pickers-pro@8.0.0-alpha.10

Same changes as in @mui/x-date-pickers@8.0.0-alpha.10.

Charts

Breaking changes

• Replace legend.position.horizontal from "left" | "middle" | "right" to "start" | "center" | "end". This is to align with the CSS values and reflect the RTL ability of the legend component.
• The default colors have changed. To keep using the old palette. It is possible to import blueberryTwilightPalette from @mui/x-charts/colorPalettes and set it on the colors property of charts.
• The id property is now optional on the Pie and Scatter data types.

@mui/x-charts@8.0.0-alpha.10

• [charts] Add new bumpX and bumpY curve options (#16318) @JCQuintas
• [charts] Move tooltipGetter to seriesConfig (#16331) @JCQuintas
• [charts] Move item highligh feature to plugin system (#16211) @alexfauquette
• [charts] Replace legend.position.horizontal from "left" | "middle" | "right" to "start" | "center" | "end" (#16315) @JCQuintas
• [charts] New default colors (#16373) @JCQuintas
• [charts] Make id optional on PieValueType and ScatterValueType (#16389) @JCQuintas

@mui/x-charts-pro@8.0.0-alpha.10

Same changes as in @mui/x-charts@8.0.0-alpha.10.

Tree View

@mui/x-tree-view@8.0.0-alpha.10

Internal changes.

@mui/x-tree-view-pro@8.0.0-alpha.10

Same changes as in @mui/x-tree-view@8.0.0-alpha.10.

Docs

• [docs] Improve release documentation (#16321) @MBilalShafi

Core

• [core] Reduce chart perf benchmark weight (#16374) @alexfauquette
• [test] Fix console warnings while executing tests with React 18 (#16386) @arminmeh
• [test] Fix flaky data source tests in DataGrid (#16395) @lauri865