NUI-Widgets documentation has moved to Storybook hosted on Github Pages.

TimePicker

There is a breaking change to this component in the next version of NUI Widgets.
  • The readOnly prop will behave differently in a future version of NUI Widgets. The Button will no longer appear in readOnly TimePickers.
import TimePicker from '@concur/nui-widgets/lib/TimePicker/TimePicker';

A TimePicker component allows the entry of time, validation of time strings, and the formatted display of times. It uses an <input> element for time entry and display, and includes a popover with dropdowns for selecting a time using keyboard or mouse.

The HTML autocomplete attribute for the input element is enabled by default meaning browsers will try and provide suggestions for input fields. SAP Concur components that provide dropdowns or popovers to assist with populating an input field attempt to disable the browser's suggestions. Please open an issue if you are seeing browser suggestion behavior for these components. See the support page for more information.

Examples

Default

The following demonstrates a default TimePicker with no customizations.

<FormGroup>
    <ControlLabel>Enter desired time</ControlLabel>
    <TimePicker />
</FormGroup>

Sizes

There are 3 supported timepicker sizes: lg (default), md and sm. The large size is recommended for all NUI experiences. Use the size property to set the appropriate size.

<FormGroup>
    <ControlLabel>Enter desired time</ControlLabel>
    <TimePicker />
</FormGroup>

<FormGroup size='md'>
    <ControlLabel>Enter desired time</ControlLabel>
    <TimePicker size='md' />
</FormGroup>

<FormGroup size='sm'>
    <ControlLabel>Enter desired time</ControlLabel>
    <TimePicker size='sm' />
</FormGroup>

Time Format

The timeFormat property is useful for formatting and validating time. It is also shown as the placeholder for the <input> element. Formats are those allowed by Moment.js (scroll to the Hour, minute, second, millisecond, and offset tokens section). Either : or . can be used as a separator.

If a user enters a valid time with :, . or an empty space between numbers, it will be reformatted to the timeFormat when onBlur is triggered by leaving the input field. If an invalid time is entered, the input will be set back to the default or initialValue, if provided.

<FormGroup>
    <ControlLabel>Enter desired time</ControlLabel>
    <TimePicker timeFormat='HH.mm.ss' />
</FormGroup>

<FormGroup>
    <ControlLabel>Enter desired time</ControlLabel>
    <TimePicker timeFormat='HH:mm' />
</FormGroup>

<FormGroup>
    <ControlLabel>Enter desired time</ControlLabel>
    <TimePicker timeFormat='hh:mm a' />
</FormGroup>

Initial Value

A default value can be set for the TimePicker using the initialValue property. This must be a valid time and match the timeFormat.

<FormGroup>
    <ControlLabel>Enter desired time</ControlLabel>
    <TimePicker
        initialValue='18:10:15'
        timeFormat='HH.mm.ss' />
</FormGroup>

<FormGroup>
    <ControlLabel>Enter desired time</ControlLabel>
    <TimePicker
        initialValue='18:10'
        timeFormat='HH:mm' />
</FormGroup>

<FormGroup>
    <ControlLabel>Enter desired time</ControlLabel>
    <TimePicker
        initialValue='6:10 PM'
        timeFormat='hh:mm a' />
</FormGroup>

Disabled State

Set the disabled property to change the TimePicker’s state to disabled.

<FormGroup>
    <ControlLabel>Enter desired time</ControlLabel>
    <TimePicker disabled initialValue='10:10:36 PM' />
</FormGroup>

ReadOnly State

Set the readOnly property to change the TimePicker’s state to readOnly. A read-only field cannot be modified. However, a user can tab to it, highlight it, and copy the text from it.

<FormGroup>
    <ControlLabel>Desired time</ControlLabel>
    <TimePicker readOnly />
</FormGroup>

<FormGroup>
    <ControlLabel>Desired time</ControlLabel>
    <TimePicker initialValue='10:10:36 PM' readOnly />
</FormGroup>

Usage

Properties

Property Type Default Description
buttonProps Object   Properties to pass through to the clock button.
disabled Boolean false Controls whether the component is enabled or disabled.
flipContainer Element or Element[]   Used to create a boundary for the underlying Popper to stay within.
id String   The DOM id of the <input> element.
initialValue String   Value to show in the <input> element when rendered. If no initialValue is set, the <input> placeholder will display the timeFormat and the dropdowns will default to midnight.
inputRef Ref or Function   Attach a ref to the <input> element.
localizedText Object   Contains all the localized text strings for the component. See Localized Text for details.
minutesStep Number 1 The minutes dropdown is populated only by multiples of the step.
placement String or String[] ['bottom-end', 'top-end', 'bottom-start', 'top-start'], Placement of the popover relative to the button. Options are 'auto', 'auto-start', 'auto-end', 'top', 'top-start', 'top-end', 'bottom', 'bottom-start', 'bottom-end', 'left', 'left-start', 'left-end', 'right', 'right-start', 'right-end'. If you use an array of strings, the first item in the array is the default placement and the following ones are chosen in order as fallback placements if the preceding ones don’t work.
popperClassName String   Passes the provided class name to the TimePicker overlay.
readOnly Boolean false Adds the readonly attribute to the <input> element.
required Boolean false Adds the required attribute to the <input> element. NOTE: This does not perform any validation, but rather just marks the field as required.
secondsStep Number 1 The seconds dropdown is populated only by multiples of the step.
show Boolean false Controls whether the popover is visible.
size String 'lg' Size of input group. Options are 'sm', 'md', and 'lg'.
timeFormat String 'h:mm:ss A' Time format to use for formatting and validating dates. Also shown as the placeholder for the <input> element. Formats are those allowed by Moment.js (scroll to the Hour, minute, second, millisecond, and offset tokens section).
validationMessageState String   If used in conjunction with field validation, this provides the icon next to the label. Options are 'error', 'warning'.

Callbacks

Property Parameters Description
onBlur Object {value, rawValue} Callback function for onBlur events. In the object returned, value is the time moment object, rawValue is the text from the <input> element. If the time is not valid, value will be null. NOTE: Likely the best callback to use to perform any custom validation.
onFocus Object {value, rawValue} Callback function for onFocus events. In the object returned, value is the time object, rawValue is the text from the <input> element. If the time is not valid, value will be null.
onHide event Callback function for when TimePicker overlay is closed.
onSelect Object {value, rawValue} Callback function when buttonConfirm is clicked in timepicker dropdown. In the object returned, value is the time object, rawValue is the text from the <input> element.

Localized Text

Property Type Default Description
buttonCancel String 'Cancel' Localized text for the cancel button inside the TimePicker overlay.
buttonConfirm String 'OK' Localized text for the confirm button inside the TimePicker overlay.
buttonToggle String 'Time Toggle' Localized assistive text for the clock icon/button.
hour String 'Hours' Localized text for the hours dropdown label inside the TimePicker overlay.
meridiem String 'AM/PM' Localized text for the meridiem dropdown label inside the TimePicker overlay.
minute String 'Minutes' Localized text for the minutes dropdown label inside the TimePicker overlay.
second String 'Seconds' Localized text for the seconds dropdown label inside the TimePicker overlay.