view | history | commit | commitdiff
Anna Kurylo
2018-10-16 99929e8c706aa7f6196ac4e02df1c04449feee7a
commit | author | age
1de42c 1 # react-datetime
4afe21 2
267a3a 3 [![Build Status](https://secure.travis-ci.org/YouCanBookMe/react-datetime.svg)](https://travis-ci.org/YouCanBookMe/react-datetime)
7d1067 4 [![npm version](https://badge.fury.io/js/react-datetime.svg)](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. |
25a4ff 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/uncontrolled-components.html). This prop is parsed by Moment.js, so it is possible to use a date `string` or a `moment` object. |
c276ec 46 | **viewDate** | `Date` | `new Date()` | Represents the month which is viewed on opening the calendar when there is no selected date. This prop is parsed by Moment.js, so it is possible to use a date `string` or a `moment` object. |
8e5d74 47 | **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 48 | **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 49 | **input** | `boolean` | `true` | Whether to show an input field to edit the date manually. |
SE 50 | **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. |
51 | **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 52 | **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 53 | **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). |
689227 54 | **onFocus** | `function` | empty function | Callback trigger for when the user opens the datepicker. The callback receives an event of type SyntheticEvent. |
fe4c5c 55 | **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 56 | **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.|
d40f6d 57 | **onNavigateBack** | `function` | empty function | Callback trigger when the user navigates to the previous month, year or decade. The callback receives the amount and type ('month', 'year') as parameters. |
DDD 58 | **onNavigateForward** | `function` | empty function | Callback trigger when the user navigates to the next month, year or decade. The callback receives the amount and type ('month', 'year') as parameters. |
1de42c 59 | **viewMode** | `string` or `number` | `'days'` | The default view to display when the picker is shown (`'years'`, `'months'`, `'days'`, `'time'`). |
SE 60 | **className** | `string` or `string array` | `''` | Extra class name for the outermost markup element. |
b6f2dd 61 | **inputProps** | `object` | `undefined` | Defines additional attributes for the input element of the component. For example: `onClick`, `placeholder`, `disabled`, `required`, `name` and `className` (`className` *sets* the class attribute for the input element). See [Customize the Input Appearance](#customize-the-input-appearance). |
28160e 62 | **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).|
0484e2 63 | **renderInput** | `function` | `undefined` | Replace the rendering of the input element. The function has the following arguments: the default calculated `props` for the input, `openCalendar` (a function which opens the calendar) and `closeCalendar` (a function which closes the calendar). Must return a React component or `null`. See [Customize the Input Appearance](#customize-the-input-appearance). |
b6f2dd 64 | **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 [Customize the Datepicker Appearance](#customize-the-datepicker-appearance). |
DF 65 | **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 [Customize the Datepicker Appearance](#customize-the-datepicker-appearance). |
66 | **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 [Customize the Datepicker Appearance](#customize-the-datepicker-appearance). |
b7a1c5 67 | **strictParsing** | `boolean` | `true` | Whether to use Moment.js's [strict parsing](http://momentjs.com/docs/#/parsing/string-format/) when parsing input.
1de42c 68 | **closeOnSelect** | `boolean` | `false` | When `true`, once the day has been selected, the datepicker will be automatically closed.
SE 69 | **closeOnTab** | `boolean` | `true` | When `true` and the input is focused, pressing the `tab` key will close the datepicker.
70 | **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`.
71 | **disableOnClickOutside** | `boolean` | `false` | When `true`, keep the datepicker open when click event is triggered outside of component. When `false`, close it.
f13618 72
c37f80 73 ## i18n
1de42c 74 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 75
M 76 ```js
77 var moment = require('moment');
78 require('moment/locale/fr');
79 // Now react-datetime will be in french
80 ```
81
28160e 82 If there are multiple locales loaded, you can use the prop `locale` to define what language shall be used by the instance.
c37f80 83 ```js
182c2b 84 <Datetime locale="fr-ca" />
c37f80 85 <Datetime locale="de" />
M 86 ```
ccbc79 87 [Here you can see the i18n example working](http://codepen.io/simeg/pen/yVVjdJ).
c37f80 88
b6f2dd 89 ## Customize the Input Appearance
DF 90 It is possible to customize the way that the input is displayed. The simplest is to supply `inputProps` which get assigned to the default `<input />` element within the component.
91
92 ```js
4eb1d6 93 <Datetime inputProps={{ placeholder: 'N/A', disabled: true }}>
b6f2dd 94 ```
DF 95
96 Alternatively, if you need to render different content than an `<input />` element, you may supply a `renderInput` function which is called instead.
97
98 ```js
99 var MyDTPicker = React.createClass({
100     render: function(){
101         return <Datetime renderInput={ this.renderInput } />;
102     },
0484e2 103     renderInput: function( props, openCalendar, closeCalendar ){
b6f2dd 104         function clear(){
DF 105             props.onChange({target: {value: ''}});
106         }
107         return (
108             <div>
109                 <input {...props} />
110                 <button onClick={openCalendar}>open calendar</button>
0484e2 111                 <button onClick={closeCalendar}>close calendar</button>
b6f2dd 112                 <button onClick={clear}>clear</button>
DF 113             </div>
114         );
115     },
116 });
117 ```
118
119 ## Customize the Datepicker Appearance
1de42c 120 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 121
M 122 ```js
123 var MyDTPicker = React.createClass({
124     render: function(){
125         return <Datetime
795f65 126             renderDay={ this.renderDay }
M 127             renderMonth={ this.renderMonth }
eba92b 128             renderYear={ this.renderYear }
M 129         />;
130     },
199ffb 131     renderDay: function( props, currentDate, selectedDate ){
M 132         return <td {...props}>{ '0' + currentDate.date() }</td>;
eba92b 133     },
8e5d74 134     renderMonth: function( props, month, year, selectedDate ){
eba92b 135         return <td {...props}>{ month }</td>;
M 136     },
199ffb 137     renderYear: function( props, year, selectedDate ){
M 138         return <td {...props}>{ year % 100 }</td>;
eba92b 139     }
M 140 });
141 ```
ccbc79 142 [You can see a customized calendar here.](http://codepen.io/simeg/pen/YppLmO)
eba92b 143
8055e6 144 #### Method Parameters
1de42c 145 * `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 146 * `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.
147 * `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 148
8e5d74 149 ## Specify Available Units
SE 150 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.
0484e2 151
8e5d74 152 In this example the component is being used as a *timepicker* and can *only be used for selecting a time*.
SE 153 ```js
154 <Datetime dateFormat={false} />
155 ```
156 [Working example of a timepicker here.](http://codepen.io/simeg/pen/mRQBrp)
157
158 In this example you can *only select a year and month*.
159 ```js
160 <Datetime dateFormat="YYYY-MM" timeFormat={false} />
161 ```
162 [Working example of only selecting year and month here.](http://codepen.io/simeg/pen/apQLdd)
163
8055e6 164 ## Selectable Dates
28160e 165 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 166
1de42c 167 In the example below are *all dates before today* disabled.
SE 168
baa9f1 169 ```js
1de42c 170 // Let's use the static moment reference in the Datetime component
8e5d74 171 var yesterday = Datetime.moment().subtract( 1, 'day' );
baa9f1 172 var valid = function( current ){
199ffb 173     return current.isAfter( yesterday );
baa9f1 174 };
M 175 <Datetime isValidDate={ valid } />
176 ```
ccbc79 177 [Working example of disabled days here.](http://codepen.io/simeg/pen/XNNYJg)
baa9f1 178
1de42c 179 It's also possible to disable *the weekends*, as shown in the example below.
baa9f1 180 ```js
M 181 var valid = function( current ){
1de42c 182     return current.day() !== 0 && current.day() !== 6;
baa9f1 183 };
M 184 <Datetime isValidDate={ valid } />
185 ```
ccbc79 186 [Working example of disabled weekends here.](http://codepen.io/simeg/pen/jVVKWq)
baa9f1 187
0de4da 188 ## Usage with TypeScript
a20f58 189
0de4da 190 This project includes typings for TypeScript versions 1.8 and 2.0. Additional typings are not
a20f58 191 required.
AS 192
0de4da 193 Typings for 1.8 are found in `react-datetime.d.ts` and typings for 2.0 are found in `typings/index.d.ts`.
SE 194
a20f58 195 ```js
8055e6 196 import * as Datetime from 'react-datetime';
a20f58 197
AS 198 class MyDTPicker extends React.Component<MyDTPickerProps, MyDTPickerState> {
199     render() JSX.Element {
200         return <Datetime />;
201     }
202 }
203 ```
204
1de42c 205 ## Contributions
9077b2 206 For information about how to contribute, see the [CONTRIBUTING](.github/CONTRIBUTING.md) file.
8055e6 207
SE 208 ## Development
209 ```sh
210 npm run dev
211 ```
212 This will start a local `webpack-dev-server` based on `example/example.js` where most development can be done.
213
214 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 215
8abb28 216 ### [Changelog](CHANGELOG.md)
M 217
9077b2 218 ### [MIT Licensed](LICENSE.md)