API Reference

This page documents the complete public API for nepali-bs-calendar-react v1.0.0.

Props

Prop	Type	Default	Description
`value`	`string \| null`	`null`	Current selected BS date in `YYYY-MM-DD` format.
`onChange`	`(value: string, date: NepaliDateValue) => void`	-	Callback triggered when a date is selected.
`minDate`	`string`	-	Minimum selectable BS date in `YYYY-MM-DD` format.
`maxDate`	`string`	-	Maximum selectable BS date in `YYYY-MM-DD` format.
`disabledDates`	`string[]`	`[]`	Specific disabled BS dates in `YYYY-MM-DD` format.
`isDateDisabled`	`(date: NepaliDateValue) => boolean`	-	Custom function to disable a date.
`label`	`string`	-	Label displayed above the picker.
`placeholder`	`string`	`Select date`	Placeholder text when no date is selected.
`calendarComponent`	`React.ComponentType<NepaliCalendarViewRenderProps>`	`-`	Custom calendar component that receives internal calendar state, actions, and helper values.
`renderCalendar`	`(props: NepaliCalendarViewRenderProps) => React.ReactNode`	`-`	Render prop alternative for custom calendar markup.
`disabled`	`boolean`	`false`	Disables the picker.
`error`	`string`	-	Error message shown below the picker.
`touched`	`boolean`	`false`	Shows error only when `touched` is true.
`className`	`string`	`""`	Extra class name added to the main wrapper.

Type Reference

type NepaliDateValue = {
  year: number
  month: number
  day: number
}

onChange Callback Shape

<NepaliCalendar
  value={date}
  onChange={(value, dateObject) => {
    console.log(value) // "2081-05-12"
    console.log(dateObject) // { year: 2081, month: 5, day: 12 }
  }}
/>

Custom Calendar Props Interface

If you write a custom template via calendarComponent or renderCalendar, your component/function receives:

interface NepaliCalendarViewRenderProps {
  viewYear: number
  viewMonth: number
  calendarCells: (NepaliDateValue | null)[]
  isDisabled: (date: NepaliDateValue) => boolean
  handleDayChange: (day: number) => void
  goToPreviousMonth: () => void
  goToNextMonth: () => void
  BS_MONTHS: string[]
  WEEK_DAYS: string[]
  toNepaliNumber: (num: number) => string
}

Utility Exports

import {
  adToBs,
  bsToAd,
  adStringToBs,
  bsStringToAd,
  formatBSDate,
  parseBSDate,
  isValidBSDate,
  getAvailableYears,
  getMonthDays,
  toNepaliNumber,
} from 'nepali-bs-calendar-react'

Overriding CSS variables is the easiest way to customize the look and feel. Because popups render via React Portals outside your local component tree, define overrides globally (e.g. on :root or body).

Date Picker CSS Variables

Variable	Default	Description
`--ndp-width`	`100%`	Main picker width.
`--ndp-gap`	`6px`	Gap between label, trigger, and error.
`--ndp-label-font-size`	`14px`	Label font size.
`--ndp-label-font-weight`	`500`	Label font weight.
`--ndp-label-color`	`#222`	Label color.
`--ndp-trigger-min-height`	`40px`	Trigger button minimum height.
`--ndp-trigger-border`	`#d9d9d9`	Trigger border color.
`--ndp-trigger-border-hover`	`#4096ff`	Trigger hover/open border color.
`--ndp-trigger-radius`	`8px`	Trigger border radius.
`--ndp-trigger-bg`	`#fff`	Trigger background.
`--ndp-trigger-padding`	`8px 12px`	Trigger padding.
`--ndp-trigger-focus-shadow`	`0 0 0 2px rgba(5, 145, 255, 0.12)`	Focus shadow.
`--ndp-trigger-disabled-bg`	`#f5f5f5`	Disabled trigger background.
`--ndp-trigger-disabled-color`	`rgba(0, 0, 0, 0.25)`	Disabled trigger text color.
`--ndp-value-color`	`rgba(0, 0, 0, 0.88)`	Selected value text color.
`--ndp-placeholder-color`	`rgba(0, 0, 0, 0.4)`	Placeholder color.
`--ndp-error-color`	`#ff4d4f`	Error color.
`--ndp-error-font-size`	`13px`	Error font size.
`--ndp-popover-min-width`	`280px`	Minimum popup width.

