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/coreconverts 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 to | Use |
|---|---|
| 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
| Package | What it does | Depends on |
|---|---|---|
@nepdatejs/core | Conversion, formatting, parsing, arithmetic, fiscal year, time | Nothing |
@nepdatejs/calendar | Calendar logic with no UI: grids, keyboard moves, day states | core |
@nepdatejs/datepicker | Picker logic with no UI: typed text, validation, BS/AD switch | core, calendar |
@nepdatejs/react | React components and hooks | calendar, datepicker, dom |
@nepdatejs/vanilla | Web Components and a plain JavaScript API | calendar, datepicker, dom |
@nepdatejs/styles | The stylesheet, with light and dark themes | Nothing |
@nepdatejs/holidays | National holidays and a loader for yearly lists | core |
@nepdatejs/dom | Small browser helpers the components share | Nothing |
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.
| Import | Gzipped |
|---|---|
{ adToBs } from @nepdatejs/core | About 2 kB |
All of @nepdatejs/core | Under 8 kB |
One Web Component, such as @nepdatejs/vanilla/date-picker | About 7 kB, plus core and the stylesheet |
All the Web Components as one <script> file | About 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
@typespackage is needed.
Next steps
- Installation: add nepdate to your project.
- Quick start: a working date and a working picker in five minutes.
- Converter: try a conversion right now.