Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

headless-react-datepicker

sepehr096kMIT1.1.9TypeScript support: included

A headless, highly customizable, multi-calendar date picker component for React. It supports various calendars and locales.

react, datepicker, date picker, rangepicker, date, calendar, jalali, persian, gregorian, multi-calendar, multi-datepicker, multi-date-picker, locales, temporal, TC39, Intl, headless, Indian, Iso8601, Japanese, Buddhist, Chinese, Coptic, Dangi, Ethioaa, Ethiopic, Hebrew, Islamic, Islamic-umalqura, Roc

readme

Headless React Datepicker

NPM NPM NPM GitHub Actions Workflow Status

A headless, highly customizable, multi-calendar date picker component for React. It supports various calendars and locales.

Live demo

https://sepehr09.github.io/headless-react-datepicker/

Edit headless-react-datepicker

Customization

alt text

Supported Calendars

All calendars are supported by the ECMAScript's Intl API:

  • Gregory
  • Persian
  • Indian
  • Iso8601
  • Japanese
  • Buddhist
  • Chinese
  • Coptic
  • Dangi
  • Ethioaa
  • Ethiopic
  • Hebrew
  • Islamic
  • Islamic-umalqura
  • Islamic-tbla
  • Islamic-civil
  • Islamic-rgsa
  • Islamicc
  • Roc

Supported Locales

All locales are supported by the Intl API.

Installation

1. install the package

npm install headless-react-datepicker

# or

yarn add headless-react-datepicker

# or

pnpm add headless-react-datepicker

2. import the css file

import "headless-react-datepicker/dist/styles.css";

Usage

import React from "react";
import DatePickerProvider, {
  Title,
  Header,
  WeekDays,
  DaySlots,
} from "headless-react-datepicker";

const MyAwesomeDatePicker = () => {
  return (
    <DatePickerProvider>
      <Title />
      <Header />
      <WeekDays />
      <DaySlots />
    </DatePickerProvider>
  );
};

Customization

Customization of the headless-react-datepicker

Headless!

Headless React Datepicker structure

DatePickerProvider

Must be in place as the parent of the whole calendar component.

import { DatePickerProvider } from "headless-react-datepicker";

props

Name Type Description
value Date | Date[] The value of the date picker (Controlled component).
initialValue Date | Date[] The initial value of the date picker.
defaultStartDate Date The default start date. Useful when you want to be on a different month or year despite the initial value.
config TCalendarConfig The configuration for the date picker.
isRange boolean Indicates whether the date picker is a range picker.
calendar TCalendar The calendar to use.
onChange (value: Date | Date[]) => void on calendar selected date change
children ReactNode The other parts of the calendar or your custom components.

TCalendarConfig

Name Type Description Default
weekStartsOn TDay | undefined The first day of the week. "monday"
locale string | undefined The locale to use. "en-US"
showOtherDays boolean | undefined Show other days from the previous and next month or not. false
otherDaysSelectable boolean | undefined Allow selecting other days from the previous and next month or not. false
weekdayFormat "long" | "short" | "narrow" | undefined | "narrow"
dayFormat "numeric" | "2-digit" | undefined | "numeric"
yearRangeFrom number | undefined | last 10 years if not provided
yearRangeTo number | undefined | current year if not provided
maxDate Date | undefined Prevent selecting dates before this date.
minDate Date | undefined Prevent selecting dates after this date.
weekends TDay[] | undefined Specify which days of the week are holidays. undefined
weekendSelectable boolean | undefined Allow selecting weekends or not. true
allowBackwardRange boolean | undefined If user select a date before the previous selected date, it will be considered as a range or start from beginning. false

TCalendar

"gregory" | "persian" | "islamic" | "islamic-umalqura" | "islamic-tbla" | "islamic-civil" | "islamic-rgsa" | "iso8601" | "japanese" | "islamicc" | "roc" | "chinese" | "indian" | "buddhist" | "coptic" | "dangi" | "ethioaa" | "ethiopic" | "hebrew"

Components

Title component

The Title component is used to display the month and year based on the selected locale and calendar.

import { Title } from "headless-react-datepicker";

props

Name Type Options Default
monthFormat string | undefined "numeric", "2-digit" , "long" , "short" , "narrow" "short"
yearFormat string | undefined "numeric" , "2-digit" "numeric"
className string ClassName of the title component
style CSSProperties css styles of the title component

Header component

The Header component is used to navigate to the next and previous month and select month and year from the drop-down list.

You can customize arrow icons with React Node and the dropdowns with className and CSS stylesheets.

import { Header } from "headless-react-datepicker";

props

