react-datepicker vs react-date-picker vs react-datetime

React 日期选择器核心方案对比

react-date-picker、react-datepicker 和 react-datetime 都是 React 生态中流行的日期选择组件，但它们在 API 设计、维护状态和功能侧重点上有所不同。react-datepicker 是目前社区采用率最高的标准方案，提供丰富的配置项和广泛的插件支持。react-date-picker（由 Wojtek Maj 维护）基于 react-calendar 构建，以简洁的输入框加日历图标样式著称，适合追求现代化 UI 的场景。react-datetime 早期非常流行，支持日期和时间混合选择，但近年来维护频率较低，可能面临兼容性风险。

npm下载趋势

3 年

GitHub Stars 排名

统计详情

npm包名称	下载量	Stars	大小	Issues	发布时间	License
npm包名称	下载量	Stars	大小	Issues	发布时间	License
react-datepicker	5,220,913	8,384	4.5 MB	95	8 个月前	MIT
react-date-picker	352,823	1,354	148 kB	15	1 个月前	MIT
react-datetime	0	2,004	291 kB	182	2 年前	MIT

React 日期选择器深度对比：架构、API 与维护状态

在前端开发中，日期选择器是表单交互的核心组件之一。react-date-picker、react-datepicker 和 react-datetime 都试图解决相同的问题，但它们的实现思路和维护现状差异巨大。本文将从架构设计、API 用法、自定义能力及维护风险四个维度进行深度剖析。

🧩 核心 API 设计：受控组件的差异

这三个包都遵循 React 的受控组件模式，但在属性命名和数据结构上存在关键区别。

react-datepicker 使用 selected 和 onChange。

selected 接收一个 Date 对象。
onChange 回调返回选中的 Date 对象。
这种命名方式与原生 input 的 value 略有不同，需要适应。

// react-datepicker
import DatePicker from 'react-datepicker';

function Example() {
  const [date, setDate] = useState(new Date());
  return (
    <DatePicker
      selected={date}
      onChange={(date) => setDate(date)}
    />
  );
}

react-date-picker 使用 value 和 onChange。

value 可以是 Date 对象或 [Date, Date] 数组（范围选择）。
命名更符合标准 HTML 输入习惯。
默认渲染为输入框加日历图标按钮。

// react-date-picker
import DatePicker from 'react-date-picker';

function Example() {
  const [value, setValue] = useState(new Date());
  return (
    <DatePicker
      value={value}
      onChange={setValue}
    />
  );
}

react-datetime 使用 value 和 onChange。

支持字符串或 Date 对象。
组件名为 Datetime 而非 DatePicker。
默认包含时间选择功能。

// react-datetime
import Datetime from 'react-datetime';

function Example() {
  const [value, setValue] = useState(new Date());
  return (
    <Datetime
      value={value}
      onChange={setValue}
    />
  );
}

🎨 自定义能力：输入框与日历结构

在实际工程中，默认样式往往无法满足设计稿需求，因此自定义能力至关重要。

react-datepicker 提供 customInput 属性。

你可以传入任意 React 组件作为触发器。
适合需要完全控制输入框样式或集成 UI 库（如 AntD、MUI）的场景。

// react-datepicker
<DatePicker
  selected={date}
  onChange={setDate}
  customInput={<input className="custom-input" />}
  renderCustomHeader={({ date, changeMonth, changeYear }) => (
    <div>{date.getFullYear()}</div>
  )}
/>

react-date-picker 通过 clearIcon、calendarIcon 等属性定制。

它更侧重于整体组件的结构控制。
若要完全替换输入框，可能需要较多 CSS 覆盖或使用 inputProps。

// react-date-picker
<DatePicker
  value={value}
  onChange={setValue}
  clearIcon={null}
  calendarIcon={<span>📅</span>}
  inputProps={{ className: 'my-input' }}
/>

react-datetime 支持 inputProps 和 renderInput。

允许自定义输入框属性。
但日历部分的自定义相对较弱，主要依赖 CSS 类名覆盖。

// react-datetime
<Datetime
  value={value}
  onChange={setValue}
  inputProps={{ className: 'my-input', placeholder: 'Select date' }}
/>

⏰ 时间选择支持：原生集成 vs 配置开启

是否需要选择具体时间（小时、分钟）是选型的关键分水岭。

react-datepicker 需要显式开启时间选择。

默认只显示日期。
通过 showTimeSelect 属性启用时间。
可以配置时间间隔 timeIntervals。

// react-datepicker
<DatePicker
  selected={date}
  onChange={setDate}
  showTimeSelect
  timeIntervals={15}
  dateFormat="yyyy-MM-dd HH:mm"
/>

react-date-picker 专注于日期。

核心包仅支持日期选择。
如果需要时间，必须安装单独的 react-datetime-picker 包。
这种分离保持了核心包的轻量。

