Feature

Seconds

Let users pick hours, minutes and seconds. Turn it on with clock.showSeconds. Added in 4.5.0.

How do I show seconds?

Set clock.showSeconds to true.

index.tstypescript

1const picker = new TimepickerUI(input, {
2  clock: {
3    showSeconds: true
4  }
5});
6picker.create();

What changes:

The header gets a seconds field.
The analog clock gets a seconds face.
The wheel and compact-wheel modes get a seconds column.
The input value, getValue() and the event payloads include seconds.

showSeconds is off by default. When it is off, there is no seconds field, face or column, and the values, getValue() and the event payloads have no seconds.

Which options control seconds?

Option	Type	Default	Description
`clock.showSeconds`	`boolean`	`false`	Adds the seconds field, the seconds clock face and the seconds wheel column. Values become HH:MM:SS.
`clock.incrementSeconds`	`1 \| 5 \| 10 \| 15 \| 20 \| 30`	`1`	Step for the seconds face, the seconds wheel column and the keyboard.
`clock.autoSwitchToSeconds`	`boolean`	`true`	After a minute is picked on the clock face, the face switches to seconds.
`clock.disabledTime.seconds`	`Array<string \| number>`	`undefined`	Seconds (0 to 59) disabled in every minute.
`labels.second`	`string`	`"Second"`	Caption under the seconds field in the keyboard view, the field's accessible name, the name of the seconds wheel column and of the clock face while it shows seconds, and the prefix announced with the selected seconds.
`callbacks.onSelectSecond`	`(data: SelectSecondEventData) => void`	`undefined`	Runs on the select:second event with { seconds }.

index.tstypescript

1const picker = new TimepickerUI(input, {
2  clock: {
3    type: '24h',
4    showSeconds: true,
5    incrementSeconds: 5,
6    autoSwitchToSeconds: true
7  }
8});
9picker.create();

What does the value look like?

24-hour

HH:MM:SS, for example 14:30:15.

index.tstypescript

1// clock: { type: '24h', showSeconds: true }
2const value = picker.getValue();
3
4// Output:
5{
6  hour: '14',
7  minutes: '30',
8  seconds: '15',
9  type: undefined,
10  time: '14:30:15',
11  // degreesHours and degreesMinutes are still returned but deprecated
12}

12-hour

HH:MM:SS AM or HH:MM:SS PM, for example 02:30:15 PM. The hour is zero-padded. The period is always AM or PM, even if you translate labels.am and labels.pm.

index.tstypescript

1// clock: { type: '12h', showSeconds: true }
2const value = picker.getValue();
3
4// Output:
5{
6  hour: '02',
7  minutes: '30',
8  seconds: '15',
9  type: 'PM',
10  time: '02:30:15 PM',
11  // degreesHours and degreesMinutes are still returned but deprecated
12}

Setting a value

setValue() accepts seconds. A value without seconds, typed or set, is read as :00. If showSeconds is off, seconds in the string are dropped. clock.defaultTime: 'now' fills in the current seconds too.

index.tstypescript

1// clock: { type: '24h', showSeconds: true }
2picker.setValue('14:30:15');
3picker.setValue('14:30');        // becomes 14:30:00
4
5// clock: { type: '12h', showSeconds: true }
6picker.setValue('2:30:15 PM');   // the input shows 02:30:15 PM

How do seconds work in each mode?

Clock

The face goes hours, then minutes, then seconds. With autoSwitchToSeconds on (the default), picking a minute opens the seconds face. Click the seconds field in the header to open it at any time.

Wheel

Three columns: hours, minutes and seconds. In 12h, AM and PM stay in the header.

Compact wheel

Columns HH : MM : SS, plus AM/PM in 12h. Keyboard navigation and wheel.hideDisabled cover the seconds column.

Keyboard view

Three editable fields, each with a caption. The seconds caption comes from labels.second.

Every built-in theme styles the seconds field, face and column. The wheel modes need the wheel plugin:

index.tstypescript

1import { TimepickerUI, PluginRegistry } from 'timepicker-ui';
2import { WheelPlugin } from 'timepicker-ui/plugins/wheel';
3
4PluginRegistry.register(WheelPlugin);
5
6const picker = new TimepickerUI(input, {
7  ui: { mode: 'compact-wheel' },
8  clock: { type: '24h', showSeconds: true, incrementSeconds: 5 },
9  wheel: { placement: 'auto' }
10});
11picker.create();

How do I disable seconds?

List the seconds to block in clock.disabledTime.seconds. They are blocked in every minute. The list is used only with showSeconds.