Name Type Description
leftIcon ReactNode
rightIcon ReactNode
rootClassName string the root className of the header
rootStyles CSSProperties the root css styles of the header
monthSelectClassName string Class name of the month select dropdown
monthSelectStyles CSSProperties css styles of the month select dropdown
monthOptionClassName string className of the month Options in the dropdown
monthOptionStyles CSSProperties css styles of the month Options in the dropdown
monthSelectedOptionClassName string className the selected option in the month dropdown
monthSelectedOptionStyles CSSProperties css styles the selected option in the month dropdown
yearSelectClassName string className of the year select dropdown
yearSelectStyles CSSProperties css styles of the year select dropdown
yearOptionClassName string className of the year Options in the dropdown
yearOptionStyles CSSProperties css styles of the year Options in the dropdown
yearSelectedOptionClassName string className the selected option in the year dropdown
yearSelectedOptionStyles CSSProperties css styles the selected option in the year dropdown
prevButtonClassName string className of the previous button (left button)
prevButtonStyles CSSProperties css styles of the previous button (left button)
nextButtonClassName string className of the next button (right button)
nextButtonStyles CSSProperties css style of the next button (right button)

WeekDays component

The WeekDays component is used to display the weekday header.

import { WeekDays } from "headless-react-datepicker";

props

Name Type Description
renderer (args: TWeekDaysRendererArgs) => ReactNode Custom renderer. If provided, the whole component will be ignored
className string Custom class name for the element
style CSSProperties css styles for the element
rootClassName string Custom class name for the parent root element
rootStyle CSSProperties css styles for the parent root element

TWeekDaysRendererArgs

Name Type Options Description
formattedTitle string | Title based on calendar config.weekdayFormat which follows locale and calendar.
weekIndex number |
weekDay TDay "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday"

DaySlots component

The DaySlots component is used to display the month and year based on the selected locale and calendar.

import { DaySlots } from "headless-react-datepicker";

props

Name Type Description Default
dayRenderer (args: TDaySlotsDayRendererArgs) => ReactNode Custom renderer
onClickSlot (date: Date) => void when click on slot
parentClassName string parent box
parentStyles CSSProperties parent box
slotParentClassName string |
slotParentStyles CSSProperties |
slotClassName string |
slotStyles CSSProperties |
todayStyles CSSProperties |
todayClassName string |
todayParentStyles CSSProperties |
todayParentClassName string |
disableStyles CSSProperties |
disableClassName string |
disableParentStyles CSSProperties |
disableParentClassName string |
weekendStyles CSSProperties |
weekendClassName string |
weekendParentStyles CSSProperties |
weekendParentClassName string |
selectedStyles CSSProperties |
selectedClassName string |
selectedParentStyles CSSProperties |
selectedParentClassName string |
selectableStyles CSSProperties |
selectableClassName string |
selectableParentStyles CSSProperties |
selectableParentClassName string |
inSelectedRangeStyles CSSProperties |
inSelectedRangeClassName string |
inSelectedRangeParentStyles CSSProperties |
inSelectedRangeParentClassName string |
inHoveredRangeStyles CSSProperties |
inHoveredRangeClassName string |
inHoveredRangeParentStyles CSSProperties |
inHoveredRangeParentClassName string |
startOfRangeStyles CSSProperties |
startOfRangeClassName string |
startOfRangeParentStyles CSSProperties |
startOfRangeParentClassName string |
endOfRangeStyles CSSProperties |
endOfRangeClassName string |
endOfRangeParentStyles CSSProperties |
endOfRangeParentClassName string

TDaySlotsDayRendererArgs props

Name Type Options Default
date Date based on calendar config.dayFormat which follows locale and calendar.
formattedDay string Formatted date based on locale and calendar which is in the calendar config.
IsToday boolean Indicate that is the day is today or not.
isSelectable boolean Is the day can be selected or not.
isDisabled boolean Is the day is disabled or not.
isInSelectedRange boolean Is in the selected range (if calendar type is range) or not.
isInHoveredRange boolean Is in the hovered range (if calendar type is range) or not.
isStartOfRange boolean |
isEndOfRange boolean |
isInWeekend boolean |
isSelected boolean |
handleClickSlot (date: Date) => void |
handleKeyDown (e: React.KeyboardEvent<HTMLDivElement>, date: Date) => void onKeyDown event

Date picker Context

You can access almost all props and functions of the date picker from the date picker context, so you can customize and build your own custom component easily.

example

import { useDatePickerContext } from "headless-react-datepicker";

const MyCustomAwesomeHeader = () => {
  const { goToCurrentMonth, yearInTheCalendar } = useDatePickerContext();

  return <div onClick={goToCurrentMonth}>{yearInTheCalendar}</div>;
};

returned props

