API reference

DateValue

Litopis represents a calendar date without a time or time zone. Months and days are one-based; supported years are 1 through 9999.

interface DateValue {
  readonly day: number;
  readonly month: number;
  readonly year: number;
}

DateValue is the default public value. Use valueAs: "date" when the application works with native Date instances.

A valid value has year: 1…9999, month: 1…12 and a day valid for that month; for example { year: 2026, month: 7, day: 29 }.

interface DateRange {
  readonly start: DateValue | null;
  readonly end: DateValue | null;
}

Value output

The calendar keeps date-only values internally. The controller can expose the same selection in the form that fits the consuming code.

const picker = createDatePicker(root, {
  format: "dd.mm.yyyy",
  valueAs: "date",
});

picker.getValue();          // Date | null
picker.getInputValue();     // "29.02.2024"
picker.getISOValue();       // "2024-02-29"

getInputValue() is the exact value shown in the field, including the range separator. getISOValue() is always an ISO value for forms and storage. With valueAs: "date", selected, range, setDate() and setRange() also accept local Date instances. Litopis reads their local year, month and day and returns local-noon Date instances so a calendar day is not shifted at a daylight-saving transition.

selection and valueAs determine the return type together. Pass literals directly, or preserve them with satisfies when options are stored first.

import {
  createDatePicker,
  type DatePickerOptions,
  type DatePickerRange,
  type DateValue,
} from "@litopis/dom";

const dateValuePicker = createDatePicker(root);
const dateValue: DateValue | null = dateValuePicker.getValue();

const nativeDatePicker = createDatePicker(root, { valueAs: "date" });
const nativeDate: Date | null = nativeDatePicker.getValue();

const rangeOptions = {
  selection: "range",
  valueAs: "date",
} satisfies DatePickerOptions<"date", "range">;

const rangePicker = createDatePicker(root, rangeOptions);
const range: DatePickerRange<"date"> = rangePicker.getValue();

Period boundaries

Month and year selections represent complete periods in values sent to an application or a form. Field text remains at the selected precision.

For example, selecting February through March 2024 yields 2024-02-01/2024-03-31 from getISOValue(), while a field with format: "dd.mm.yyyy" displays 02.2024 – 03.2024.

createDatePicker

Mounts a date field and calendar into an existing element.

function createDatePicker(
  root: HTMLElement,
  options?: DatePickerOptions,
): DatePickerController;

DatePickerOptions

Literal unions below are the complete set of accepted variants. Text options accept user-facing text; locale accepts a supported BCP 47 tag such as "uk-UA".

DatePickerController

createDateField

Mounts only the masked text field. It is useful when the application provides its own calendar surface or needs typed date entry without a picker.

const field = createDateField(root, {
  format: "dd.mm.yyyy",
  label: "Invoice date",
  min: { day: 1, month: 1, year: 2026 },
});

field.getDate();
field.getISOValue();
field.isValid();
field.setDate({ day: 16, month: 7, year: 2026 });
field.destroy();

DateFieldOptions

Core exports

@litopis/core has no DOM dependency and can be used for custom renderers, server-side validation and deterministic calendar calculations.