// react-date-picker (仅日期)
<DatePicker value={date} onChange={setDate} />

// 需引入兄弟包支持时间
// import DateTimePicker from 'react-datetime-picker';

react-datetime 默认包含时间。

组件名即暗示了日期 + 时间。
可以通过 dateFormat 和 timeFormat 控制显示。
适合需要快速启用日期时间混合选择的场景。

// react-datetime
<Datetime
  value={date}
  onChange={setDate}
  dateFormat="YYYY-MM-DD"
  timeFormat="HH:mm"
/>

🛠️ 维护状态与生态风险

对于长期项目，库的维护活跃度直接影响技术债务。

react-datepicker 维护活跃。

社区贡献频繁，Issue 响应较快。
对 React 新版本（如 React 18）兼容性较好。
是大多数企业级项目的首选。

// react-datepicker
// 拥有完善的 TypeScript 类型定义
import DatePicker from 'react-datepicker';
// 类型支持良好，IDE 提示准确

react-date-picker 维护稳定。

由知名开发者 Wojtek Maj 维护。
依赖 react-calendar，生态独立且稳定。
适合追求代码质量和稳定性的团队。

// react-date-picker
// 同样拥有良好的 TypeScript 支持
import DatePicker from 'react-date-picker';
// 结构清晰，依赖链简单

react-datetime 维护频率较低。

相比前两者，更新节奏较慢。
在 React 严格模式或新版本中可能遇到警告。
新项目建议优先考虑前两者，除非有特定遗留依赖。

// react-datetime
// 需注意潜在的类型定义缺失或更新滞后
import Datetime from 'react-datetime';
// 建议在使用前检查最新 Issue 中的兼容性反馈

📊 核心特性对比总结

特性	`react-datepicker`	`react-date-picker`	`react-datetime`
API 风格	`selected` / `onChange`	`value` / `onChange`	`value` / `onChange`
默认 UI	输入框 + 弹出日历	输入框 + 图标 + 弹出日历	输入框 + 图标 + 弹出日历
时间支持	配置开启 (`showTimeSelect`)	需兄弟包 (`react-datetime-picker`)	默认支持
自定义输入	强 (`customInput`)	中 (`inputProps`)	中 (`inputProps`)
维护状态	🟢 活跃	🟢 稳定	🟡 较低
TypeScript	✅ 完善	✅ 完善	⚠️ 一般

💡 架构师建议

react-datepicker 是通用性最强的选择 🧰。如果你需要一个能应对各种复杂需求（范围选择、时间选择、自定义渲染）且社区资源丰富的库，它是首选。它的配置项虽然多，但文档齐全，适合大多数业务场景。

react-date-picker 是现代化 UI 的优选 🎨。如果你喜欢它默认的输入框加图标样式，且希望依赖一个结构清晰、基于 react-calendar 的稳定内核，它非常适合。注意若需时间选择，需引入额外包。

react-datetime 需谨慎评估 ⚠️。虽然它曾经很流行，且默认支持时间选择很方便，但考虑到维护频率和生态活跃度，在新项目中建议优先考察前两者。仅在维护旧系统或有特定兼容性需求时保留使用。

最终建议：对于新启动的 React 项目，优先在 react-datepicker 和 react-date-picker 之间根据 UI 风格偏好进行选择。

如何选择: react-datepicker vs react-date-picker vs react-datetime

react-datepicker:
选择 react-datepicker 如果你需要最广泛的社区支持、丰富的自定义选项（如自定义输入框、头部渲染）以及良好的文档。它是大多数项目的安全默认选择，尤其适合需要复杂日期范围或特定交互逻辑的企业级应用。
react-date-picker:
选择 react-date-picker 如果你需要简洁现代的默认样式，且希望组件基于 react-calendar 内核以获得稳定的日历交互体验。它适合后台管理系统或需要清晰日期输入的场景，但注意它主要专注于日期选择，时间选择需使用其兄弟包。
react-datetime:
选择 react-datetime 仅当你需要维护旧项目或依赖其特定的日期时间混合输入行为。对于新项目，建议谨慎评估其维护状态，因为相比其他两个包，其更新频率较低，可能存在与新版本 React 的兼容性隐患。

与react-datepicker类似的npm包

react-datepicker 是一个用于 React 应用程序的日期选择器组件。它提供了一个简单而灵活的界面，允许用户轻松选择日期和时间。虽然 react-datepicker 提供了强大的日期选择功能，但在 React 生态系统中还有其他一些库可以作为替代方案。以下是一些替代品：

