Headless React Datepicker

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/

Customization

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

Headless!

DatePickerProvider

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

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

props

TCalendarConfig

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

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

WeekDays component

The WeekDays component is used to display the weekday header.

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

props

TWeekDaysRendererArgs

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

TDaySlotsDayRendererArgs props

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

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

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.