RedHatTraining/react-datetime.git

Simon Egersand

2018-02-01 80582080ed523fcb9f85300438e066b76a008a4f

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