Skip to content

@nepdatejs/calendar ​

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

ts
import { createCalendar } from '@nepdatejs/calendar';

createCalendar ​

createCalendar(options?) returns a store:

MemberDoes
getState()The current state. The same object until something changes
subscribe(listener)Returns a function that stops listening
setOptions(changes)Change options. selected and visibleMonth here act as controlled values
actionsSee Actions
destroy()Stop everything

Options ​

OptionTypeDefaultMeaning
calendar'BS' | 'AD''BS'The calendar shown
localestringconfiguredNames and digits
selectionMode'single' | 'range' | 'multiple''single'How clicks select
selecteddate, range or listThe selection
defaultVisibleMonthCalendarDateselected or todayThe month shown first
visibleMonthCalendarDateControl the month
min, maxCalendarDatetable limitsSelectable range
isDateDisabled(date) => booleanRule out days
holidayslist or functionSee Holidays and events
events(date) => EventMarker[]Markers for a day
showOtherCalendarbooleantrueOther calendar's day number
showOutsideDaysbooleantrueDays of nearby months
fixedWeeksbooleanfalseAlways six rows
weekStartsOnWeekdayconfiguredFirst day of the week
weekendDaysWeekday[]configuredWeekend days
todayCalendarDatereal todayOverride, for tests
onSelect(selection) => voidCalled on a selection
onVisibleMonthChange(month) => voidCalled when the month changes
onViewChange(view) => voidCalled when the view changes

State ​

FieldContents
calendarThe calendar shown
view'day', 'month', 'year' or 'fiscal'
visibleMonthDay 1 of the month on screen
focusedThe day with keyboard focus
title"Kartik 2083", "2083" or "2076–2087"
weekdaysA list of { index, label, narrowLabel, longLabel, isWeekend }
weeksRows of seven DayCell | null. null is an empty cell
months, years, fiscalYearsLists of PickerCell tiles
canPrev, canNextWhether the view can move
selectionMode, selectedThe selection
rangeHoverThe hovered day while choosing a range end
minDate, maxDateFirst and last selectable days

DayCell ​

FieldContents
keyA stable key, such as "BS-2083-06-24"
date, otherDateThe day in each calendar
epoch, weekdayIts epoch day and weekday
label, subLabelDay numbers in the locale's digits
ariaLabel"Sunday, 1 Kartik 2083 (18 October 2026 AD)", plus any holiday
isToday, isSelected, isDisabled, isOutside, isWeekendFlags
isRangeStart, isRangeMiddle, isRangeEnd, isInRangePreviewRange flags
isHoliday, holidayLabelHoliday information
eventsThe day's markers
isFocusTargetPut tabindex="0" on this one cell
stateOne word for styling: DayState

PickerCell ​

FieldContents
valueThe month number, the year, or the fiscal start year
label"Ashwin" or "2083"
subLabelThe other calendar's span, such as "Sep / Oct"
isSelected, isCurrent, isDisabledFlags

Actions ​

ActionDoes
next(), prev()Move by a month, a year or a page, depending on the view
goTo(date), goToToday()Show a date's month
setView(view)Switch view
chooseMonth(month), chooseYear(year)Drill down through the views
chooseFiscalYear(startYear)In range mode, select that fiscal year. Returns false if outside the limits
focus(date)Move keyboard focus
moveFocus(key, { shift })Arrows, Home, End, PageUp, PageDown. Never throws at the limits
select(date)Returns false for a disabled day
hover(date | null)Range preview

Pure helpers ​

FunctionDoes
buildMonthGrid(input), buildWeekdays(locale, weekStartsOn, weekendDays)Build a month
buildMonthTiles(input), buildYearTiles(input)Build tiles
yearPageStart(year)The first year on a page of twelve
nextFocus(focused, key, limits, options)The day a key moves to
computeLimits(calendar, min, max), isInLimits(date, limits)Work out limits
isDayList(selection)Whether a selection is a list of days

Types ​

CalendarOptions, CalendarState, CalendarStore, CalendarActions, CalendarView, CalendarSelection, SelectionMode, DateRange, DayCell, DayState, WeekdayCell, PickerCell, EventMarker, HolidayInfo, HolidayInput, HolidayLookup, FocusKey, GridInput, TileInput, HolidayResolver, Limits.

Released under the MIT licence.