Skip to content

Date picker ​

Introduction ​

The date picker is a text field with a calendar. People type a date or pick one, in BS or AD, and you get the AD date.

Basic usage ​

tsx
import { useState } from 'react';
import { DatePicker } from '@nepdatejs/react';

export function BirthDate() {
  const [value, setValue] = useState('');

  return (
    <label>
      Date of birth
      <DatePicker value={value} onChange={setValue} />
    </label>
  );
}
html
<label for="dob">Date of birth</label>
<nep-date-picker name="dob" input-id="dob"></nep-date-picker>

Reading the value ​

The value is the AD date as YYYY-MM-DD, or an empty string when the field is empty or invalid. The change callback also gives you both calendars as date objects:

tsx
<DatePicker
  onChange={(value, date) => {
    console.log(value); // "2026-10-10"
    console.log(date?.ad); // { calendar: 'AD', year: 2026, month: 10, day: 10 }
    console.log(date?.bs); // { calendar: 'BS', year: 2083, month: 6, day: 24 }
  }}
/>;
html
<nep-date-picker id="date"></nep-date-picker>

<script>
  document.querySelector('#date').addEventListener('change', (event) => {
    console.log(event.detail.value); // "2026-10-10"
    console.log(event.detail.ad);
    console.log(event.detail.bs);
  });
</script>

Setting a starting value ​

Values you pass in are AD too:

tsx
<DatePicker defaultValue="2026-10-10" />;
html
<nep-date-picker value="2026-10-10"></nep-date-picker>

Fixing the calendar ​

By default the picker starts in BS and shows a switch. Use calendar to fix one calendar and hide the switch, or defaultCalendar to choose which one comes first.

tsx
<>
  <DatePicker calendar="BS" />
  <DatePicker defaultCalendar="AD" />
</>;
html
<nep-date-picker calendar="BS"></nep-date-picker>
<nep-date-picker default-calendar="AD"></nep-date-picker>

The value is AD in every case. Fixing the calendar to BS only changes what's shown.

Remembering the choice ​

persistCalendar saves the person's BS/AD choice in localStorage under the key you give, and restores it next time:

tsx
<DatePicker persistCalendar="date-calendar" />;
html
<nep-date-picker persist-calendar="date-calendar"></nep-date-picker>

To react to the switch yourself, use onCalendarChange in React, or the nep-calendar-change event on the element.

Limits ​

min and max are AD strings. isDateDisabled rules out individual days, such as Saturdays:

tsx
<DatePicker
  min="2026-01-01"
  max="2026-12-31"
  isDateDisabled={(date) => isWeekend(date)}
/>;
html
<nep-date-picker id="date" min="2026-01-01" max="2026-12-31"></nep-date-picker>

<script type="module">
  import { isWeekend } from '@nepdatejs/core';

  document.querySelector('#date').isDateDisabled = (date) => isWeekend(date);
</script>

See Limits and validation for error messages and more.

Showing the other calendar ​

Under the field, the picker shows the same day in the other calendar, such as "10 October 2026 AD". It helps people check they have the right date. To hide it:

tsx
<DatePicker showEquivalent={false} />;
html
<nep-date-picker show-equivalent="false"></nep-date-picker>

Each day in the panel also shows the other calendar's day number. Turn that off with showOtherCalendar={false}.

How the date is shown ​

The field shows YYYY-MM-DD by default, which can also be typed back. displayFormat takes any format:

tsx
<DatePicker displayFormat="long" />;
html
<nep-date-picker display-format="long"></nep-date-picker>

Language ​

tsx
<DatePicker locale="ne" />;
html
<nep-date-picker locale="ne"></nep-date-picker>

Keeping the panel open ​

The panel closes after a pick. To keep it open:

tsx
<DatePicker closeOnSelect={false} />;
html
<nep-date-picker close-on-select="false"></nep-date-picker>

To keep the calendar on the page all the time, see inline mode.

Options ​

These are React props. In HTML, each one is an attribute in kebab-case, such as default-calendar. Functions and lists are set as properties on the element. The full list is in the Web Components reference.

PropTypeDefaultMeaning
valuestringThe AD date, when you control the value
defaultValuestring''The starting AD date
onChange(value, date) => voidCalled when the person changes the value
calendar'BS' | 'AD'Fix the calendar and hide the switch
defaultCalendar'BS' | 'AD''BS'The calendar shown first
onCalendarChange(calendar) => voidCalled when the person switches
persistCalendarstringlocalStorage key for the BS/AD choice
min, maxstringEarliest and latest AD dates
isDateDisabled(date) => booleanRule out individual days
holidayslist or functionHolidays to mark
events(date) => EventMarker[]Event dots
presetsSinglePreset[]Shortcuts beside the calendar
locale'en' | 'ne' | stringpage languageNames, digits and messages
displayFormatstring'iso'How the field shows a date
showEquivalentbooleantrueShow the other calendar under the field
showOtherCalendarbooleantrueShow the other day number in each cell
clearablebooleantrueShow the clear button
closeOnSelectbooleantrueClose the panel after a pick
weekStartsOn0–60First day of the week
weekendDaysWeekday[][6]Days shown as weekend
maskbooleantrueAdd dashes while typing
inlinebooleanfalseAlways show the calendar
panelLayout'auto' | 'popover' | 'sheet''auto'Panel layout
namestringSubmit the value with a form
id, placeholder, required, disabledAs on an <input>
aria-label, aria-invalid, aria-describedbyPassed to the input
theme'light' | 'dark' | 'auto'Force a theme
classNamestringClass for the field
todayCalendarDateOverride "today", for tests and server rendering

Released under the MIT licence.