Documentation · itzsa

Nepali Bikram Sambat Datepicker — @itzsa/nepali-datepicker

Production-ready Bikram Sambat pickers for React: calendar select, typeable YYYY-MM-DD input, and dual-month range — with AD ↔ BS conversion, validation helpers, and theme tokens via props.

@itzsa/nepali-datepickeruses @itzsa/bs-datesingle · editable · datetime · rangeBS 1970–2100

Installation#

Install with your package manager, then import styles once in the app.

pnpm add @itzsa/nepali-datepicker

Global CSS (Tailwind v4):

@import "tailwindcss";
@source "../node_modules/@itzsa/nepali-datepicker";
@import "@itzsa/nepali-datepicker/styles.css";

:root {
  --itzsa-nepali-font: "Noto Sans Devanagari", sans-serif;
}

Peers

Peer deps: react and react-dom ^18 or ^19. Load a Devanagari font for Nepali labels.

Getting started#

Canonical values are always ASCII YYYY-MM-DD (BS). Display locale is separate from the stored value.

import { useState } from "react";
import {
  EditableNepaliDatePicker,
  NepaliDatePicker,
  NepaliDateTimePicker,
  NepaliDateRangePicker,
  isCompleteBsDate,
} from "@itzsa/nepali-datepicker";
import "@itzsa/nepali-datepicker/styles.css";

export function DateFields() {
  const [date, setDate] = useState("");
  const [typed, setTyped] = useState("");
  const [dateTime, setDateTime] = useState("");
  const [range, setRange] = useState<{ from?: string; to?: string }>({});

  return (
    <>
      <NepaliDatePicker value={date} onChange={setDate} locale="ne" />
      <EditableNepaliDatePicker value={typed} onChange={setTyped} />
      <NepaliDateTimePicker
        value={dateTime}
        onChange={setDateTime}
        minDateTime="2080-01-01 00:00"
        maxDateTime="2090-12-30 23:59"
      />
      <NepaliDateRangePicker value={range} onChange={setRange} />
    </>
  );
}

vs jQuery NepaliDatePicker

You do not need to port that plugin’s compressed month codec or special-case patches. This package uses explicit BS month-length tables (1970–2100) plus validateBsDate / minDate / maxDate — same job, clearer API.

Validation#

Use soft checks in forms; assert helpers throw TypeError / RangeError when you need hard guards.

import {
  isCompleteBsDate,
  parseDateString,
  validateBsDate,
  assertValidBsDate,
} from "@itzsa/nepali-datepicker";

// Soft (forms)
const result = validateBsDate(2082, 1, 32);
// → { ok: false, code: "invalid_date", message: "…" }

if (!isCompleteBsDate(value)) {
  // still typing or bad calendar day
}

// Hard (throw)
assertValidBsDate(2082, 4, 15);

const parts = parseDateString("2082-04-15"); // null if invalid

What we validate

Integer year/month/day, year in 1970–2100, month 1–12, day within that month’s length. Incomplete typed strings fail isCompleteBsDate until the user finishes a real calendar day.

Examples#

Interactive demos — Preview for the UI, Code for the full snippet (copy upper right).

Basic picker#

Read-only field with Nepali label — open calendar to pick.

BS: 2083-04-24 · AD: 2026-08-09

Editable input#

Type digits (auto-masked to YYYY-MM-DD) or open the calendar.

value: · valid: no

Date & time#

Pick a BS date plus every minute (minuteStep={1}). Preview uses Nepali live-clock style.

value: 2083-04-24 08:56

Bounds: 2080-01-01 00:00 2090-12-30 23:59

Live Nepali clock#

Show the current BS date/time in configurable formats (two-line, dmyw, time-only, with/without वि सं).

नेपाली समय ०८ : ५६ : ४५ पूर्वाह्न

वि सं २०८३ श्रावण २४ आइतवार

Live BS clock — ticks every second. Swap format for the presets above (two-line, dmyw, time-only, …).

Date range#

Click start, then end. Hover previews the span; dual months on desktop.

from: 2083-04-24 · to: 2083-04-31

Custom styling#

Theme with vars (CSS tokens) and classNames (per-part Tailwind / CSS).

Themed via vars + classNames.

Locale#

Switch calendar and labels between ne and en.

Label: 1 Baisakh 2082

Min / max#

Limit selectable days and years.

Selectable range: 2082-01-01 2082-12-30

value: 2082-04-15

AD ↔ BS helpers#

Pick BS or type AD — conversion is powered by @itzsa/bs-date.

Pick a BS date — conversion uses @itzsa/bs-date under the hood. Flip AD → BS below.

AD 2026-08-09

BS 2083-04-24 ·

Round-trip check: OK

Props API#

Canonical date strings are always ASCII YYYY-MM-DD (BS).

NepaliDatePicker#

Human-readable display; calendar selection only.

NepaliDatePickerProps

