react-datetime

A date and time picker in the same React.js component. It can be used as a datepicker, timepicker or both at the same time. It is highly customizable and it even allows to edit date's milliseconds.

Back to the roots! Thanks to the people of YouCanBook.me (best scheduling tool) for sponsoring react-datetime for so long. Now the project returns to the community and we are looking for contributors to continue improving react-datetime. Would you like to give a hand?

Version 3 is out! These are the docs for version 3 of the library. If you are still using the deprecated v2, here it is its documentation, but we strongly recommend to migrate to version 3 in order to keep receiving updates. Please check migrating react-datetime to version 3 to safely update your app.

Installation

Install using npm:

npm install --save react-datetime

Install using yarn:

yarn add react-datetime

Usage

React.js and Moment.js are peer dependencies for react-datetime (as well as Moment.js timezones if you want to use the displayTimeZone prop). These dependencies are not installed along with react-datetime automatically, but your project needs to have them installed in order to make the datepicker work. You can then use the datepicker like in the example below.

// Import the library
import Datetime from 'react-datetime';

// return it from your components
return <Datetime />;

See this example working.

Do you want more examples? Have a look at our resources gallery.

Don't forget to add the CSS stylesheet to make it work out of the box.. You only need to do this once in your app:

import "react-datetime/css/react-datetime.css";

API

Below we have all the props that we can use with the <DateTime> component. There are also some methods that can be used imperatively.

Imperative API

Besides controlling the selected date, there is a navigation through months, years, decades that react-datetime handles for us. We can interfere in it, stopping view transtions by using the prop onBeforeNavigate, but we can also navigate to a specific view and date by using some imperative methods.

To do so, we need to create our component with a ref prop amd use the reference.

// This would be the code to render the picker
<DateTime ref="datetime" />

// ... once rendered we can use the imperative API
// let's show the years view
this.refs.datetime.navigate('years')

Available methods are:

• navigate( viewMode ): Set the view currently shown by the calendar. View modes shipped with react-datetime are years, months, days and time, but you can alse navigate to custom modes that can be defined by using the renderView prop.
• setViewDate( date ): Set the date that is currently shown in the calendar. This is independent from the selected date and it's the one used to navigate through months or days in the calendar. It accepts a string in the format of the current locale, a Date or a Moment object as parameter.

i18n

Different language and date formats are supported by react-datetime. React uses Moment.js to format the dates, and the easiest way of changing the language of the calendar is changing the Moment.js locale.

Don't forget to import your locale file from the moment's moment/locale folder.

import moment from 'moment';
import 'moment/locale/fr';
// Now react-datetime will be in french

If there are multiple locales loaded, you can use the prop locale to define what language shall be used by the instance.

<Datetime locale="fr-ca" />
<Datetime locale="de" />

Here you can see the i18n example working.

Customize the Input Appearance

It is possible to customize the way that the input is displayed. The simplest is to supply inputProps which will get directly assigned to the <input /> element within the component. We can tweak the inputs this way:

let inputProps = {
    placeholder: 'N/A',
    disabled: true,
    onMouseLeave: () => alert('You went to the input but it was disabled')
};

<Datetime inputProps={ inputProps } />

See the customized input working

Alternatively, if you need to render different content than an <input /> element, you may supply a renderInput function which is called instead.

class MyDTPicker extends React.Component {
    render(){
        return <Datetime renderInput={ this.renderInput } />;
    }
    renderInput( props, openCalendar, closeCalendar ){
        function clear(){
            props.onChange({target: {value: ''}});
        }
        return (
            <div>
                <input {...props} />
                <button onClick={openCalendar}>open calendar</button>
                <button onClick={closeCalendar}>close calendar</button>
                <button onClick={clear}>clear</button>
            </div>
        );
    }
}

See this example working

Or maybe you just want to shown the calendar and don't need an input at all. In that case input={ false } will make the trick:

    <Datetime input={ false } />;

See react-datetime calendar working without an input

Customize the Datepicker Appearance

