Reference
API Documentation
Complete API reference for every class, method, and utility.
NepaliDate
The core date manipulation object — immutable, chainable, inspired by Moment.js. All arithmetic methods return a new instance.
Construction
new NepaliDate(bsYear, bsMonth, bsDay)
Create a NepaliDate from BS year, month (1-indexed), and day. The instance is frozen (immutable).
NepaliDate.fromAD(jsDate)
Create a NepaliDate from a native JavaScript
Date object.Returns
NepaliDateNepaliDate.parse(str, formatStr = 'YYYY-MM-DD', locale = 'en')
Parse a formatted BS date string. Supports both English and Nepali numerals.
Returns
NepaliDateNepaliDate.today()
Returns today's date in Bikram Sambat.
Returns
NepaliDateNepaliDate.fromTimestamp(ms)
Create a NepaliDate from a Unix timestamp in milliseconds.
Returns
NepaliDateGetters
| Property | Type | Description |
|---|---|---|
.year | number | BS year |
.month | number | BS month (1-indexed, 1 = Baisakh) |
.day | number | BS day of month |
.weekDay | number | Day of week (0 = Sunday, 6 = Saturday) |
.quarter | number | Quarter (1–4) |
.dayOfYear | number | Day number within the BS year |
.weekOfYear | number | Week number within the BS year |
.daysInMonth | number | Total days in the current month |
.daysInYear | number | Total days in the current year |
.isLeapYear | boolean | True if the BS year has 366 days |
Conversion
.toAD()
Convert to a native JavaScript Date object in Gregorian calendar.
Returns
Date.toObject()
Returns a plain object with
year, month, day, and weekDay properties.Returns
{ year, month, day, weekDay }.toTimestamp()
Returns the equivalent Unix timestamp in milliseconds.
Returns
number.format(formatStr = 'YYYY-MM-DD', locale = 'en')
Format the date as a string. Tokens:
YYYY, MM, DD, MMMM, MMM, dddd, ddd.Returns
stringArithmetic
.add(value, unit) / .subtract(value, unit)
Add or subtract time. Units:
'day', 'week', 'month', 'year'. Returns a new instance.Returns
NepaliDate.startOf(unit) / .endOf(unit)
Get the first or last moment of the given unit. Units:
'month', 'year', 'week'.Returns
NepaliDate.addDays(n) / .addMonths(n) / .addYears(n)
Shorthand helpers for
.add(n, unit).Returns
NepaliDate.subtractDays(n) / .subtractMonths(n) / .subtractYears(n)
Shorthand helpers for
.subtract(n, unit).Returns
NepaliDateComparison
.isBefore(other) / .isAfter(other)
Compare two NepaliDate instances chronologically.
Returns
boolean.isSame(other, granularity = 'day')
Check equality at a given granularity:
'day', 'month', or 'year'.Returns
boolean.isBetween(start, end, inclusive = '[]')
Check if the date falls within a range. Inclusive modes:
'[]', '()', '[)', '(]'.Returns
boolean.isToday() / .isWeekend() / .isValid()
Convenience boolean checks.
isWeekend() returns true for Saturday (weekDay === 6).Returns
boolean.diff(other, unit = 'day')
Calculate the signed difference between two dates. Units:
'day', 'week', 'month', 'year'.Returns
numberCloning & Mutation
.clone()
Create an identical copy of this NepaliDate.
Returns
NepaliDate.set(field, value)
Return a new NepaliDate with the given field changed. Fields:
'year', 'month', 'day'. Day is clamped to valid range.Returns
NepaliDateCalendarEngine
A headless calendar state machine. Holds view state, selection, and disabled-date logic. Zero DOM or framework knowledge — adapters consume its state snapshots.
Constructor Options
| Option | Type | Description |
|---|---|---|
value | NepaliDate | Currently selected date |
defaultDate | NepaliDate | Date to show on first render |
minDate | NepaliDate | Earliest selectable date |
maxDate | NepaliDate | Latest selectable date |
locale | 'en' | 'np' | Display locale (default: 'en') |
weekStartsOn | number | First day of week (0 = Sun, default: 0) |
disabledDays | string[] | Weekday names to disable, e.g. ['Sat'] |
disabledDates | NepaliDate[] | Specific dates to disable |
onChange | Function | Called with NepaliDate on selection |
onMonthChange | Function | Called with { year, month } on navigation |
getState()
Returns a complete, serializable snapshot of the current UI state.
| Property | Type | Description |
|---|---|---|
viewYear | number | Currently displayed BS year |
viewMonth | number | Currently displayed BS month (1-indexed) |
viewMode | 'day' | 'month' | 'year' | Current view mode |
weeks | DayCell[][] | 6 rows × 7 cols of day cells |
months | MonthCell[] | 12 month items for month picker |
years | YearCell[] | ~12 items in current decade window |
selectedDate | NepaliDate | null | Currently selected date |
todayDate | NepaliDate | Today's BS date |
locale | 'en' | 'np' | Current locale |
canGoBack | boolean | Can navigate to previous month |
canGoForward | boolean | Can navigate to next month |
DayCell Shape
| Property | Type |
|---|---|
date | NepaliDate |
label | string — formatted day number |
isToday | boolean |
isSelected | boolean |
isDisabled | boolean |
isOutsideMonth | boolean |
weekDay | number |
Navigation Methods
.goToPrevMonth() / .goToNextMonth()
Navigate to the previous or next month. Respects min/max bounds.
.goToPrevYear() / .goToNextYear()
Navigate to the previous or next year.
.goToMonth(year, month)
Navigate directly to a specific year and month.
.goToToday()
Navigate to today's month.
.setViewMode(mode)
Switch between
'day', 'month', and 'year' views.Selection Methods
.selectDate(nepaliDate)
Select a date. Fires
onChange callback. Skips disabled dates..clearSelection()
Clear the currently selected date.
.setValue(nepaliDate)
Set the value programmatically. Does not fire
onChange.Subscriptions
.subscribe(listener)
Subscribe to state changes. The listener is called immediately with the current state, then on every subsequent change.
Returns
Function — unsubscribe callback.destroy()
Remove all subscriptions and clean up.
RangePicker
Extends CalendarEngine. Adds two-phase range selection with hover preview.
Additional Options
| Option | Type | Description |
|---|---|---|
startDate | NepaliDate | Initial range start |
endDate | NepaliDate | Initial range end |
minRange | number | Min days between start and end |
maxRange | number | Max days between start and end |
onRangeChange | Function | Called with { start, end } |
Additional State Properties
| Property | Type |
|---|---|
startDate | NepaliDate | null |
endDate | NepaliDate | null |
hoverDate | NepaliDate | null |
selectionPhase | 'idle' | 'start-selected' | 'complete' |
Each DayCell also includes: isRangeStart, isRangeEnd, isInRange, isRangeHover.
Methods
.selectDate(nepaliDate)
First click = range start, second click = range end. Validates min/max range constraints.
.hoverDate(nepaliDate)
Update the hover date for range preview (only active during
'start-selected' phase)..setRange(start, end)
Set the range programmatically. Fires
onRangeChange if both dates are set..clearRange()
Clear both start and end dates, reset to
'idle' phase..swapIfInverted()
Ensures start < end. Called automatically after range selection.
Vanilla JS Adapter
Renders the picker into a DOM container and wires events to the engine.
createPicker(container, options = {})
Mount a date picker into an
HTMLElement. If the container is an <input>, the picker wraps it automatically.Additional Options
| Option | Type | Description |
|---|---|---|
range | boolean | Use RangePicker instead of CalendarEngine |
inputSelector | string | CSS selector for an input to sync value to |
format | string | Date format string (default: 'YYYY-MM-DD') |
syncInput | boolean | Auto-update the input value on selection |
openOnInit | boolean | Show the panel immediately (default: false) |
Return Value
| Property | Type | Description |
|---|---|---|
engine | CalendarEngine | RangePicker | Direct engine reference |
destroy() | Function | Unmount and clean up all listeners |
open() | Function | Show the picker panel |
close() | Function | Hide the picker panel |
getValue() | Function | Get selected date or range { start, end } |
setValue() | Function | Set value programmatically |
React Adapter
Import from nepali-datepicker/react.
useNepaliDatePicker(options = {})
Headless hook — wraps the CalendarEngine and returns reactive state + bound action handlers.
Return Value
| Property | Description |
|---|---|
state | Reactive getState() snapshot |
engine | Direct engine reference |
goToPrevMonth | Bound action |
goToNextMonth | Bound action |
goToPrevYear | Bound action |
goToNextYear | Bound action |
goToToday | Bound action |
setViewMode | Bound action |
selectDate | Bound action |
clearSelection | Bound action |
hoverDate | Bound action (range mode) |
setRange | Bound action (range mode) |
clearRange | Bound action (range mode) |
<NepaliDatePicker options={...} children={renderFn} />
Render-prop component. Passes the same object as
useNepaliDatePicker to the children render function.Vue 3 Adapter
Import from nepali-datepicker/vue.
useNepaliDatePicker(options = {})
Vue 3 composable. Wraps CalendarEngine with reactive
ref state. Returns the same interface as the React adapter.Returns
{ state: Ref, engine, ...actions }Svelte Adapter
Import from nepali-datepicker/svelte.
createNepaliPickerStore(options = {})
Returns a Svelte-compatible readable store. Use
$store syntax to access state reactively.Returns
{ subscribe, engine, ...actions }Locale & Formatting
Two built-in locales: English ('en') and Nepali Devanagari ('np').
formatDate(nepaliDate, formatStr, locale = 'en')
Format a NepaliDate to a string. Tokens:
YYYY, MM, DD, MMMM (full month), MMM (short month), dddd (full weekday), ddd (short weekday).Returns
stringparseDate(str, formatStr, locale = 'en')
Parse a formatted BS date string back into a NepaliDate. Supports both English and Nepali numerals.
Returns
NepaliDateLOCALES
Object containing
en and np locale data: months, days, daysLong, today, clear, numberFormat(n).Nepali Month Names
| # | English | Nepali |
|---|---|---|
| 1 | Baisakh | बैशाख |
| 2 | Jestha | जेठ |
| 3 | Ashadh | असार |
| 4 | Shrawan | श्रावण |
| 5 | Bhadra | भाद्र |
| 6 | Ashwin | आश्विन |
| 7 | Kartik | कार्तिक |
| 8 | Mangsir | मंसिर |
| 9 | Poush | पुष |
| 10 | Magh | माघ |
| 11 | Falgun | फाल्गुण |
| 12 | Chaitra | चैत्र |
Converter
Bidirectional conversion between Bikram Sambat and Gregorian dates.
Epoch anchor: 1 Baisakh 2000 BS = April 14, 1943 AD.
adToBS(adYear, adMonth, adDay)
Convert a Gregorian date to Bikram Sambat. Month is 1-indexed.
Returns
{ year, month, day }bsToAD(bsYear, bsMonth, bsDay)
Convert a Bikram Sambat date to Gregorian. Month is 1-indexed.
Returns
{ year, month, day }BS_CALENDAR_DATA
The raw lookup table:
{ [bsYear]: number[12] }. Each array contains the number of days in each month for that year. Range: 2000–2100 BS.Styling
The optional Material stylesheet uses CSS custom properties for full theming control.
Import: import 'nepali-datepicker/dist/material.css'
CSS Custom Properties
| Variable | Default | Description |
|---|---|---|
--ndp-primary | #1976D2 | Primary accent color |
--ndp-primary-dark | #115293 | Darker primary |
--ndp-primary-light | #E3F2FD | Light primary (range bg) |
--ndp-surface | #FFFFFF | Panel background |
--ndp-on-surface | #212121 | Text on surface |
--ndp-on-surface-muted | #757575 | Muted text |
--ndp-radius-md | 8px | Panel border radius |
--ndp-cell-size | 36px | Day cell size |
--ndp-width | 280px | Panel width |
--ndp-font | 'Roboto' | Font family |
--ndp-font-np | 'Noto Sans Devanagari' | Nepali font |
--ndp-transition | 150ms ease | Transition timing |
Component Classes
| Class | Description |
|---|---|
.ndp-container | Outer wrapper |
.ndp-panel | Floating calendar panel |
.ndp-header | Month/year navigation row |
.ndp-grid | 7-column CSS grid for day cells |
.ndp-cell | Individual day cell |
.ndp-cell--today | Today's date indicator |
.ndp-cell--selected | Selected date (filled) |
.ndp-cell--disabled | Disabled cell |
.ndp-cell--range-start | Range start |
.ndp-cell--range-end | Range end |
.ndp-cell--in-range | Days within the selected range |
.ndp-footer | Bottom action bar |
.ndp-input | Input trigger styling |