Documentation · itzsa
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.
Installation#
Install with your package manager, then import styles once in the app.
pnpm add @itzsa/nepali-datepickerGlobal 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 (2000–2100) plusvalidateBsDate / 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 invalidWhat we validate
Integer year/month/day, year in 2000–2100, month 1–12, day within that month’s length. Incomplete typed strings failisCompleteBsDate until the user finishes a real calendar day.Examples#
Interactive demos for each picker variant.
Basic picker#
Read-only field with Nepali label — open calendar to pick.
value: 2083-04-03
Editable input#
Type digits (auto-masked to YYYY-MM-DD) or open the calendar.
value: — · valid: no
Date & time#
Pick a BS date plus hour/minute. Use minDateTime / maxDateTime for bounds.
value: 2083-04-03 12:46
Bounds: 2080-01-01 00:00 → 2090-12-30 23:59
Date range#
Click start, then end. Hover previews the span; dual months on desktop.
from: 2083-04-03 · to: 2083-04-10
Custom styling#
Theme with vars (CSS tokens) and classNames (per-part Tailwind / CSS).
Themed via vars + classNames.
<NepaliDatePicker
value={date}
onChange={setDate}
vars={{
accent: "#0f766e",
radius: "12px",
border: "#99f6e4",
surface: "#f0fdfa",
}}
classNames={{
input: "h-10 font-medium",
popover: "shadow-lg",
}}
/>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#
Pure functions for conversion outside React.
todayBs(): 2083-4-3
→ AD: 2026-7-19
→ BS again: 2083-4-3
import { adToBs, bsToAd, todayBs } from "@itzsa/nepali-datepicker";
const today = todayBs();
const ad = bsToAd(today.year, today.month, today.day);
const bs = adToBs(ad.year, ad.month, ad.day);Props API#
Canonical date strings are always ASCII YYYY-MM-DD (BS).
NepaliDatePicker#
Human-readable display; calendar selection only.
NepaliDatePickerProps
| Prop | Type | Default | Description |
|---|---|---|---|
| value | string | — | Controlled BS date as ASCII YYYY-MM-DD. Empty string = no selection. |
| defaultValue | string | "" | 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 / maxDate | string | — | Inclusive selectable range as YYYY-MM-DD (BS). |
| minYear / maxYear | number | 2000 / 2100 | Year picker bounds within supported calendar data. |
| closeOnSelect | boolean | true | Close the popover after picking a day. |
| todayIfEmpty | boolean | true | Open on today’s month when value is empty. |
| disabled / readOnly | boolean | false | Disable interaction or prevent opening. |
| className / inputClassName / popoverClassName | string | — | Style hooks for root, input, and popover. |
| classNames | NepaliDatePickerClassNames | — | Per-part classes: root, field, input, trigger, popover, day, footer. |
| vars | NepaliDatePickerVars | — | Theme tokens: accent, background, border, surface, radius, font, … |
| style / popoverStyle | CSSProperties | — | Inline styles merged with vars on root / popover. |
EditableNepaliDatePicker#
Typeable masked input + calendar. Validate with isCompleteBsDate.
EditableNepaliDatePickerProps
| Prop | Type | Default | Description |
|---|---|---|---|
| value | string | — | 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. |
| placeholder | string | '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.
NepaliDateTimePickerProps
| Prop | Type | Default | Description |
|---|---|---|---|
| value | string | — | Controlled BS datetime as ASCII YYYY-MM-DD HH:mm. |
| onChange | (value: string) => void | — | Fires on Confirm (canonical datetime string). |
| minDateTime / maxDateTime | string | — | Inclusive bounds. Date-only (YYYY-MM-DD) = start/end of that day; or full YYYY-MM-DD HH:mm. |
| minDate / maxDate | string | — | Aliases of minDateTime / maxDateTime. |
| minuteStep | number | 5 | Minute list increment (1–30). |
| withSeconds | boolean | false | Show seconds column and include :ss in the value. |
| placeholder | string | — | Empty-state label. |
| classNames / vars / style | … | — | Same styling API as NepaliDatePicker. |
NepaliDateRangePicker#
from / to as YYYY-MM-DD. Duration shown in the footer.
NepaliDateRangePickerProps
| Prop | Type | Default | Description |
|---|---|---|---|
| value | { from?: string; to?: string } | — | Controlled BS range (ASCII YYYY-MM-DD each). |
| onChange | (range) => void | — | Fires as the user selects start / end. |
| numberOfMonths | 1 | 2 | 2 | Show one or two months side by side. |
| locale / valueLocale | 'ne' | 'en' | 'ne' | Calendar and trigger label locales. |
| minDate / maxDate | string | — | Inclusive selectable bounds. |
| closeOnSelect | boolean | true | Close 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
| Prop | Type | Default | Description |
|---|---|---|---|
| bsToAd(y, m, d) | DateParts | — | Convert BS → AD civil date parts. |
| adToBs(y, m, d) | DateParts | — | Convert AD → BS date parts. |
| 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. |
| validateBsDate / assertValidBsDate | ValidationResult | void | — | Soft or hard validation (year/month/day range + calendar-valid). |
| isValidBsDate / isCompleteBsDate | boolean | — | 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 2000–2100. Outside that range, conversion helpers throwRangeError.Source: packages/nepali-datepicker