Skip to content

@nepdatejs/datepicker ​

Picker logic with no UI. See Framework-free stores for how to use it.

ts
import { createDatePicker } from '@nepdatejs/datepicker';

Stores ​

FunctionPicks
createDatePicker(options?)One day
createDateRangePicker(options?)A start and an end
createDateTimePicker(options?)A day and a time
createMultiDatePicker(options?)Several days

Each returns a store with getState(), subscribe(listener), setOptions(changes), actions, calendar (the panel's calendar store) and destroy().

Options ​

Shared by all pickers ​

OptionTypeDefaultMeaning
calendar'BS' | 'AD'Fix the calendar
defaultCalendar'BS' | 'AD''BS'The calendar shown first
onCalendarChange(calendar) => voidCalled on a switch
min, maxstringAD YYYY-MM-DD
isDateDisabled(date) => booleanRule out days
localestringconfiguredNames, digits, messages
displayFormatstring'iso'How the input shows a date
closeOnSelectbooleantrueClose after a pick
inlinebooleanfalseAlways open, in the page
maskbooleantrueAdd dashes while typing
holidays, eventsPassed to the calendar
showOtherCalendarbooleantrue
weekStartsOn, weekendDaysconfigured
todayCalendarDatereal todayOverride, for tests

createDatePicker ​

OptionTypeMeaning
value, defaultValuestringAD YYYY-MM-DD
onChange(value, detail) => voiddetail is { ad, bs } or null
presetsSinglePreset[]Shortcuts

createDateRangePicker ​

OptionTypeMeaning
value, defaultValueRangeValue{ start, end }
onChange(value, detail) => voiddetail is RangeDetail
minDays, maxDaysnumberCounting both ends
presetsRangePreset[]Shortcuts

createDateTimePicker ​

OptionTypeDefaultMeaning
value, defaultValuestringAn ISO timestamp
onChange(value, detail) => voiddetail is DateTimeDetail or null
timeZonestringconfiguredThe zone shown and stored
hour12booleanfalse12-hour display
minuteStepnumber51 to 30
defaultTimestring'00:00'Used when a day is picked first
presetsSinglePreset[]Shortcuts

createMultiDatePicker ​

OptionTypeMeaning
value, defaultValuereadonly string[]AD days
onChange(value, dates) => voiddates is DateDetail[]
maxDatesnumberThe most days allowed

displayFormat isn't used here, and closeOnSelect defaults to false.

State ​

FieldPickersContents
valueAllThe value, always AD
dateDate, range{ ad, bs }, or { start, end } of those
datesMultipleA list of { ad, bs }
detailDate and time{ ad, bs, time, iso } or null
textDate, multipleWhat the input shows
startText, endTextRangeWhat the inputs show
dateText, timeText, timeDate and timeThe two inputs and the parsed time
calendar, canSwitchCalendarAllThe calendar on screen
open, inlineAllPanel state
errorAll{ code, message } or null. In range and date and time, also field
equivalentTextDate, range, date and timeThe same day in the other calendar
placeholderAll"YYYY-MM-DD (BS)"
timePlaceholder, hours, minutesDate and timeThe time column
presetsDate, range, date and timeA list of PresetState
calendarStateAllThe panel's calendar state

Actions ​

ActionPickersDoes
type(text)Date, multipleThe user typed
type(field, text)RangeThe user typed in 'start' or 'end'
typeDate(text), typeTime(text)Date and time
blur()Date, multipleTidy the text
blur(field)Range
blurDate(), blurTime()Date and time
select(date)Date, range, multiplePick a day. In multiple, a second pick removes it
selectDate(date)Date and time
selectHour(hour), selectMinute(minute)Date and time
selectNow()Date and timeToday and the current time
selectToday()Date
remove(value)MultipleRemove one day
clear()All
setValue(value)AllFrom outside. Doesn't call onChange
reset()AllBack to defaultValue
open(), close(), toggle()AllPanel
switchCalendar(calendar)AllThe value doesn't change
applyPreset(id)Date, range, date and timeReturns false if disabled or unknown

The value contract ​

  • The value is always AD, and '' when empty or invalid.
  • onChange is called for user actions only: typing, picking, clear and reset.
  • setValue and setOptions({ value }) never call it.
  • Passing back the value the user just typed leaves their text alone, so the cursor doesn't jump.

Helpers ​

FunctionDoes
parseInput(text, calendar, limits, locale, format?)Read typed text. Returns a ParseResult
checkDate(date, calendar, limits, locale, format?)The error for a date, or null
formatInput(date, calendar, format, locale)The text for an input
equivalentText(date, calendar, locale)"10 October 2026 AD"
placeholderText(calendar, locale)"YYYY-MM-DD (BS)"
maskDateText(next, previous?)Add dashes
resolveSinglePreset(id, context), resolveRangePreset(id, context)What a built-in shortcut stands for

Types ​

DatePickerOptions, DatePickerState, DatePickerActions, DatePickerStore, DateRangePickerOptions, DateRangePickerState, DateRangePickerActions, DateRangePickerStore, DateTimePickerOptions, DateTimePickerState, DateTimePickerActions, DateTimePickerStore, MultiDatePickerOptions, MultiDatePickerState, MultiDatePickerActions, MultiDatePickerStore, PickerBaseOptions, DateDetail, DateTimeDetail, RangeDetail, RangeField, RangeValue, DateError, DateErrorCode, TimeCell, InputLimits, ParseResult, CustomPreset, PresetContext, PresetRange, PresetState, RangePreset, RangePresetId, SinglePreset, SinglePresetId.

Released under the MIT licence.