It is possible to customize the way that the datepicker display the days, months and years in the calendar. To adapt the calendar for every need it is possible to use the props renderDay(props, currentDate, selectedDate), renderMonth(props, month, year, selectedDate) and renderYear(props, year, selectedDate) to customize the output of each rendering method.

class MyDTPicker extends React.Component {
  render() {
    return (
      <Datetime
        renderDay={this.renderDay}
        renderMonth={this.renderMonth}
        renderYear={this.renderYear}
      />
    );
  }
  renderDay(props, currentDate, selectedDate) {
    // Adds 0 to the days in the days view
    return <td {...props}>{"0" + currentDate.date()}</td>;
  }
  renderMonth(props, month, year, selectedDate) {
    // Display the month index in the months view
    return <td {...props}>{month}</td>;
  }
  renderYear(props, year, selectedDate) {
    // Just display the last 2 digits of the year in the years view
    return <td {...props}>{year % 100}</td>;
  }
}

See the customized calendar here.

It's also possible to override some view in the calendar completelly. Let's say that we want to add a today button in our calendars, when we click it we go to the today view:

class MyDTPicker extends React.Component {
  render() {
    return (
      <Datetime
        ref="datetime"
        renderView={(mode, renderDefault) =>
          this.renderView(mode, renderDefault)
        }
      />
    );
  }

  renderView(mode, renderDefault) {
    // Only for years, months and days view
    if (mode === "time") return renderDefault();

    return (
      <div className="wrapper">
        {renderDefault()}
        <div className="controls">
          <button onClick={() => this.goToToday()}>Today</button>
        </div>
      </div>
    );
  }

  goToToday() {
    // Reset
    this.refs.datetime.setViewDate(new Date());
    this.refs.datetime.navigate("days");
  }
}

See it working

Method Parameters

• props is the object that the datepicker has calculated for this object. It is convenient to use this object as the props for your custom component, since it knows how to handle the click event and its className attribute is used by the default styles.
• selectedDate and currentDate are moment objects and can be used to change the output depending on the selected date, or the date for the current day.
• month and year are the numeric representation of the current month and year to be displayed. Notice that the possible month values range from 0 to 11.

Make it work as a year picker or a time picker

You can filter out what you want the user to be able to pick by using dateFormat and timeFormat, e.g. to create a timepicker, yearpicker etc.

In this example the component is being used as a timepicker and can only be used for selecting a time.

<Datetime dateFormat={false} />

Working example of a timepicker here.

In this example you can only select a year and month.

<Datetime dateFormat="YYYY-MM" timeFormat={false} />

Working example of only selecting year and month here.

Blocking some dates to be selected

It is possible to disable dates in the calendar if the user are not allowed to select them, e.g. dates in the past. This is done using the prop isValidDate, which admits a function in the form function(currentDate, selectedDate) where both arguments are moment objects. The function shall return true for selectable dates, and false for disabled ones.

In the example below are all dates before today disabled.

import moment from 'moment';
var yesterday = moment().subtract( 1, 'day' );
var valid = function( current ){
    return current.isAfter( yesterday );
};
<Datetime isValidDate={ valid } />

Working example of disabled days here.

It's also possible to disable the weekends, as shown in the example below.

var valid = function( current ){
    return current.day() !== 0 && current.day() !== 6;
};
<Datetime isValidDate={ valid } />

Working example of disabled weekends here.

Usage with TypeScript

This project includes typings for TypeScript versions 1.8 and 2.0. Additional typings are not required.

Typings for 1.8 are found in react-datetime.d.ts and typings for 2.0 are found in typings/index.d.ts.

import * as Datetime from 'react-datetime';

class MyDTPicker extends React.Component<MyDTPickerProps, MyDTPickerState> {
    render() JSX.Element {
        return <Datetime />;
    }
}

Contributions

react-datetime is made by the community for the community. People like you, interested in contribute, are the key of the project! 🙌🙌🙌

Have a look at our contribute page to know how to get started.

Changelog

MIT Licensed