Validation

The picker checks the value already in the input, the values people pick, and its own options:

• When the picker opens, it reads the input value. If it cannot read it, it shows labels.invalidTimeFormat after the input and emits error. An empty input is not an error.
• It reads 2:30 PM or 02:30 pm on a 12-hour clock (the default) and 14:30 on a 24-hour clock. With clock.showSeconds, seconds are optional: 14:30:15.
• Times blocked by clock.disabledTime are shown as disabled on the clock face and the wheel (or left out, with wheel.hideDisabled) and cannot be picked there. clock.isTimeDisabled works the same way. A time is disabled when clock.disabledTime or the function disables it. See Disabled Time.
• The hour and minute fields inside the picker keep typed values in range: hours 1-12 or 0-23, minutes 0-59.
• create() and setOptions() check clock.disabledTime and report invalid values through error.

Read the selected time in callbacks.onConfirm or with picker.on('confirm'). Both run after the picker has written the new value to the input:

1import { TimepickerUI } from 'timepicker-ui';
2
3const picker = new TimepickerUI('#timepicker', {
4  callbacks: {
5    onConfirm: (data) => {
6      console.log(data.hour, data.minutes, data.type); // 02 30 PM
7    }
8  }
9});
10
11picker.create();
12
13picker.on('confirm', () => {
14  console.log(picker.getValue().time); // 02:30 PM
15});

The payload has hour and minutes, type ('AM' or 'PM', undefined on a 24-hour clock) and, with clock.showSeconds, seconds. The time values are strings. With wheel.commitOnScroll, confirm also fires when a wheel stops scrolling, with autoCommit: true.

The picker sets input.value directly and does not fire input or change events. A listener on the input only sees what people type into it, so check picked values in onConfirm.

The error event and callbacks.onError report four kinds of problems: an input value the picker cannot read, a setValue() string that is not a time, invalid options, and a mode or feature whose plugin is not registered (for example ui.mode: 'wheel' without WheelPlugin).

Invalid Input Detection

Each time the picker opens, it reads the input value. When it cannot, for example 25:00 on a 24-hour clock or 2:30 without AM/PM on a 12-hour clock, it adds the tp-ui-invalid-format class to the input, puts a message right after the input and emits error:

1const picker = new TimepickerUI('#timepicker', {
2  clock: { type: '24h' },
3  labels: { invalidTimeFormat: 'Enter a time as HH:MM' },
4  callbacks: {
5    onError: (data) => {
6      console.warn(data.error, data.inputHour, data.inputMinute);
7    }
8  }
9});
10
11picker.create();
12
13// Input value '25:00', picker opened:
14// Invalid 24h time. 25 0

The message the picker inserts after the input:

<div class="tp-ui-invalid-text" role="alert"><b>Enter a time as HH:MM</b></div>

role="alert" makes screen readers announce it. The text comes from labels.invalidTimeFormat (default Invalid time format). The picker still opens. The message and the class are removed when a time is confirmed or set with setValue(), and on the next open if the value can be read by then. With range.enabled this check is skipped.

setValue() converts a time in the other clock format: 14:30 sets 02:30 PM on a 12-hour clock. A string that is not a time, such as 25:00 or abc, leaves the value and the input as they were and emits error. It does not add the class or the message.

Disabled Time Validation

create() and setOptions() check clock.disabledTime. An hour, minute or second out of range, or a time range that cannot be parsed or overlaps another, is reported through error:

1const picker = new TimepickerUI('#timepicker', {
2  clock: {
3    disabledTime: { hours: [0, 22, 23] }
4  },
5  callbacks: {
6    onError: (data) => console.error(data.error)
7  }
8});
9
10picker.create();
11// [TimepickerUI] Invalid hours or minutes in disabledTime option
12
13console.log(picker.isDestroyed); // true

The default clock is 12-hour, where hours takes 1 to 12, so 0, 22 and 23 are rejected. Set clock.type: '24h' to use them. After a failed create() the picker is not set up and does not open. On a working picker, a failed setOptions() keeps the previous options:

1const picker = new TimepickerUI('#meeting-time', {
2  callbacks: {
3    onError: (data) => console.error(data.error)
4  }
5});
6
7picker.create();
8
9picker.setOptions({
10  clock: {
11    disabledTime: {
12      ranges: ['9:00 AM - 11:00 AM', '10:00 AM - 12:00 PM']
13    }
14  }
15});
16// Logs that the two ranges overlap; the previous options stay

If you use picker.on('error', ...) instead of callbacks.onError, subscribe before create(), so the handler is in place when the options are checked.

Error Payload

• error: a short English description, for example Invalid 24h time. Use it for logging. The text people see comes from labels.invalidTimeFormat.
• inputHour, inputMinute: the hour and minute read from the input.
• inputSecond: the seconds, only with clock.showSeconds.
• inputType: the AM/PM part as typed.
• inputLength: the length of the value, set when the AM/PM part or the length is wrong.

Which input* fields are set depends on what went wrong. Option, plugin and setValue() errors carry only error. rejectedHour and rejectedMinute are deprecated and always undefined.

clock.disabledTime covers fixed rules. For anything else, such as a limit that changes or a rule that depends on another field, check the value in callbacks.onConfirm. The input already holds the new value at that point, so you can clear it and show your own message. The picker closes either way.

Minimum Time Validation

1<label for="pickup-time">Pickup time</label>
2<input id="pickup-time" type="text" aria-describedby="pickup-time-error" />
3<p id="pickup-time-error" role="alert"></p>

1import { TimepickerUI } from 'timepicker-ui';
2
3const input = document.querySelector<HTMLInputElement>('#pickup-time')!;
4const message = document.querySelector<HTMLElement>('#pickup-time-error')!;
5
6function toMinutes(hour = '0', minutes = '0', type?: string): number {
7  let h = Number(hour);
8  if (type === 'PM' && h < 12) h += 12;
9  if (type === 'AM' && h === 12) h = 0;
10  return h * 60 + Number(minutes);
11}
12
13function showError(text: string): void {
14  message.textContent = text;
15  input.setAttribute('aria-invalid', 'true');
16}
17
18function clearError(): void {
19  message.textContent = '';
20  input.removeAttribute('aria-invalid');
21}
22
23const earliest = toMinutes('10', '30', 'AM');
24
25const picker = new TimepickerUI(input, {
26  callbacks: {
27    onConfirm: ({ hour, minutes, type }) => {
28      if (toMinutes(hour, minutes, type) < earliest) {
29        input.value = '';
30        showError('Pickup starts at 10:30 AM.');
31        return;
32      }
33      clearError();
34    }
35  }
36});
37
38picker.create();

toMinutes works for both clock types; type is undefined on a 24-hour clock. The message element has role="alert", so screen readers announce it when its text changes.

Time Range Validation

For a fixed window, use clock.disabledTime.ranges instead of a check after the fact. Times outside the window cannot be picked on the clock face or the wheel:

1const picker = new TimepickerUI('#meeting-time', {
2  clock: {
3    type: '24h',
4    disabledTime: {
5      ranges: ['00:00 - 08:59', '17:01 - 23:59']
6    }
7  }
8});
9
10picker.create();

Ranges include both ends, so this leaves 09:00 to 17:00. If people can type into the hour and minute fields (ui.editable or the keyboard view), also check the confirmed value as in the example above.

Date-Time Validation

1const dateInput = document.querySelector<HTMLInputElement>('#pickup-date')!;
2
3const picker = new TimepickerUI(input, {
4  clock: { type: '24h' },
5  callbacks: {
6    onConfirm: ({ hour, minutes }) => {
7      if (!dateInput.value) {
8        showError('Pick a date first.');
9        return;
10      }
11
12      const [year, month, day] = dateInput.value.split('-').map(Number);
13      const selected = new Date(year, month - 1, day, Number(hour), Number(minutes));
14
15      if (selected.getTime() <= Date.now()) {
16        input.value = '';
17        showError('Pick a time later than now.');
18        return;
19      }
20
21      clearError();
22    }
23  }
24});
25
26picker.create();