react-calendar 是一个功能丰富的日历组件，允许用户选择日期和时间。与 react-datepicker 不同，react-calendar 提供了一个完整的日历视图，用户可以在其中浏览和选择日期。它适合需要展示完整日历视图的应用程序，提供了更多的灵活性和可定制性。
react-datetime 是一个日期和时间选择器，结合了日期和时间的选择功能。它提供了一个直观的界面，允许用户同时选择日期和时间。对于需要同时处理日期和时间的应用程序，react-datetime 是一个理想的选择，能够满足更复杂的需求。
react-day-picker 是一个灵活的日期选择器，专注于提供简单而强大的日期选择功能。它允许开发者自定义日期选择的行为和外观，非常适合需要高度可定制日期选择器的应用程序。react-day-picker 的灵活性使其成为构建复杂日期选择需求的理想选择。

要查看 react-datepicker 与其他库的比较，请访问：比较 react-calendar vs react-datepicker vs react-datetime vs react-day-picker。

与react-date-picker类似的npm包

react-date-picker 是一个用于 React 应用程序的日期选择器组件。它提供了一个用户友好的界面，允许用户轻松选择日期，并且支持多种日期格式和本地化选项。虽然 react-date-picker 提供了强大的日期选择功能，但在 React 生态系统中还有其他一些库可以作为替代方案。以下是几个替代库：

react-datepicker 是一个流行的日期选择器库，功能强大且易于使用。它提供了丰富的功能，包括日期范围选择、时间选择、日期格式化和本地化支持。react-datepicker 的灵活性和可定制性使其适用于各种应用场景，特别是需要复杂日期选择功能的项目。如果你需要一个功能全面且易于集成的日期选择器，react-datepicker 是一个很好的选择。
react-datetime 是另一个用于选择日期和时间的库。它提供了一个简单的界面，允许用户选择日期和时间，并支持多种格式和本地化选项。react-datetime 的设计旨在提供一个直观的用户体验，并且可以轻松集成到现有的 React 应用中。如果你需要一个轻量级的日期和时间选择器，react-datetime 是一个不错的选择。

要查看 react-date-picker 与 react-datepicker 和 react-datetime 的比较，请访问：比较 react-date-picker vs react-datepicker vs react-datetime。

与react-datetime类似的npm包

react-datetime 是一个用于 React 应用程序的日期和时间选择器组件。它提供了一个灵活且易于使用的界面，允许用户选择日期和时间。该库支持多种日期格式和本地化选项，使其适用于各种应用场景。尽管 react-datetime 提供了强大的功能，但在 React 生态系统中还有其他一些库可以作为替代方案。以下是几个替代库：

react-datepicker 是一个功能丰富的日期选择器组件，专为 React 应用程序设计。它提供了一个直观的用户界面，支持日期范围选择、时间选择和自定义日期格式。react-datepicker 还支持本地化和多种主题，使其适用于各种设计需求。如果你需要一个功能全面且易于定制的日期选择器，react-datepicker 是一个理想的选择。
react-datetime-picker 是一个简单而灵活的日期和时间选择器，旨在提供更简化的用户体验。它允许用户选择日期和时间，支持多种格式和本地化选项。react-datetime-picker 的设计更加简洁，适合那些希望在应用中实现基本日期和时间选择功能的开发者。如果你需要一个轻量级且易于使用的选择器，react-datetime-picker 是一个不错的选择。

查看比较：比较 react-datepicker vs react-datetime vs react-datetime-picker。

react-datepicker

react-date-picker

react-datetime

react-datepicker的README

React Date Picker

A simple and reusable Datepicker component for React (Demo)

Installation

The package can be installed via npm:

npm install react-datepicker --save

Or via yarn:

yarn add react-datepicker

You’ll need to install React and PropTypes separately since those dependencies aren’t included in the package. If you need to use a locale other than the default en-US, you'll also need to import that into your project from date-fns (see Localization section below). Below is a simple example of how to use the Datepicker in a React view. You will also need to require the CSS file from this package (or provide your own). The example below shows how to include the CSS from this package if your build system supports requiring CSS files (Webpack is one that does).

import React, { useState } from "react";
import DatePicker from "react-datepicker";

import "react-datepicker/dist/react-datepicker.css";

// CSS Modules, react-datepicker-cssmodules.css
// import 'react-datepicker/dist/react-datepicker-cssmodules.css';

const Example = () => {
  const [startDate, setStartDate] = useState(new Date());
  return <DatePicker selected={startDate} onChange={(date) => setStartDate(date)} />;
};

Configuration

The most basic use of the DatePicker can be described with:

<DatePicker selected={startdate} onChange={(date) => setStartDate(date)} />

You can use onSelect event handler which fires each time some calendar date has been selected

<DatePicker
  selected={date}
  onSelect={handleDateSelect} //when day is clicked
  onChange={handleDateChange} //only when value has changed
/>

onClickOutside handler may be useful to close datepicker in inline mode

