react-time-picker

A carefully crafted time picker for React

Install

$ npm install react-time-picker --save

Demo

See time picker demo

Usage

var TimePicker = require('./src')

var VALUE = '14:00:01'

var onChange = function(value){
    picker.setProps({value: value})
}

var picker = React.render(
    <TimePicker
        value={VALUE}
        onChange={onChange}
    />,
    document.getElementById('content')
)

For uncontrolled behavior, use defaultValue instead of value

The time picker can also be used on touch devices.

NOTES

The time picker depends on ReactJS and MomentJS.

If you use files from the dist folder:

dist/react-time-picker.js
dist/react-time-picker.min.js

you need to make sure you have React global var set

If you use the .nomoment files

dist/react-time-picker.nomoment.js
dist/react-time-picker.nomoment.min.js

you need to make sure you have both React and moment global vars set.

Properties

value: String - a time value - for controlled behavior
defaultValue: String - a time value - for uncontrolled behavior
onChange: Function(string, moment) - function to be called on change

Formatting

The time picker can display time in multiple formats. For example, you can show hour, hour & minute, hour & minute & second, and all of these with or without AM/PM.

You can specify a format to decide which parts of the time picker to display

format: String - See http://momentjs.com/docs/#/parsing/string-format/. A format that dictates which parts of the time picker are displayed.

Valid format tokens are:
- H or HH - 0..23 - 24 hour time (hour and double digit hour)
- h or hh - 1..12 - 12 hour time used with a A
- m or mm - 0..59 for minute and double digit minute
- s or ss - 0..59 for second and double digit second
- a or A - for meridiem display

So you can decide what to display either by specifying a format or just use the appropriate formatting on the value you provide.

Examples

If you want to display only hour & minute, specify a value string with hour and minute (eg: 16:03)
If you want to display hour, minute & second, specify eg 16:45:21
If you want to display AM/PM, specify an hour format that contains AM/PM eg 10:45 PM

Overflowing

By default when minutes/seconds are incremented, and they overflow 59, the next amount is increased. You can also overflow hour to trigger a meridian change by using overflowHourToMeridian.

Increment steps

When time arrows are triggered, values are incremented with a certain amount - called step. The default step value is 1

step: Number
hourStep: Number - A step for incrementing hours (defaults to null). If not provided, step will be used when incrementing the hour
minuteStep: Number - A step for incrementing minutes (defaults to null). If not provided, step will be used when incrementing the minute
secondStep: Number - A step for incrementing seconds (defaults to null). If not provided, step will be used when incrementing the second

Styling props

The time picker comes with built-in styles, no dependencies on external css files.

style

By default, the timepicker is 200px in width and has padding 10px. You can easily change that:

<TimePicker style={{width: '100%', padding: 5}} />

Styles for time boxes (the div containing the input and the arrows)

boxStyle - style to be applied to all boxes (hour, minute, second, meridian)
hourStyle
minuteStyle
secondStyle
meridianStyle

Styles for time input fields

inputStyle - style to be applied to all time input fields
hourInputStyle
minuteInputStyle
secondInputStyle
meridianInputStyle

Other props

useArrowKeys: Boolean - defaults to true. When this prop is true, you can update time values with arrow up/down keys when field is focused. Set to false if you don't want this behavior
inputFactory: Function(props) - you can control how to render the time inputs, by using this function. It will be called with some props for the input:
- props.timeName: String - the name of the input ('hour', 'minute', etc)
- props.style - the style for the input
- props.value
- props.onChange
- props.onFocus
- props.onBlur
Changing either onChange, onFocus or onBlur of the props passed in to inputFactory is not recommended. If you choose to change those, make sure you know what you're doing or you call the initial functions along with your own logic
showArrows: Boolean - decides whether to show arrows or not. Defaults to true
arrowStyle - style to be applied to all arrows
arrowUpStyle
arrowDownStyle
arrowOverStyle
arrowUpOverStyle
arrowDownOverStyle
arrowFactory
stepDelay: Number - defaults to 60. The amount of milliseconds between amount increments when mouse is down on an arrow
stopChangePropagation: Boolean - defaults to true. Stops the propagation of the change event on the inputs contained in the time picker. Needed so your onChange function will not get called multiple times, and with different arguments. Only modify this if you know what you're doing
normalizeStyle: Boolean - defaults to true. Uses react-style-normalizer to prefix style names when needed. In this case, all style props are prefixed (style, inputStyle, hourStyle, etc... )

Contributing

Check out the project, cd into it and do

$ npm install
$ npm run dev

Navigate to localhost:8080.

Change the sources in the src directory. When a change is detected, the browser is auto refreshed.

To make a new build, execute npm run build, which refreshes the lib folder (for use with npm) from sources found in src, and also creates a concatenated file for use in the browser (minified version as well).

Roadmap

See Roadmap

Changelog

See Changelog

linhhdinh/react-time-picker