Options, methods and events

Options#

Range only#

A TimeMatcher#

Three shapes, mixed freely in one array:

disabled: [
  '15:30',                               // one time
  ['12:00', '13:00'],                    // a span, inclusive
  ['23:00', '06:00'],                    // a span that crosses midnight
  (seconds) => seconds % 3600 !== 0,     // a rule: only on the hour
]

A Slot#

{
  time: '09:30',        // or seconds since midnight
  label?: string,       // what the row says; defaults to the time
  note?: string,        // a second line: "2 left", "AED 250"
  disabled?: boolean,
  reason?: string,      // read out to a screen reader
  className?: string,
}

A bare "09:30" is a slot with nothing else on it.

Methods#

picker.getValue();          // "14:30" — or { start, end } for a range
picker.getTime();           // 52200, seconds since midnight
picker.getDuration();       // range only: seconds, counting past midnight
picker.setValue('09:15');   // or { start: '09:00', end: '17:00' }
picker.setValue('09:15', true);   // silently: no callbacks, no events
picker.getSlots();          // the rows on show, availability worked out
picker.open();
picker.close();
picker.isOpen();
picker.setOptions({ min: '10:00', slots: fresh });
picker.destroy();           // gives the page its own input back

getSlots() is the one to reach for when the times come from a server: render your own summary, count what is left, or check a time before you send it.

const free = picker.getSlots().filter((slot) => !slot.disabled);

Events#

Both CustomEvents on the widget root, and both bubble:

picker.element.addEventListener('dx:timechange', (event) => {
  event.detail.value;   // "14:30" — or { start, end } for a range
});

The input the picker is mounted on also gets the native input and change events, so Livewire, Alpine, FormData, jQuery and any server-rendered form see the value with nothing wired up.

Words#

Fifteen languages ship with the package, and none of them is in your bundle until you ask:

Arabic · Urdu · French · German · Spanish · Portuguese · Italian · Dutch · Turkish · Russian · Polish · Hindi · Indonesian · Chinese · Japanese

import { registerAll } from '@devix-labs/time-picker/locales';

registerAll();                                  // every language, once
createTimePicker(input, { locale: 'ar-AE' });   // now Arabic throughout

Or one, which is what most sites need — your bundler ships only what you name:

import { registerStrings } from '@devix-labs/time-picker';
import { fr } from '@devix-labs/time-picker/locales';

registerStrings('fr', fr);

A pack is 0.3–0.4 KB gzipped; all fifteen together are 3.9 KB, and the widget carries none of it. Registering is global, so <dx-time-picker locale="ar"> in markup is translated too — markup has nowhere to pass an object. fr covers fr-CA as well; register an exact tag when a country needs different wording and it wins for that country only.

Words people type#

A pack also teaches the parser the words that mean a time in its language, so this works without any wiring:

// with fr registered
"midi"    → 12:00
"minuit"  → 00:00
"noon"    → 12:00   // English still parses: a pack adds to the list, it does not replace it

Your own words are added the same way, and are merged with the pack's rather than replacing them:

createTimePicker(input, {
  locale: 'ar-AE',
  strings: { words: { 'وقت الغداء': 13 * 3600 } },
});

Your own wording#

strings wins over a registered pack, one key at a time:

createTimePicker(input, { locale: 'fr', strings: { now: 'À l’instant' } });

And a language nobody has written yet is one object away — a plain object is accepted as well as a function:

import { registerStrings } from '@devix-labs/time-picker';

registerStrings('sw', { now: 'Sasa', clear: 'Futa', chooseTime: 'Chagua saa' });

The complete list of keys is DEFAULT_STRINGS, exported from the package. Anything left out falls back to English rather than showing a blank button. RTL needs nothing at all: the layout uses logical properties.