Methods API Reference

create()

Binds the input and triggers. Mounts the picker when ui.inline.enabled is set. Calling it again does nothing. The constructor throws when it finds no input, so call create() after the input exists.

1const picker = new DatepickerUI("#date");
2picker.create();

open()

Opens the picker. Does nothing for an inline picker.

picker.open();

close()

Closes the picker.

picker.close();

destroy(options?)

Removes everything the picker added and restores the input. Clears the input text unless keepInputValue is true.

1picker.destroy();
2
3picker.destroy({ keepInputValue: true });

getValue()

Returns the committed value, or null when nothing is committed or a range has no end yet. The shape depends on calendar.mode. value is ISO YYYY-MM-DD (YYYY-MM for month precision, YYYY for year precision), date is a Date at local midnight and formatted is the text as the input shows it.

1// calendar.mode: "single"
2picker.getValue();
3// { value: "2025-03-14", date: Date, formatted: "14/03/2025" }
4
5// calendar.mode: "range"
6picker.getValue();
7// { start: DateValue, end: DateValue }
8
9// calendar.mode: "multiple", sorted
10picker.getValue();
11// DateValue[]

setValue(value)

Sets the committed value and the input text. Pass null to clear. It does not emit confirm. A value that does not fit calendar.mode emits an error event with code invalid-date.

1// single: a Date or an ISO string
2picker.setValue("2025-03-14");
3picker.setValue(new Date(2025, 2, 14));
4
5// range: { start, end }
6picker.setValue({ start: "2025-03-14", end: "2025-03-20" });
7
8// multiple: an array
9picker.setValue(["2025-03-14", "2025-03-16"]);
10
11// month precision accepts "2026-10" too
12picker.setValue(null);

setOptions(options)

Merges a partial options object into the current options and applies it. Emits update. Changing calendar.mode empties the selection.

1picker.setOptions({ ui: { theme: "crane" } });
2
3picker.setOptions({ calendar: { mode: "range" } });

setActiveEnd(end)

Range mode only. Sets which end the next pick fills, "start" or "end". It is ignored in other modes and after destroy(), emits no event and does not open the picker.

1picker.open();
2picker.setActiveEnd("end");

getElement()

Returns the .dp-ui host element.

const host = picker.getElement();

on(event, handler)

Subscribes to an event and returns a function that unsubscribes.

1const off = picker.on("confirm", ({ value }) => {
2  console.log(value);
3});
4
5off();

once(event, handler)

Subscribes for one call and returns an unsubscribe function.

1picker.once("open", ({ mode }) => {
2  console.log(mode);
3});

off(event, handler?)

Unsubscribes one handler, or all handlers of the event when you pass none.

1picker.off("confirm", handler);
2
3picker.off("confirm");

From the first setActiveEnd() call on, a pick follows the active end, like it does with ui.endInput. When "end" is active and the range has a start, a date on or after the start sets the end. Any other pick makes that date a new start. After each pick the active end moves to the next end.

open() starts every docked or modal session at "start", so call setActiveEnd() after open().

1const picker = new DatepickerUI("#date", {
2  calendar: { mode: "range" },
3});
4picker.create();
5
6picker.open();
7picker.setActiveEnd("end");

DatepickerUI.getById(id)

Returns the instance created with behavior.id, or undefined.

1new DatepickerUI("#date", { behavior: { id: "trip-dates" } }).create();
2
3const picker = DatepickerUI.getById("trip-dates");

DatepickerUI.getAllInstances()

Returns every live instance.

const pickers = DatepickerUI.getAllInstances();

DatepickerUI.destroyAll()

Destroys every live instance.

DatepickerUI.destroyAll();

Events lists what on() can subscribe to, and TypeScript has the types of the values these methods take and return.