Skip to content

Introduction ​

What is nepdate? ​

nepdate is a set of JavaScript packages for working with Bikram Sambat (BS), the official calendar of Nepal, alongside the Gregorian calendar (AD). It has two parts:

  • A date engine. @nepdatejs/core converts between BS and AD, formats and parses dates in English and Nepali, does date arithmetic, and knows Nepal's fiscal year. It depends on no other package and runs anywhere JavaScript runs.
  • A calendar and date pickers. Ready-made components for React and for plain HTML (Web Components), so they also work in Vue, Svelte, Angular and Laravel Blade.
ts
import { adDate, adToBs, formatDate } from '@nepdatejs/core';

const bs = adToBs(adDate(2026, 10, 18));

formatDate(bs, 'long'); // → '1 Kartik 2083'
formatDate(bs, 'long', 'ne'); // → '१ कार्तिक २०८३'

Why a library for this? ​

BS looks simple, but three things make it easy to get wrong:

  • Month lengths can't be calculated. A BS month has 29 to 32 days, and the lengths change from year to year. They are decided by astronomical observation and published in calendars, so software has to use a table.
  • A BS year spans two AD years. BS 2083 runs from April 2026 to April 2027. Code that looks things up by year number across the two calendars gives subtly wrong answers around the new year.
  • It is easy to store the wrong thing. If a BS date lands in a database column that expects AD, nothing fails. The record is just wrong, years in the future.

nepdate is designed around these problems. See How it works for the details.

What you get ​

You want toUse
Convert, format or calculate dates@nepdatejs/core
Add a date picker in React@nepdatejs/react
Add a date picker in HTML, Vue, Svelte, Angular or Blade@nepdatejs/vanilla
Show Nepal's national holidays@nepdatejs/holidays
Change how the components look@nepdatejs/styles
Build your own picker UI@nepdatejs/calendar and @nepdatejs/datepicker

The packages ​

PackageWhat it doesDepends on
@nepdatejs/coreConversion, formatting, parsing, arithmetic, fiscal year, timeNothing
@nepdatejs/calendarCalendar logic with no UI: grids, keyboard moves, day statescore
@nepdatejs/datepickerPicker logic with no UI: typed text, validation, BS/AD switchcore, calendar
@nepdatejs/reactReact components and hookscalendar, datepicker, dom
@nepdatejs/vanillaWeb Components and a plain JavaScript APIcalendar, datepicker, dom
@nepdatejs/stylesThe stylesheet, with light and dark themesNothing
@nepdatejs/holidaysNational holidays and a loader for yearly listscore
@nepdatejs/domSmall browser helpers the components shareNothing

You only install what you need. Most apps install one of @nepdatejs/react or @nepdatejs/vanilla, plus @nepdatejs/styles.

Size ​

@nepdatejs/core is under 8 kB gzipped if you bundle all of it, and bundlers keep only what you import: a page that only uses adToBs ships about 2 kB. CI fails if a package grows past its budget.

ImportGzipped
{ adToBs } from @nepdatejs/coreAbout 2 kB
All of @nepdatejs/coreUnder 8 kB
One Web Component, such as @nepdatejs/vanilla/date-pickerAbout 7 kB, plus core and the stylesheet
All the Web Components as one <script> fileAbout 25 kB, including core

Browser and runtime support ​

  • Node: 18 or newer, in ESM or CommonJS.
  • Browsers: current versions of Chrome, Edge, Firefox and Safari. Panels use the browser's top layer where it is available, and fall back to fixed positioning.
  • React: 18 and 19, including server rendering and Server Components.
  • TypeScript: full types are included. No @types package is needed.

Next steps ​

Released under the MIT licence.