Calendar Panel CSS Variables

Variable	Default	Description
`--nc-border-color`	`#e5e7eb`	Calendar border color.
`--nc-border-radius`	`12px`	Calendar border radius.
`--nc-bg`	`#fff`	Calendar background.
`--nc-shadow`	`0 12px 32px rgba(15, 23, 42, 0.18)`	Calendar shadow.
`--nc-padding`	`14px`	Calendar padding.
`--nc-font-family`	`system-ui, -apple-system...`	Calendar font family.
`--nc-header-gap`	`8px`	Header gap.
`--nc-header-margin-bottom`	`12px`	Header bottom margin.
`--nc-title-font-size`	`16px`	Calendar title font size.
`--nc-title-font-weight`	`600`	Calendar title font weight.
`--nc-title-color`	`#111827`	Calendar title color.
`--nc-nav-btn-size`	`32px`	Previous/next button size.
`--nc-nav-btn-border-color`	`#e5e7eb`	Previous/next button border color.
`--nc-nav-btn-radius`	`8px`	Previous/next button radius.
`--nc-nav-btn-bg`	`#fff`	Previous/next button background.
`--nc-nav-btn-color`	`#111827`	Previous/next button text color.
`--nc-nav-btn-hover-bg`	`#f9fafb`	Previous/next hover background.
`--nc-nav-btn-font-size`	`22px`	Previous/next arrow font size.
`--nc-controls-gap`	`8px`	Gap between year, month, and day selects.
`--nc-controls-margin-bottom`	`12px`	Controls bottom margin.
`--nc-select-height`	`34px`	Select input height.
`--nc-select-border-color`	`#d1d5db`	Select input border color.
`--nc-select-radius`	`8px`	Select input border radius.
`--nc-select-bg`	`#fff`	Select input background.
`--nc-select-color`	`#111827`	Select input text color.
`--nc-select-padding`	`0 8px`	Select input padding.
`--nc-grid-gap`	`4px`	Gap between date cells.
`--nc-weekdays-margin-bottom`	`6px`	Weekday row bottom margin.
`--nc-weekday-font-size`	`12px`	Weekday font size.
`--nc-weekday-font-weight`	`600`	Weekday font weight.
`--nc-weekday-color`	`#6b7280`	Weekday text color.
`--nc-cell-min-height`	`36px`	Date cell minimum height.
`--nc-cell-radius`	`8px`	Date cell border radius.
`--nc-cell-bg`	`transparent`	Date cell background.
`--nc-cell-color`	`#111827`	Date cell text color.
`--nc-cell-hover-bg`	`#f3f4f6`	Date cell hover background.
`--nc-cell-selected-bg`	`#1677ff`	Selected date background.
`--nc-cell-selected-color`	`#fff`	Selected date text color.
`--nc-cell-selected-hover-bg`	`#1677ff`	Selected date hover background.
`--nc-cell-disabled-color`	`#bdbdbd`	Disabled date text color.
`--nc-cell-disabled-bg`	`transparent`	Disabled date background.

Mobile Responsive Styling Variables

:root {
  --nc-mobile-padding: 12px;
  --nc-mobile-title-font-size: 15px;
  --nc-mobile-nav-btn-size: 30px;
  --nc-mobile-cell-min-height: 34px;
  --nc-mobile-cell-font-size: 13px;
 
  --nc-small-padding: 10px;
  --nc-small-title-font-size: 14px;
  --nc-small-cell-min-height: 32px;
  --nc-small-cell-font-size: 12px;
 
  --nc-tiny-padding: 8px;
  --nc-tiny-cell-min-height: 30px;
  --nc-tiny-cell-font-size: 11px;
}