Nepali Charm Calendar

Composable Nepali (Bikram Sambat) calendar components, inputs, utilities, and holiday data for React applications. Ship production-ready BS/AD date pickers, full-featured calendars, and event timelines without rebuilding complex date logic.

Highlights

• Full Nepali calendar grid with BS/AD conversion, lunar metadata, and holiday overlays
• Drop-in BS date and date-time inputs with validation
• Event manager UI for creating and curating localized events
• Strongly typed utilities for conversions, formatting, ranges, and holiday data loading
• Written in TypeScript, styled with Tailwind/shadcn, and published as a tree-shakeable ESM/CJS bundle

Table of Contents

1. Installation
2. Importing styles
3. Quick start
4. Core components
5. Holiday data and events
6. Utilities
7. Local development
8. License

Installation

Use any package manager. React 18.3+ is required via peer dependencies.

# pnpm
pnpm add @verishore/nepali-calendar

# npm
npm install @verishore/nepali-calendar

# yarn
yarn add @verishore/nepali-calendar

Importing styles

All components share a small stylesheet that ships with the package. Import it once in your application entry point (e.g., src/main.tsx).

import "@verishore/nepali-calendar/style.css";

If you already use Tailwind or shadcn-ui, no additional setup is required. The CSS file only provides structural defaults so you can still override classes freely.

Quick start

import {
	NepaliCalendar,
	NepaliDateInput,
	NepaliDateTimeInput,
	FullNepaliCalendar,
	EventManager,
	type CalendarEvent,
	type NepaliDateData
} from "@verishore/nepali-calendar";

const events: CalendarEvent[] = [];

export function DemoCalendar() {
	const [selectedDate, setSelectedDate] = useState<NepaliDateData>();
	const [customEvents, setCustomEvents] = useState(events);

	return (
		<div className="space-y-8">
			<NepaliDateInput value={selectedDate} onChange={setSelectedDate} />
			<NepaliCalendar selectedDate={selectedDate} onDateSelect={setSelectedDate} events={customEvents} />
			<FullNepaliCalendar onDateSelect={setSelectedDate} />
			<EventManager events={customEvents} onEventsChange={setCustomEvents} />
		</div>
	);
}

Core components

NepaliCalendar

• Compact month view with range selection, AD mirrors, and event badges
• Works standalone or inside popovers (used by the input components)

| Prop | Type | Default | Description | | --- | --- | --- | --- | | selectedDate | NepaliDateData | undefined | Controlled value for single-date mode | | onDateSelect | (date) => void | undefined | Fired when a date is clicked | | events | CalendarEvent[] | [] | Display per-day markers and tooltips | | mode | 'single' \| 'range' | 'single' | Enables BS range picking | | selectedRange | DateRange | undefined | Controlled range state | | onRangeSelect | (range) => void | undefined | Range change callback | | restrictions | DateRestrictions | undefined | Disable dates, min/max bounds | | showAdDates | boolean | true | Show AD mirror beneath each day | | language | 'en' \| 'ne' | 'en' | Toggle labels and numerals |

<NepaliCalendar
	defaultDate={{ year: 2081, month: 5, day: 1, formatted: "2081/05/01" }}
	mode="range"
	restrictions={{
		minDate: { year: 2075, month: 1, day: 1, formatted: "2075/01/01" },
		maxDate: { year: 2085, month: 12, day: 30, formatted: "2085/12/30" }
	}}
	events={events}
	onRangeSelect={(range) => console.log(range)}
/>;

FullNepaliCalendar

• Dashboard-style planner: BS and AD conversion, lunar info, searchable year selector, event overlays, copy-to-clipboard helpers
• Great for analytics pages or knowledge bases where users browse entire months

<FullNepaliCalendar
	language="ne"
	onDateSelect={(date) => console.log("Picked", date)}
/>;

NepaliDateInput

• Text input with inline validation, popover calendar, and optional localization

| Prop | Type | Default | | --- | --- | --- | | value | NepaliDateData | undefined | | onChange | (date) => void | undefined | | label | string | "Select Date" | | placeholder | string | "YYYY/MM/DD" | | language | 'en' \| 'ne' | 'en' |

<NepaliDateInput label="Birth date (BS)" value={value} onChange={setValue} />

NepaliDateTimeInput

• Adds hour/minute selectors (00-23 / 00-59) to the calendar popover

<NepaliDateTimeInput
	value={appointment}
	onChange={setAppointment}
	placeholder="2081/05/10 14:45"
/>;

EventManager

• CRUD UI for CalendarEvent objects (titles in EN/NE, colors, JSON import/export)

const [events, setEvents] = useState<CalendarEvent[]>([]);

<EventManager events={events} onEventsChange={setEvents} />;

Holiday data and events

Holiday helpers live under data/nepaliHolidays and are exported from the root package.

import {
	loadDefaultHolidays,
	loadHolidaysForYear,
	registerHolidaysForYear,
	getEventsForDate,
	getEventsForMonth,
	getAvailableHolidayYears
} from "@verishore/nepali-calendar";

await loadDefaultHolidays();
const dashain = await getEventsForDate(2081, 6, 10);
const mangsirEvents = await getEventsForMonth(2081, 8);

registerHolidaysForYear(2085, customEvents);

• loadDefaultHolidays() lazily fetches bundled data (currently includes 2080-2082)
• loadHolidaysForYear(year) fetches a specific BS year on demand
• registerHolidaysForYear(year, events) lets you inject remote data or CMS content
• getEventsForDate/getEventsForMonth return CalendarEvent[] suitable for the UI components
• getAvailableHolidayYears() and hasHolidayDataForYear(year) help you gate selectors

Utilities

Everything inside src/utils/nepaliDateUtils.ts is exported for reuse:

• Conversions: adToBs, bsToAd, parseDateInput, convertToNepaliDate, convertToADDate
• Formatting and numerals: formatNepaliDate, englishToNepaliNumber, nepaliToEnglishNumber
• State helpers: getCurrentNepaliDate, compareNepaliDates, isDateDisabled, validateDateRange
• Domain data: nepaliMonths, nepaliWeekDays, getTithi, getPaksha, getNakshatra
• Types: NepaliDateData, DateRange, DateRestrictions, CalendarEvent, NepaliDateTimeData

These utilities are framework-agnostic and can back server code, cron jobs, or other UI kits.

Local development

Clone the repo if you want to tweak the source or contribute.

pnpm install
pnpm run dev       # Playground with Vite
pnpm run build     # Library bundle (ESM+CJS+types)
pnpm run lint      # ESLint (flat config)

Publishing uses pnpm publish and runs prepublishOnly (lint + build) automatically.

License

MIT © Sujit. Contributions welcome—please open an issue or PR if you ship improvements or additional holiday datasets.