| commit | author | age | ||
| 1de42c | 1 | # react-datetime |
| 4afe21 | 2 | |
| 267a3a | 3 | [](https://travis-ci.org/YouCanBookMe/react-datetime) |
| 7d1067 | 4 | [](http://badge.fury.io/js/react-datetime) |
| 889b6c | 5 | |
| 1de42c | 6 | 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. |
| eba92b | 7 | |
| 18dc17 | 8 | This project started as a fork of https://github.com/quri/react-bootstrap-datetimepicker but the code and the API has changed a lot. |
| 795f65 | 9 | |
| 1530e0 | 10 | ## Installation |
| f13618 | 11 | |
| 28160e | 12 | Install using npm: |
| 8055e6 | 13 | ```sh |
| 70f4fb | 14 | npm install --save react-datetime |
| f13618 | 15 | ``` |
| LC | 16 | |
| 1530e0 | 17 | Install using yarn: |
| SE | 18 | ```sh |
| 19 | yarn add react-datetime | |
| 20 | ``` | |
| 21 | ||
| 22 | ## Usage | |
| 23 | ||
| 1de42c | 24 | [React.js](http://facebook.github.io/react/) and [Moment.js](http://momentjs.com/) are peer dependencies for react-datetime. 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. |
| f60b22 | 25 | |
| 1de42c | 26 | |
| SE | 27 | ```js |
| 9fb8e8 | 28 | require('react-datetime'); |
| f13618 | 29 | |
| LC | 30 | ... |
| 31 | ||
| 32 | render: function() { | |
| 614998 | 33 | return <Datetime />; |
| f13618 | 34 | } |
| LC | 35 | ``` |
| 70f4fb | 36 | [See this example working](http://codepen.io/simeg/pen/mEmQmP). |
| f13618 | 37 | |
| 8055e6 | 38 | **Don't forget to add the [CSS stylesheet](https://github.com/YouCanBookMe/react-datetime/blob/master/css/react-datetime.css) to make it work out of the box.** |
| 70f4fb | 39 | |
| 1de42c | 40 | ## API |
| f13618 | 41 | |
| LC | 42 | | Name | Type | Default | Description | |
| 43 | | ------------ | ------- | ------- | ----------- | | |
| 1de42c | 44 | | **value** | `Date` | `new Date()` | Represents the selected date by the component, in order to use it as a [controlled component](https://facebook.github.io/react/docs/forms.html#controlled-components). This prop is parsed by Moment.js, so it is possible to use a date `string` or a `moment` object. | |
| SE | 45 | | **defaultValue** | `Date` | `new Date()` | Represents the selected date for the component to use it as a [uncontrolled component](https://facebook.github.io/react/docs/forms.html#uncontrolled-components). This prop is parsed by Moment.js, so it is possible to use a date `string` or a `moment` object. | |
| 8e5d74 | 46 | | **dateFormat** | `boolean` or `string` | `true` | Defines the format for the date. It accepts any [Moment.js date format](http://momentjs.com/docs/#/displaying/format/) (not in localized format). If `true` the date will be displayed using the defaults for the current locale. If `false` the datepicker is disabled and the component can be used as timepicker, see [available units docs](#specify-available-units). | |
| SE | 47 | | **timeFormat** | `boolean` or `string` | `true` | Defines the format for the time. It accepts any [Moment.js time format](http://momentjs.com/docs/#/displaying/format/) (not in localized format). If `true` the time will be displayed using the defaults for the current locale. If `false` the timepicker is disabled and the component can be used as datepicker, see [available units docs](#specify-available-units). | |
| 1de42c | 48 | | **input** | `boolean` | `true` | Whether to show an input field to edit the date manually. | |
| SE | 49 | | **open** | `boolean` | `null` | Whether to open or close the picker. If not set react-datetime will open the datepicker on input focus and close it on click outside. | |
| 50 | | **locale** | `string` | `null` | Manually set the locale for the react-datetime instance. Moment.js locale needs to be loaded to be used, see [i18n docs](#i18n). | |
| 049c33 | 51 | | **utc** | `boolean` | `false` | When true, input time values will be interpreted as UTC (Zulu time) by Moment.js. Otherwise they will default to the user's local timezone. |
| fe4c5c | 52 | | **onChange** | `function` | empty function | Callback trigger when the date changes. The callback receives the selected `moment` object as only parameter, if the date in the input is valid. If the date in the input is not valid, the callback receives the value of the input (a string). | |
| MV | 53 | | **onFocus** | `function` | empty function | Callback trigger for when the user opens the datepicker. | |
| 54 | | **onBlur** | `function` | empty function | Callback trigger for when the user clicks outside of the input, simulating a regular onBlur. The callback receives the selected `moment` object as only parameter, if the date in the input is valid. If the date in the input is not valid, the callback returned. | | |
| 5377a9 | 55 | | **onViewModeChange** | `function` | empty function | Callback trigger when the view mode changes. The callback receives the selected view mode string (`years`, `months`, `days` or `time`) as only parameter.| |
| 1de42c | 56 | | **viewMode** | `string` or `number` | `'days'` | The default view to display when the picker is shown (`'years'`, `'months'`, `'days'`, `'time'`). | |
| SE | 57 | | **className** | `string` or `string array` | `''` | Extra class name for the outermost markup element. | |
| 8055e6 | 58 | | **inputProps** | `object` | `undefined` | Defines additional attributes for the input element of the component. For example: `placeholder`, `disabled`, `required`, `name` and `className` (`className` *sets* the class attribute for the input element). | |
| 28160e | 59 | | **isValidDate** | `function` | `() => true` | Define the dates that can be selected. The function receives `(currentDate, selectedDate)` and shall return a `true` or `false` whether the `currentDate` is valid or not. See [selectable dates](#selectable-dates).| |
| 8e5d74 | 60 | | **renderDay** | `function` | `DOM.td(day)` | Customize the way that the days are shown in the daypicker. The accepted function has the `selectedDate`, the current date and the default calculated `props` for the cell, and must return a React component. See [appearance customization](#customize-the-appearance). | |
| SE | 61 | | **renderMonth** | `function` | `DOM.td(month)` | Customize the way that the months are shown in the monthpicker. The accepted function has the `selectedDate`, the current date and the default calculated `props` for the cell, the `month` and the `year` to be shown, and must return a React component. See [appearance customization](#customize-the-appearance). | |
| 62 | | **renderYear** | `function` | `DOM.td(year)` | Customize the way that the years are shown in the year picker. The accepted function has the `selectedDate`, the current date and the default calculated `props` for the cell, the `year` to be shown, and must return a React component. See [appearance customization](#customize-the-appearance). | | |
| 1de42c | 63 | | **strictParsing** | `boolean` | `false` | Whether to use Moment.js's [strict parsing](http://momentjs.com/docs/#/parsing/string-format/) when parsing input. |
| SE | 64 | | **closeOnSelect** | `boolean` | `false` | When `true`, once the day has been selected, the datepicker will be automatically closed. |
| 65 | | **closeOnTab** | `boolean` | `true` | When `true` and the input is focused, pressing the `tab` key will close the datepicker. | |
| 66 | | **timeConstraints** | `object` | `null` | Add some constraints to the timepicker. It accepts an `object` with the format `{ hours: { min: 9, max: 15, step: 2 }}`, this example means the hours can't be lower than `9` and higher than `15`, and it will change adding or subtracting `2` hours everytime the buttons are clicked. The constraints can be added to the `hours`, `minutes`, `seconds` and `milliseconds`. | |
| 67 | | **disableOnClickOutside** | `boolean` | `false` | When `true`, keep the datepicker open when click event is triggered outside of component. When `false`, close it. | |
| f13618 | 68 | |
| c37f80 | 69 | ## i18n |
| 1de42c | 70 | Different language and date formats are supported by react-datetime. React uses [Moment.js](http://momentjs.com/) to format the dates, and the easiest way of changing the language of the calendar is [changing the Moment.js locale](http://momentjs.com/docs/#/i18n/changing-locale/). |
| c37f80 | 71 | |
| M | 72 | ```js |
| 73 | var moment = require('moment'); | |
| 74 | require('moment/locale/fr'); | |
| 75 | // Now react-datetime will be in french | |
| 76 | ``` | |
| 77 | ||
| 28160e | 78 | If there are multiple locales loaded, you can use the prop `locale` to define what language shall be used by the instance. |
| c37f80 | 79 | ```js |
| 182c2b | 80 | <Datetime locale="fr-ca" /> |
| c37f80 | 81 | <Datetime locale="de" /> |
| M | 82 | ``` |
| ccbc79 | 83 | [Here you can see the i18n example working](http://codepen.io/simeg/pen/yVVjdJ). |
| c37f80 | 84 | |
| 8055e6 | 85 | ## Customize the Appearance |
| 1de42c | 86 | 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. |
| eba92b | 87 | |
| M | 88 | ```js |
| 89 | var MyDTPicker = React.createClass({ | |
| 90 | render: function(){ | |
| 91 | return <Datetime | |
| 795f65 | 92 | renderDay={ this.renderDay } |
| M | 93 | renderMonth={ this.renderMonth } |
| eba92b | 94 | renderYear={ this.renderYear } |
| M | 95 | />; |
| 96 | }, | |
| 199ffb | 97 | renderDay: function( props, currentDate, selectedDate ){ |
| M | 98 | return <td {...props}>{ '0' + currentDate.date() }</td>; |
| eba92b | 99 | }, |
| 8e5d74 | 100 | renderMonth: function( props, month, year, selectedDate ){ |
| eba92b | 101 | return <td {...props}>{ month }</td>; |
| M | 102 | }, |
| 199ffb | 103 | renderYear: function( props, year, selectedDate ){ |
| M | 104 | return <td {...props}>{ year % 100 }</td>; |
| eba92b | 105 | } |
| M | 106 | }); |
| 107 | ``` | |
| ccbc79 | 108 | [You can see a customized calendar here.](http://codepen.io/simeg/pen/YppLmO) |
| eba92b | 109 | |
| 8055e6 | 110 | #### Method Parameters |
| 1de42c | 111 | * `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. |
| SE | 112 | * `selectedDate` and `currentDate` are [moment objects](http://momentjs.com) and can be used to change the output depending on the selected date, or the date for the current day. |
| 113 | * `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`. | |
| eba92b | 114 | |
| 8e5d74 | 115 | ## Specify Available Units |
| SE | 116 | 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. |
| 117 | ||
| 118 | In this example the component is being used as a *timepicker* and can *only be used for selecting a time*. | |
| 119 | ```js | |
| 120 | <Datetime dateFormat={false} /> | |
| 121 | ``` | |
| 122 | [Working example of a timepicker here.](http://codepen.io/simeg/pen/mRQBrp) | |
| 123 | ||
| 124 | In this example you can *only select a year and month*. | |
| 125 | ```js | |
| 126 | <Datetime dateFormat="YYYY-MM" timeFormat={false} /> | |
| 127 | ``` | |
| 128 | [Working example of only selecting year and month here.](http://codepen.io/simeg/pen/apQLdd) | |
| 129 | ||
| 8055e6 | 130 | ## Selectable Dates |
| 28160e | 131 | 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](http://momentjs.com). The function shall return `true` for selectable dates, and `false` for disabled ones. |
| baa9f1 | 132 | |
| 1de42c | 133 | In the example below are *all dates before today* disabled. |
| SE | 134 | |
| baa9f1 | 135 | ```js |
| 1de42c | 136 | // Let's use the static moment reference in the Datetime component |
| 8e5d74 | 137 | var yesterday = Datetime.moment().subtract( 1, 'day' ); |
| baa9f1 | 138 | var valid = function( current ){ |
| 199ffb | 139 | return current.isAfter( yesterday ); |
| baa9f1 | 140 | }; |
| M | 141 | <Datetime isValidDate={ valid } /> |
| 142 | ``` | |
| ccbc79 | 143 | [Working example of disabled days here.](http://codepen.io/simeg/pen/XNNYJg) |
| baa9f1 | 144 | |
| 1de42c | 145 | It's also possible to disable *the weekends*, as shown in the example below. |
| baa9f1 | 146 | ```js |
| M | 147 | var valid = function( current ){ |
| 1de42c | 148 | return current.day() !== 0 && current.day() !== 6; |
| baa9f1 | 149 | }; |
| M | 150 | <Datetime isValidDate={ valid } /> |
| 151 | ``` | |
| ccbc79 | 152 | [Working example of disabled weekends here.](http://codepen.io/simeg/pen/jVVKWq) |
| baa9f1 | 153 | |
| 0de4da | 154 | ## Usage with TypeScript |
| a20f58 | 155 | |
| 0de4da | 156 | This project includes typings for TypeScript versions 1.8 and 2.0. Additional typings are not |
| a20f58 | 157 | required. |
| AS | 158 | |
| 0de4da | 159 | Typings for 1.8 are found in `react-datetime.d.ts` and typings for 2.0 are found in `typings/index.d.ts`. |
| SE | 160 | |
| a20f58 | 161 | ```js |
| 8055e6 | 162 | import * as Datetime from 'react-datetime'; |
| a20f58 | 163 | |
| AS | 164 | class MyDTPicker extends React.Component<MyDTPickerProps, MyDTPickerState> { |
| 165 | render() JSX.Element { | |
| 166 | return <Datetime />; | |
| 167 | } | |
| 168 | } | |
| 169 | ``` | |
| 170 | ||
| 1de42c | 171 | ## Contributions |
| 9077b2 | 172 | For information about how to contribute, see the [CONTRIBUTING](.github/CONTRIBUTING.md) file. |
| 8055e6 | 173 | |
| SE | 174 | ## Development |
| 175 | ```sh | |
| 176 | npm run dev | |
| 177 | ``` | |
| 178 | This will start a local `webpack-dev-server` based on `example/example.js` where most development can be done. | |
| 179 | ||
| 180 | If you want to develop using the component inside a React application, we recommend that you use [react-datetime-playground](https://github.com/arqex/react-datetime-playground). | |
| 9fb8e8 | 181 | |
| 8abb28 | 182 | ### [Changelog](CHANGELOG.md) |
| M | 183 | |
| 9077b2 | 184 | ### [MIT Licensed](LICENSE.md) |