index.tstypescript

1const picker = new TimepickerUI(input, {
2  clock: {
3    showSeconds: true,
4    disabledTime: {
5      seconds: [55, 56, 57, 58, 59]
6    }
7  }
8});
9picker.create();

Ranges with seconds

The edges of clock.disabledTime.ranges can carry seconds. This example blocks 10:00:30 AM up to and including 10:05:59 AM:

index.tstypescript

1const picker = new TimepickerUI(input, {
2  clock: {
3    type: '12h',
4    showSeconds: true,
5    disabledTime: {
6      ranges: '10:00:30 AM - 10:05 AM'
7    }
8  }
9});
10picker.create();
11
12// 24h, several ranges:
13// ranges: ['12:00:00 - 12:00:30', '18:30 - 18:45:15']

How edges are read

Both edges are inclusive.
An edge without seconds covers its whole minute. A start of 10:00 means 10:00:00. An end of 12:30 means 12:30:59. So a range written for 4.4.0 disables exactly the same minutes.
An edge with seconds is exact.
12h edges need AM or PM. 24h edges must not have them.
Ranges must not overlap. Because an edge without seconds covers its whole minute, '10:00 - 10:05' and '10:05 - 10:10' overlap. Start the second one at 10:06.
Overnight ranges (start later than end) are not supported. Split them in two, for example ['22:00 - 23:59', '00:00 - 06:00'].
When ranges is set, the hours, minutes and seconds lists are ignored.
With seconds on, a minute is disabled only when all of its seconds fall inside a range, and an hour only when all of its minutes do. In the example above, minute 10:00 stays selectable because 10:00:00 to 10:00:29 are free.

Invalid ranges

A malformed or overlapping range is rejected and reported through the error event and callbacks.onError. On create(), the picker then does not open. On setOptions(), the previous options stay in place.

index.tstypescript

1const picker = new TimepickerUI(input, {
2  clock: {
3    type: '24h',
4    showSeconds: true,
5    disabledTime: {
6      ranges: '10:00 AM - 11:00 AM'   // AM/PM on a 24h clock: rejected
7    }
8  },
9  callbacks: {
10    onError: (data) => console.error(data.error)
11  }
12});
13picker.create();

How do seconds work with the range plugin?

range:confirm and range:validation carry durationSeconds, the exact length in seconds.
duration stays in whole minutes, rounded down.
range.minDuration and range.maxDuration are still in minutes, but they are compared to the exact length. With minDuration: 1, a 59-second range is invalid and a 60-second range is valid.
Empty From and To tabs show --:--:--.

index.tstypescript

1import { TimepickerUI, PluginRegistry } from 'timepicker-ui';
2import { RangePlugin } from 'timepicker-ui/plugins/range';
3
4PluginRegistry.register(RangePlugin);
5
6const picker = new TimepickerUI(input, {
7  clock: { type: '24h', showSeconds: true },
8  range: { enabled: true, minDuration: 1 },
9  callbacks: {
10    onRangeConfirm: (data) => {
11      console.log(data.from, data.to);    // '14:00:00' '14:01:30'
12      console.log(data.duration);         // 1
13      console.log(data.durationSeconds);  // 90
14    }
15  }
16});
17picker.create();

Which events carry seconds?

select:second (and onSelectSecond) with { seconds }. It fires when the seconds field or face is selected, and when the seconds wheel column stops on a value.
open, confirm and update add a seconds field.
error adds inputSecond when the input's seconds are invalid.

These fields appear only when showSeconds is on.

index.tstypescript

1picker.on('select:second', (data) => {
2  console.log('Seconds:', data.seconds);
3});
4
5picker.on('confirm', (data) => {
6  console.log(data.hour, data.minutes, data.seconds, data.type);
7});

How do I translate the seconds labels?

One label covers seconds: labels.second is the caption in the keyboard view, the accessible name of the seconds field and wheel column, and the prefix of the announced value. A Polish example:

index.tstypescript

1const picker = new TimepickerUI(input, {
2  clock: { type: '24h', showSeconds: true },
3  labels: {
4    clockTitle: 'Wybierz godzinę',
5    keyboardTitle: 'Wpisz godzinę',
6    cancel: 'Anuluj',
7    hour: 'Godzina',
8    minute: 'Minuta',
9    second: 'Sekunda'
10  }
11});
12picker.create();

Version

Seconds need timepicker-ui 4.5.0 or later.

Try it

Live pickers with seconds in clock, wheel, compact-wheel and range modes.

Open the seconds examples