See here for a full list of props that may be passed to the component. Examples are given on the main website.

Working with Examples

When using examples from the documentation site, note that they may reference utilities from external libraries. Common imports you might need:

Date manipulation (from date-fns):

import { getYear, getMonth, addDays, subDays, setHours, setMinutes } from "date-fns";

Utility functions:

For range() function used in custom headers: import range from "lodash/range";
Or implement your own: const range = (start, end, step) => Array.from({ length: (end - start) / step }, (_, i) => start + i * step);

TypeScript types:

import type { ReactDatePickerCustomHeaderProps } from "react-datepicker";

All examples on the documentation site include commented import statements at the top showing exactly what you need to import for your own project.

For a comprehensive guide on imports, see the Common Imports Guide.

Time picker

You can also include a time picker by adding the showTimeSelect prop

<DatePicker selected={date} onChange={handleDateChange} showTimeSelect dateFormat="Pp" />

Times will be displayed at 30-minute intervals by default (default configurable via timeIntervals prop)

More examples of how to use the time picker are given on the main website

Localization

The date picker relies on date-fns internationalization to localize its display components. By default, the date picker will use the locale globally set, which is English. Provided are 3 helper methods to set the locale:

registerLocale (string, object): loads an imported locale object from date-fns
setDefaultLocale (string): sets a registered locale as the default for all datepicker instances
getDefaultLocale: returns a string showing the currently set default locale

import { registerLocale, setDefaultLocale } from  "react-datepicker";
import { es } from 'date-fns/locale/es';
registerLocale('es', es)

<DatePicker
  locale="es"
/>

Locales can be changed in the following way:

Globally - setDefaultLocale('es');

Timezone handling

React-datepicker uses native JavaScript Date objects which are timezone-aware. By default, dates are displayed in the user's local timezone. The library does not include built-in timezone conversion utilities.

Common issue: "Date is one day off" (#1018) - If you're seeing dates shift by one day when converting to ISO strings or sending to a server, this is due to timezone conversion, not a bug. See the Timezone Handling Guide for solutions.

For detailed information about working with timezones, UTC dates, and common timezone-related scenarios, see the Timezone Handling Guide.

For applications requiring timezone conversion, we recommend using date-fns-tz alongside react-datepicker.

Compatibility

React

We're always trying to stay compatible with the latest version of React. We can't support all older versions of React.

Latest compatible versions:

React 16 or newer: React-datepicker v2.9.4 and newer
React 15.5: React-datepicker v2.9.3
React 15.4.1: needs React-datepicker v0.40.0, newer won't work (due to react-onclickoutside dependencies)
React 0.14 or newer: All above React-datepicker v0.13.0
React 0.13: React-datepicker v0.13.0
pre React 0.13: React-datepicker v0.6.2

Moment.js

Up until version 1.8.0, this package was using Moment.js. Starting v2.0.0, we switched to using date-fns, which uses native Date objects, to reduce the size of the package. If you're switching from 1.8.0 to 2.0.0 or higher, please see the updated example above of check out the examples site for up to date examples.

Browser Support

The date picker is compatible with the latest versions of Chrome, Firefox, and IE10+.

Unfortunately, it is difficult to support legacy browsers while maintaining our ability to develop new features in the future. For IE9 support, it is known that the classlist polyfill is needed, but this may change or break at any point in the future.

Local Development

The main branch contains the latest version of the Datepicker component.

To begin local development:

Run yarn install from project root
Run yarn build from project root
Run yarn start from project root

The last step starts documentation app as a simple webserver on http://localhost:5173.

You can run yarn test to execute the test suite and linters. To help you develop the component we’ve set up some tests that cover the basic functionality (can be found in /tests). Even though we’re big fans of testing, this only covers a small piece of the component. We highly recommend you add tests when you’re adding new functionality.

Please refer to CONTRIBUTING.md file for more details about getting set up.

The examples

The examples are hosted within the docs folder and are ran in the simple app that loads the Datepicker. To extend the examples with a new example, you can simply duplicate one of the existing examples and change the unique properties of your example.

Accessibility

Keyboard support

Left: Move to the previous day.
Right: Move to the next day.
Up: Move to the previous week.
Down: Move to the next week.
PgUp: Move to the previous month.
Shift+PgUp: Move to the same day and month of the previous year. If that day does not exist, moves focus to the last day of the month.
PgDn: Move to the next month.
Shift+PgDn: Move to the same day and month of the next year. If that day does not exist, moves focus to the last day of the month.
Home: Move to the first day (e.g Sunday) of the current week.
End: Move to the last day (e.g. Saturday) of the current week.
Enter/Esc/Tab: close the calendar. (Enter & Esc calls preventDefault)

For month picker

Left: Move to the previous month.
Right: Move to the next month.
Enter: Select date and close the calendar