Documentation

Complete API reference and usage guide for bos-nepali-date — a React component for selecting Bikram Sambat (Nepali) dates with a pluggable conversion engine. API design follows Ant Design DatePicker conventions.

Getting started

$ npm install bos-nepali-date

import { useState } from "react"
import { NepaliDatePicker, defaultAdapter } from "bos-nepali-date"

function Demo() {
  const [value, setValue] = useState(null)
  return (
    <NepaliDatePicker
      value={value}
      onChange={setValue}
      adapter={defaultAdapter}
    />
  )
} Copy

Basic usage

The onChange callback receives a BsDate object or null (when cleared).

// Range picker usage
import { NepaliDateRangePicker } from "bos-nepali-date"

function RangeDemo() {
  const [range, setRange] = useState([null, null])
  return (
    <NepaliDateRangePicker
      value={range}
      onChange={setRange}
      adapter={defaultAdapter}
    />
  )
} Copy

Common props

These props are shared by both NepaliDatePicker and NepaliDateRangePicker.

Basic

Date control

Display

Localization

Customization

Popover control

Events

NepaliDatePicker

The single date picker component. Accepts all common props plus the following:

// Full featured single picker
<NepaliDatePicker
  value={value}
  onChange={setValue}
  adapter={adapter}
  variant="outlined"
  size="middle"
  status="error"
  placement="bottomLeft"
  allowClear
  inputReadOnly
  disabledDate={(d) => d.day === 5}
  menu={{ lang: "en" }}
  classNames={{ popup: "my-popup" }}
  renderExtraFooter={() => <span>Custom footer</span>}
/> Copy

NepaliDateRangePicker

The range date picker component for selecting start and end dates. Accepts all common props plus the following:

// Range picker with all options
<NepaliDateRangePicker
  value={[start, end]}
  onChange={setRange}
  adapter={fullAdapter}
  minDate={{ year: 2080, month: 1, day: 1 }}
  maxDate={{ year: 2085, month: 12, day: 30 }}
  separator="to"
  size="small"
  variant="filled"
  allowClear
  menu={{ lang: "ne" }}
/>

Range selection behavior

• First click: selects the start date — the popover stays open and highlights the start cell.
• Second click: selects the end date — the popover closes and onChange fires with the full range. Dates between start and end are highlighted.
• Auto-swap: If the second click lands before the start date, the range is automatically reversed so start ≤ end.
• Hover preview: While selecting the end date, hovering over dates shows a visual preview of the in-progress range.
• Third click: Clicking when both dates are already set restarts the selection with the clicked date as the new start.
• Input typing: Both input fields accept typed BS dates in YYYY-MM-DD format (supports Nepali digits).
• Clear button: Clears both start and end values (when allowClear is enabled).

Disable options

Pass a disable object to control which dates cannot be selected. These static rules combine with the disabledDate callback — if any rule marks a date as disabled, it will be unselectable.

// Disable today + block specific dates + block past dates
<NepaliDatePicker
  disable={{
    today: true,
    dates: [
      { year: 2081, month: 1, day: 1 },
      { year: 2081, month: 1, day: 15 },
    ],
    before: { year: 2081, month: 1, day: 10 },
  }}
  disabledDate={(d) => d.day === 5} // also disable every 5th
/> Copy

Menu options

The menu prop controls localization, calendar layout, and visibility of navigation controls.

// Nepali locale with Monday start, hide year selector
<NepaliDatePicker
  menu={{
    lang: "ne",
    firstDayOfWeek: 1,
    showMonth: true,
    showYear: false,
  }}
/> Copy

Localization behavior

The input accepts Nepali digits (०-९) and normalizes them to ASCII automatically. The onChange value always returns ASCII BS dates.

classNames & styles

Both pickers accept classNames and styles props for granular styling of sub-elements. These follow the same pattern as Ant Design's classNames/styles API.

PickerClassNames

PickerStyles

<NepaliDatePicker
  classNames={{
    popup: "my-custom-popup",
    cell: "my-custom-cell",
    footer: "dark-mode-footer",
  }}
  styles={{
    popup: { borderRadius: "16px" },
    header: { background: "#fef3c7" },
  }}
/>

Styling

The picker's base styles are auto-imported from the CSS bundle. Override these CSS variables to theme the component.

CSS Variables

/* Custom theme override */
.np-picker {
  --np-font: "Noto Sans Devanagari", sans-serif;
  --np-popover-min-width: 300px;
  --np-color-error: #dc2626;
  --np-color-warning: #d97706;
}

Adapter

The adapter is the conversion engine that translates between Bikram Sambat (BS) and Gregorian (AD) dates. The library ships with two built-in adapters.

defaultAdapter

Pre-configured with demo data for BS years 2080–2081. Suitable for evaluation and development. Not recommended for production — toAD() and toBS() throw for dates outside this range.

MemoryBsAdapter

Create a custom adapter with your own complete year table for production use.

import { MemoryBsAdapter } from "bos-nepali-date"

const adapter = new MemoryBsAdapter({
  anchorBs: { year: 2000, month: 1, day: 1 },
  anchorAdIso: "1943-04-14",
  yearTable: {
    2080: [31, 32, 31, 32, 31, 30, 30, 30, 29, 30, 29, 31],
    2081: [31, 31, 31, 32, 31, 31, 30, 29, 30, 29, 30, 30],
  },
})

BsAdapter interface

Implement this interface to provide your own conversion logic, e.g., from an API or database.

// Custom adapter example (e.g., API-backed)
const apiAdapter: BsAdapter = {
  toAD: (date) => { /* POST /convert-to-ad */ },
  toBS: (iso) => { /* POST /convert-to-bs */ },
  addDays: (date, days) => { /* POST /add-days */ },
  diffDays: (a, b) => { /* POST /diff */ },
  today: () => { /* GET /today-bs */ },
  range: { min: { year: 2000, month: 1, day: 1 }, max: { year: 2090, month: 12, day: 30 } },
}

TypeScript

All components and types are fully typed. Key exports:

// Import types:
import {
  type BsDate, type BsAdapter, type AdDateIso,
  type DisableOptions, type MenuOptions,
  type PickerSize, type PickerStatus,
  type PickerVariant, type PickerPlacement,
  type CellRenderInfo, type NepaliDateRangePickerProps,
} from "bos-nepali-date"

Accessibility

The picker components follow WAI-ARIA design patterns for accessible date picker widgets.