PropTypeDefaultDescription
valuestring-Controlled BS date as ASCII YYYY-MM-DD. Empty string = no selection.
defaultValuestring""Uncontrolled initial BS date.
onChange(value: string) => void-Fires with canonical YYYY-MM-DD (or "" when cleared).
onSelect(value: string) => void-Fires when a day is chosen (also on Today / Clear).
locale'ne' | 'en''ne'Calendar month/weekday names and day digits.
valueLocale'ne' | 'en'-Input display locale. Defaults to locale.
minDate / maxDatestring-Inclusive selectable range as YYYY-MM-DD (BS).
minYear / maxYearnumber1970 / 2100Year picker bounds within supported calendar data.
closeOnSelectbooleantrueClose the popover after picking a day.
todayIfEmptybooleantrueOpen on today’s month when value is empty.
disabled / readOnlybooleanfalseDisable interaction or prevent opening.
className / inputClassName / popoverClassNamestring-Style hooks for root, input, and popover.
classNamesNepaliDatePickerClassNames-Per-part classes: root, field, input, trigger, popover, day, footer.
varsNepaliDatePickerVars-Theme tokens: accent, background, border, surface, radius, font, …
style / popoverStyleCSSProperties-Inline styles merged with vars on root / popover.

EditableNepaliDatePicker#

Typeable masked input + calendar. Validate with isCompleteBsDate.

EditableNepaliDatePickerProps

PropTypeDefaultDescription
valuestring-Controlled string — may be partial while typing (e.g. 2082-04).
onChange(value: string) => void-Fires on each keystroke (masked) and on calendar pick.
locale'ne' | 'en''en'Calendar UI locale (input stays ASCII YYYY-MM-DD).
minDate / maxDate / minYear / maxYear-Same bounds as NepaliDatePicker.
placeholderstring'YYYY-MM-DD'Shown when the field is empty.
classNames / vars / style-Same styling API as NepaliDatePicker.

NepaliDateTimePicker#

Value is YYYY-MM-DD HH:mm. Confirm applies date + time together. Default minuteStep is 1.

NepaliDateTimePickerProps

PropTypeDefaultDescription
valuestring-Controlled BS datetime as ASCII YYYY-MM-DD HH:mm.
onChange(value: string) => void-Fires on Confirm (canonical datetime string).
minDateTime / maxDateTimestring-Inclusive bounds. Date-only (YYYY-MM-DD) = start/end of that day; or full YYYY-MM-DD HH:mm.
minDate / maxDatestring-Aliases of minDateTime / maxDateTime.
minuteStepnumber1Minute list increment (1 = every minute; also 5 / 15 / 30).
withSecondsbooleanfalseShow seconds column and include :ss in the value.
displayFormatNepaliDateTimeDisplayFormat | "compact"time-date-single-no-bs (ne)How the closed input renders the selection (Nepali live-clock presets or compact).
placeholderstring-Empty-state label.
classNames / vars / style-Same styling API as NepaliDatePicker.

NepaliLiveClock#

Live or controlled Nepali BS date/time display with format presets.

NepaliLiveClockProps

PropTypeDefaultDescription
formatNepaliDateTimeDisplayFormattime-date-two-linePreset: time-date-two-line(-seconds), time-date-single(-no-bs), time-only, date-only(-no-bs), dmyw, time-date-bare.
locale"ne" | "en"neMonth/weekday/period labels and Devanagari digits.
valueDateTimeParts-Controlled parts. Omit to track the live clock.
tickMsnumber1000Live update interval. 0 freezes after first paint.
hour12 / withSeconds / timePrefix / bsPrefix / periodLabels-Fine-grained display overrides (see formatNepaliDateTimeDisplay).

NepaliDateRangePicker#

from / to as YYYY-MM-DD. Duration shown in the footer.

NepaliDateRangePickerProps

PropTypeDefaultDescription
value{ from?: string; to?: string }-Controlled BS range (ASCII YYYY-MM-DD each).
onChange(range) => void-Fires as the user selects start / end.
numberOfMonths1 | 22Show one or two months side by side.
locale / valueLocale'ne' | 'en''ne'Calendar and trigger label locales.
minDate / maxDatestring-Inclusive selectable bounds.
closeOnSelectbooleantrueClose after both ends are chosen.
classNames / vars / style-Styling API plus rangeTrigger, rangeLabel, rangeMonths in classNames.

Helpers#

Tree-shakeable utilities from the same package entry.

Conversion, format & validation

PropTypeDefaultDescription
bsToAd(y, m, d)DateParts-Convert BS → AD civil date parts (via @itzsa/bs-date).
adToBs(y, m, d)DateParts-Convert AD → BS date parts (via @itzsa/bs-date).
todayBs()DateParts-Today in BS (local civil date).
parseDateString / toDateString-Parse/format ASCII YYYY-MM-DD BS strings.
formatTypedBsDate / isCompleteBsDate-Mask typing and validate a complete BS date.
diffBsDays / addBsDays-Day arithmetic across the BS calendar (@itzsa/bs-date).
validateBsDate / assertValidBsDateValidationResult | void-Soft or hard validation (year/month/day range + calendar-valid).
isValidBsDate / isCompleteBsDateboolean-Quick checks for parts or YYYY-MM-DD strings.
formatBsLabel(parts, locale)string-Human label, e.g. १५ माघ २०८२.

Styling & fonts#

Three layers: CSS import tokens, vars prop, and classNames / className.

.itzsa-ndp {
  --ndp-accent: #1d9e75;
  --ndp-border: #e4e2db;
  --ndp-radius: 10px;
  --itzsa-nepali-font: "Noto Sans Devanagari", sans-serif;
}

vars maps to the same CSS variables at runtime. classNames targets root, field, input, trigger, popover (and range-specific keys on the range picker).

Calendar data range

Tables cover BS 1970–2100. Outside that range, conversion helpers throw RangeError.

Source: packages/nepali-datepicker