#pickup-date is an <input type="date">, whose value is YYYY-MM-DD. input, showError and clearError come from the first example.

Native form validation works on the input the picker is attached to. Use type="text". A type="time" input only takes values like 14:30, so it drops 12-hour values such as 02:30 PM, and the browser adds its own time controls. min, max and step apply only to type="time". Use clock.disabledTime and clock.incrementMinutes instead.

Required Time Input

1<form>
2  <label for="meeting-time">Meeting time</label>
3  <input id="meeting-time" type="text" required />
4  <button type="submit">Schedule</button>
5</form>

1const picker = new TimepickerUI('#meeting-time', {
2  clock: { type: '24h' }
3});
4
5picker.create();

With required, the browser blocks the submit and shows its own message while the input is empty. No extra code is needed.

Custom Validation Messages

setCustomValidity() adds your own rule to the browser's check. Call it from onConfirm for picked values and from change for typed ones:

1const input = document.querySelector<HTMLInputElement>('#meeting-time')!;
2
3function checkBusinessHours(): void {
4  const { hour, minutes } = picker.getValue();
5  const total = Number(hour) * 60 + Number(minutes);
6  const outside = total < 9 * 60 || total > 17 * 60;
7  input.setCustomValidity(outside ? 'Business hours are 09:00 to 17:00.' : '');
8}
9
10const picker = new TimepickerUI(input, {
11  clock: { type: '24h' },
12  callbacks: { onConfirm: checkBusinessHours }
13});
14
15picker.create();
16
17input.addEventListener('change', checkBusinessHours);

During onConfirm the input already holds the confirmed time, so getValue() returns it. The browser shows the message when the form is submitted.

When the picker cannot read the input value, it adds tp-ui-invalid-format to the input and inserts a tp-ui-invalid-text element after it. main.css gives the input a 2px border and colors its text and the message with --tp-error. The message text comes from labels.invalidTimeFormat.

Error Styling

1:root {
2  --tp-error: #b3261e;
3}
4
5.tp-ui-invalid-format {
6  border-radius: 8px;
7}
8
9.tp-ui-invalid-text {
10  margin-top: 4px;
11  font-size: 0.875rem;
12}

The message is text, so the error is not shown by color alone.

Complete Example

The picker's own check for values it cannot read, plus a rule of your own with its own message. Both states get the same border:

1<div class="field">
2  <label for="pickup-time">Pickup time</label>
3  <input id="pickup-time" type="text" aria-describedby="pickup-time-error" />
4  <p id="pickup-time-error" class="field-error" role="alert"></p>
5</div>
6
7<style>
8  .field input {
9    border: 2px solid #d1d5db;
10    border-radius: 8px;
11    padding: 8px 12px;
12    font-size: 16px;
13  }
14
15  .field input[aria-invalid='true'],
16  .field input.tp-ui-invalid-format {
17    border-color: #b3261e;
18  }
19
20  .field-error {
21    margin-top: 4px;
22    color: #b3261e;
23    font-size: 0.875rem;
24  }
25</style>

1import { TimepickerUI } from 'timepicker-ui';
2import 'timepicker-ui/main.css';
3
4const input = document.querySelector<HTMLInputElement>('#pickup-time')!;
5const message = document.querySelector<HTMLElement>('#pickup-time-error')!;
6
7function setError(text: string): void {
8  message.textContent = text;
9  if (text) {
10    input.setAttribute('aria-invalid', 'true');
11  } else {
12    input.removeAttribute('aria-invalid');
13  }
14}
15
16const picker = new TimepickerUI(input, {
17  clock: { type: '24h' },
18  labels: { invalidTimeFormat: 'Enter a time as HH:MM' },
19  callbacks: {
20    onConfirm: ({ hour, minutes }) => {
21      const total = Number(hour) * 60 + Number(minutes);
22      if (total < 10 * 60 + 30) {
23        input.value = '';
24        setError('Pickup starts at 10:30.');
25        return;
26      }
27      setError('');
28    },
29    onError: (data) => console.warn(data.error)
30  }
31});
32
33picker.create();