Name Type Description
goToNextMonth () => void Function to navigate to the next month
goToPrevMonth () => void Function to navigate to the previous month
goToDate (date: Date) => void Function to navigate to a specific date
goToCurrentMonth () => void Function to navigate to the current month
goToMonth (month: number) => void Local month (based on the desired calendar)
goToYear (year: number) => void Handle go to year (based on desire calendar)
daysOfMonth Date[] All the dates of the month rendered in the calendar
startDateIncludeOtherDays Date End date of the month rendered in the calendar (include previous month days (if in the week))
endDateIncludeOtherDays Date Start date of the month rendered in the calendar (include next month days (if in the week))
firstDayOfMonth Date First day of the month
lastDayOfMonth Date Last day of the month
selectedDay Date | Date[] | undefined The selected day in the calendar
handleClickSlot (date: Date) => void Callback function when a date is clicked
monthInTheCalendar number Current month in the calendar (based on desire calendar)
totalDaysInTheCalendar number Indicate the total days in the month
yearInTheCalendar number Current year in the desire calendar
monthsList TMonthListItem[] List of all month based on culture
yearsList number[] List of all years based on yearRangeFrom and yearRangeTo
initialValue Date | Date[] The initial value of the date picker.
defaultStartDate Date The default start date. Useful when you want to be on different month or year despite the initial value.
config TCalendarConfig The configuration for the date picker.
isRange boolean Indicates whether the date picker is a range picker.
calendar TCalendar The calendar to use.

Dependencies

Using the Intl API which is ECMAScript Internationalization API with a very good browser support and depends on Temporal for converting other calendars into gregory.

Todo

  • <input checked="" disabled="" type="checkbox"> remove dependency to date-fns
  • <input disabled="" type="checkbox"> time picker
  • <input disabled="" type="checkbox"> rangle picker hover effect
  • <input disabled="" type="checkbox"> integrate popover for whole calendar
  • <input disabled="" type="checkbox"> two side by side calendar

License

MIT @ Sepehr09

Contributing

We're eagerly welcoming to contributors who want to help build and maintain this repo. PRs are always welcome!

Change log

you can see the change log here

changelog

Changelog

version 1.1.9

  • new: add isInHoveredRange prop to DaySlots component to be able to style the hovered range..
  • new: add inHoveredRangeStyles prop to DaySlots component to be able to style the hovered range.
  • new: add inHoveredRangeClassName prop to DaySlots component to be able to style the hovered range.
  • new: add inHoveredRangeParentStyles prop to DaySlots component to be able to style the hovered range.
  • new: add inHoveredRangeParentClassName prop to DaySlots component to be able to style the hovered range.
  • new: add prevButtonClassName prop to Header component.
  • new: add nextButtonClassName prop to Header component.
  • new: add prevButtonStyles prop to Header component.
  • new: add nextButtonStyles prop to Header component.
  • new: add rootStyles prop to Header component.
  • chore: remove warning for unique "key" prop and defaultValue for select component.

version 1.1.7

  • fix: on value change, the calendar should respect the defaultSelectedDate if it is provided.

version 1.1.6

  • new: add rootClassName prop to Header component.
  • new: add prevButtonClassName prop to Header component.
  • new: add nextButtonClassName prop to Header component.
  • fix: header next button aria-label wording fixed.
  • fix: in range picker, when not selecting the second date, the end of range class and styles should not be applied.

version 1.1.4

  • fix: classNames orders fixed by priority
  • new: expose handleKeyDown in dayRenderer component to be able to handle keyboard events.

version 1.1.2

  • fix: minor fix onChange wont return range if value is provided and value was not changed.
  • fix: duplicate classNames fixed for able to use tailwindcss classes.

version 1.1.1

  • new: add aria-label and role for better accessibility.
  • new: add keyboard events for better accessibility.
  • new: add keyboard arrow navigation for better accessibility so that user can navigate through the calendar using arrow keys.
  • chore: refactor some codes to improve performance.
  • fix: duplicate classNames will be removed now on elements.

version 1.1.0

  • new: add value prop to support controlled component.
  • new: add TDatePickerOnChange type to handle onChange event.
  • new: add TDatePickerValue type.
  • new: add onClickSlot prop to handle click event in DaySlots component.
  • chore: use useCallback to memoize onChange function internally for better performance.

version 1.0.3

  • fix: timezone issue causing wrong selection in month and year dropdown.
  • refactor: remove date-fns dependency and use native utils.
  • new: add className prop to add custom class to the Title component.
  • new: add style prop to add custom style to the Title component.
  • new: add rootStyle prop to add custom style to the WeekDays parent component.
  • new: add style prop to add custom style to the WeekDays component.
  • new: add parentClassName prop to add custom class to the DaySlots parent component.
  • new: add parentStyles prop to add custom style to the DaySlots parent component.
  • chore: Add Vitest and write some test cases for some utility functions.
  • chore: add some examples in the storybook.

version 1.0.2

  • fix: ios converting date issue.

version 1.0.1:

  • feat: add allowBackwardRange to control behavior of backward range selection.
  • fix: fix next/previous arrow functionality when minDate and maxDate are passed in config.
  • fix: wrong firstDayOfMonth calculation because of local timezone.