React Nepali Date Picker

A lightweight, reusable React + TypeScript Nepali date picker package that ships with zero external date dependencies.

Install

npm install @react-nepali-datepicker

Development Scaffold (from scratch)

mkdir react-nepali-calendar
cd react-nepali-calendar
npm init -y
npm i -D typescript tsup vitest jsdom @testing-library/react @testing-library/user-event @testing-library/jest-dom @types/react @types/react-dom

Add the files from this repository layout:

• src/utils/nepDate.ts
• src/components/NepaliDatePicker.tsx
• src/hooks/useOnClickOutside.ts
• src/styles/nepali-date-picker.css
• src/data/noOfDays.json
• tests/*.test.ts(x)

Usage

import { useState } from "react";
import { NepaliDatePicker } from "@nepalicalendar/react-nepali-datepicker";
import "@nepalicalendar/react-nepali-datepicker/styles.css";

export function Demo() {
  const [value, setValue] = useState<Date | null>(new Date());

  return (
    <NepaliDatePicker
      value={value}
      minDate={new Date(1943, 3, 14)}
      maxDate={new Date(2044, 3, 13)}
      locale="en"
      onChange={(date, nepaliDateString) => {
        setValue(date);
        console.log(date, nepaliDateString);
      }}
    />
  );
}

API

• value?: Date | string | null — Controlled value. Accepts a JavaScript Date, a Nepali date string ("YYYY/MM/DD"), or a raw input string. When provided the picker reflects this value.
• onChange?: (date: Date, nepaliDateString: string) => void — Called when a valid date is committed (via calendar selection or input commit). Receives the Gregorian Date and the Nepali-formatted string.
• minDate?: Date — Minimum allowed Gregorian date (inclusive). Dates before this are disabled in the calendar and rejected on commit.
• maxDate?: Date — Maximum allowed Gregorian date (inclusive). Dates after this are disabled in the calendar and rejected on commit.
• locale?: 'en' | 'ne' — Locale for month names, weekday labels and digit formatting. Default: 'en'. Set to 'ne' to show Nepali month names and digits.
• placeholder?: string — Input placeholder text. Default: 'YYYY/MM/DD'. The input enforces a numeric mask and a maxLength of 10.
• className?: string — CSS class applied to the root .ndp-root for styling or layout overrides.
• style?: CSSProperties — Inline styles applied to the root element (e.g. { width: 520 }).
• required?: boolean — Marks the input as required. When true an empty blur will mark the input invalid. Default: false.

Accessibility & Behavior

• Uses forwardRef (the exported NepaliDatePicker forwards an input ref) for form-library integration.
• The text input uses inputMode="numeric", maxLength=10 and an automatic masking behaviour that clamps year/month/day to valid ranges.
• Keyboard navigation and selection are supported (arrow keys, Enter to commit).
• The calendar and input expose ARIA attributes (aria-expanded, aria-controls, aria-invalid, aria-required) and the toggle button includes an accessible label.

Features

• Zero external date dependencies — conversion is driven by the bundled noOfDays.json.
• Accepts both Date and Nepali YYYY/MM/DD strings as value.
• Input masking (YYYY/MM/DD) with clamping by valid month/day counts.
• Strict validation on blur and on explicit complete input; invalid or out-of-range inputs set the invalid state.
• Calendar navigation respects minDate/maxDate and will disable navigation to months outside bounds.
• Locale-aware month names and digit formatting ('en' | 'ne').

You can view the supported conversion range via the exported utilities (getSupportedDateRange() in src/utils/nepDate.ts).

Styling using className

.my-datepicker { max-width: none; width: 420px; }
.my-datepicker .ndp-input { font-size: 1rem; }

<NepaliDatePicker className="my-datepicker" value={...} onChange={...} />
<NepaliDatePicker style={{ width: 520 }} />

Note: Caveat: because .ndp-root has max-width: 320px, wrapping alone may not expand the picker unless you also override that max-width (via className or CSS).

Scripts

npm run build
npm run test
npm run test:watch
npm run typecheck

Notes

• Date conversion is synchronous and uses bundled noOfDays.json.
• Invalid or out-of-range values throw RangeError in utility methods (no silent fallback to current date).
• The picker uses forwardRef for form library integration.