| commit | author | age | ||
| 9fb8e8 | 1 | react-datetime |
| 4afe21 | 2 | =============================== |
| 18dc17 | 3 | 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. |
| 4afe21 | 4 | |
| 267a3a | 5 | [](https://travis-ci.org/YouCanBookMe/react-datetime) |
| 7d1067 | 6 | [](http://badge.fury.io/js/react-datetime) |
| 889b6c | 7 | |
| eba92b | 8 | It allows to edit even date's milliseconds. |
| M | 9 | |
| 18dc17 | 10 | 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 | 11 | |
| f13618 | 12 | Usage |
| LC | 13 | =============================== |
| 14 | ||
| 70f4fb | 15 | Installation: |
| f13618 | 16 | ``` |
| 70f4fb | 17 | npm install --save react-datetime |
| f13618 | 18 | ``` |
| LC | 19 | |
| f60b22 | 20 | [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 datetime picker work. |
| M | 21 | |
| f13618 | 22 | Then |
| LC | 23 | ```javascript |
| 9fb8e8 | 24 | require('react-datetime'); |
| f13618 | 25 | |
| LC | 26 | ... |
| 27 | ||
| 28 | render: function() { | |
| 9fb8e8 | 29 | return <Datetime />; |
| f13618 | 30 | } |
| LC | 31 | ``` |
| 70f4fb | 32 | [See this example working](http://codepen.io/simeg/pen/mEmQmP). |
| f13618 | 33 | |
| 70f4fb | 34 | **Don't forget to add the [CSS stylesheet](https://github.com/arqex/react-datetime/blob/master/css/react-datetime.css) to make it work out of the box.** |
| SE | 35 | |
| 36 | Build the component (Mac / Linux): | |
| 37 | ``` | |
| 38 | npm run build:mac | |
| 39 | ``` | |
| 40 | ||
| 41 | Build the component (Windows): | |
| 42 | ``` | |
| 43 | npm run build:windows | |
| 44 | ``` | |
| 08dd0e | 45 | |
| f13618 | 46 | API |
| LC | 47 | =============================== |
| 48 | ||
| 49 | | Name | Type | Default | Description | | |
| 50 | | ------------ | ------- | ------- | ----------- | | |
| 0d9dc7 | 51 | | **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.js date. | |
| M | 52 | | **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.js date. | |
| cbe644 | 53 | | **dateFormat** | `bool` or `string` | `true` | Defines the format for the date. It accepts any [moment.js date format](http://momentjs.com/docs/#/displaying/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. | |
| M | 54 | | **timeFormat** | `bool` or `string` | `true` | Defines the format for the time. It accepts any [moment.js time format](http://momentjs.com/docs/#/displaying/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. | |
| c37f80 | 55 | | **input** | boolean | true | Wether to show an input field to edit the date manually. | |
| 87c677 | 56 | | **open** | boolean | null | Wether to open or close the picker. If not set react-datetime will open the datepicker on input focus and close it on click outside. | |
| c37f80 | 57 | | **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). |
| 62fd2f | 58 | | **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 it isn't, the value of the input (a string) is returned. | |
| aca9e6 | 59 | | **onFocus** | function | empty function | Callback trigger for when the user opens the datepicker. | |
| 62fd2f | 60 | | **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 it isn't, the value of the input (a string) is returned. | |
| 9fb8e8 | 61 | | **viewMode** | string or number | 'days' | The default view to display when the picker is shown. ('years', 'months', 'days', 'time') | |
| 8abb28 | 62 | | **className** | string | `""` | Extra class names for the component markup. | |
| 4cdcdb | 63 | | **inputProps** | object | undefined | Defines additional attributes for the input element of the component. | |
| baa9f1 | 64 | | **isValidDate** | function | () => true | Define the dates that can be selected. The function receives `(currentDate, selectedDate)` and should return a `true` or `false` whether the `currentDate` is valid or not. See [selectable dates](#selectable-dates).| |
| 0d9dc7 | 65 | | **renderDay** | function | DOM.td( day ) | Customize the way that the days are shown in the day picker. 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](#appearance-customization) | |
| M | 66 | | **renderMonth** | function | DOM.td( month ) | Customize the way that the months are shown in the month picker. 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](#appearance-customization) | |
| 67 | | **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](#appearance-customization) | | |
| 0eb226 | 68 | | **strictParsing** | boolean | false | Whether to use moment's [strict parsing](http://momentjs.com/docs/#/parsing/string-format/) when parsing input. |
| c22fcc | 69 | | **closeOnSelect** | boolean | false | When `true`, once the day has been selected, the react-datetime will be automatically closed. |
| 52191d | 70 | | **closeOnTab** | boolean | true | When `true` and the input is focused, pressing the `tab` key will close the picker. |
| f13618 | 71 | |
| c37f80 | 72 | ## i18n |
| M | 73 | 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/). |
| 74 | ||
| 75 | ```js | |
| 76 | var moment = require('moment'); | |
| 77 | require('moment/locale/fr'); | |
| 78 | // Now react-datetime will be in french | |
| 79 | ``` | |
| 80 | ||
| 81 | If there are multiple locales loaded, you can use the prop `locale` to define what language should be used by the instance: | |
| 82 | ```js | |
| 182c2b | 83 | <Datetime locale="fr-ca" /> |
| c37f80 | 84 | <Datetime locale="de" /> |
| M | 85 | ``` |
| 86 | [Here you can see the i18n example working](http://codepen.io/arqex/pen/PqJMQV). | |
| 87 | ||
| eba92b | 88 | ## Appearance customization |
| M | 89 | It is possible to customize the way that the datetime picker display the days, months and years in the calendar. To adapt the calendar to every need it is possible to use the props `renderDay( props, currentDate, selectedDate )`, `renderMonth( props, month, year, selectedDate )` and `renderYear( props, year, selectedDate )` of react-datetime. |
| 90 | ||
| 91 | ```js | |
| 92 | var MyDTPicker = React.createClass({ | |
| 93 | render: function(){ | |
| 94 | return <Datetime | |
| 795f65 | 95 | renderDay={ this.renderDay } |
| M | 96 | renderMonth={ this.renderMonth } |
| eba92b | 97 | renderYear={ this.renderYear } |
| M | 98 | />; |
| 99 | }, | |
| 199ffb | 100 | renderDay: function( props, currentDate, selectedDate ){ |
| M | 101 | return <td {...props}>{ '0' + currentDate.date() }</td>; |
| eba92b | 102 | }, |
| 199ffb | 103 | renderMonth: function( props, month, year, selectedDate){ |
| eba92b | 104 | return <td {...props}>{ month }</td>; |
| M | 105 | }, |
| 199ffb | 106 | renderYear: function( props, year, selectedDate ){ |
| M | 107 | return <td {...props}>{ year % 100 }</td>; |
| eba92b | 108 | } |
| M | 109 | }); |
| 110 | ``` | |
| 199ffb | 111 | [You can see this customized calendar here.](http://codepen.io/arqex/pen/mJzRwM) |
| eba92b | 112 | |
| M | 113 | * `props` is the object that react-date picker 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. |
| 114 | * `selectedDate` and `currentDate` are Moment.js objects and can be used to change the output depending on the selected date, or the date for the current day. | |
| 115 | * `month` and `year` are the numeric representation of the current month and year to be displayed. Notice that the possible `month` values go from `0` to `11`. | |
| 116 | ||
| baa9f1 | 117 | ## Selectable dates |
| M | 118 | It is possible to disable dates in the calendar if we don't want the user to select them. It is possible thanks to the prop `isValidDate`, which admits a function in the form `function( currentDate, selectedDate )` where both arguments are moment.js objects. The function should return `true` for selectable dates, and `false` for disabled ones. |
| 119 | ||
| 120 | If we want to disable all the dates before today we can do like | |
| 121 | ```js | |
| 199ffb | 122 | // Let's use moment static reference in the Datetime component. |
| M | 123 | var yesterday = Datetime.moment().subtract(1,'day'); |
| baa9f1 | 124 | var valid = function( current ){ |
| 199ffb | 125 | return current.isAfter( yesterday ); |
| baa9f1 | 126 | }; |
| M | 127 | <Datetime isValidDate={ valid } /> |
| 128 | ``` | |
| 199ffb | 129 | [See the isValidDate prop working here](http://codepen.io/arqex/pen/jPeyGX). |
| baa9f1 | 130 | |
| 199ffb | 131 | If we want to disable the weekends |
| baa9f1 | 132 | ```js |
| M | 133 | var valid = function( current ){ |
| 199ffb | 134 | return current.day() != 0 && current.day() != 6; |
| baa9f1 | 135 | }; |
| M | 136 | <Datetime isValidDate={ valid } /> |
| 137 | ``` | |
| 199ffb | 138 | [The example working here](http://codepen.io/arqex/pen/VLEPXb). |
| baa9f1 | 139 | |
| ce8749 | 140 | Contributions |
| LC | 141 | =============================== |
| 9fb8e8 | 142 | Any help is always welcome :) |
| M | 143 | |
| f27565 | 144 | **Please use the linter before submitting your pull request.** |
| SE | 145 | |
| 146 | ``` | |
| 147 | npm run lint | |
| 148 | ``` | |
| 149 | ||
| 8abb28 | 150 | ### [Changelog](CHANGELOG.md) |
| M | 151 | |
| 9fb8e8 | 152 | ### [MIT Licensed](LICENSE) |
