rhdp v3.0.2
RHDP - React Hook Datepicker
A React Hook based primitive to build simple, flexible datepicker components that are WAI-ARIA compliant, and support localization.
The Problem
You need a datepicker that can be fully customized in appearance, but it needs to be accessible, and flexible enough to meet your needs. It should work with any design system, including one built in-house, and have zero dependencies (besides React of course). It should also meet accessibility specs for screenreaders, as well as keyboard accessibility. It should also only concern itself with dates, a datepicker should not concern itself with time, or timezones.
The Solution
RHDP offers a single react hook called useDatepicker. It provides functions and properties to populate your own React based datepicker component. It is fully typed with Typescript and backed by interaction and unit tests. You can lift and shift any of the existing datepicker components built with RHDP in the examples and adapt them to your needs.
Use your own design system or one of the many publicly available design systems to easily match the datepicker with the look for your site. Just provide css classes for the applicable styles for them to be applied at the component level.
This React Hook Datepicker allows several modes of operation: single select, range select, multi-select, and max multi-select. Selectable dates can be limited by min and max dates as well as blocked dates. It also supports Sunday or Monday as the start of the week.
RHDP takes in the ISO 8601 extended date format, that's to say YYYY-MM-DD and outputs the same. This format allows for lexicographical sorting of dates, and removes any concerns or bugs that may arise from dealing with disparate local and server times.
Zero dependencies & purpose built.
Props
All props are fully typed in Typescript. This small subset is provided here for quick reference. View the full types.
| Property | Type | Description |
|---|---|---|
blockedDates | string[] \| string | YYYY-MM-DD format, prevents selection of specified dates |
focusOnInit | boolean | Will cause focus to be set to the first of an array of dates or today |
hasFocusTrap | boolean | Will cause focus to be constrained to the datepicker and controls while the datepicker is open as a popover |
labels | object | Button labels for accessibility, English defaults provided |
labels.closeButton | string | |
labels.dateSelected | string | |
labels.nextMonthButton | string | |
labels.nextYearButton | string | |
labels.previousMonthButton | string | |
labels.previousYearButton | string | |
labels.today | string | |
locale | Intl.DateTimeFormat | Defaults to en-US, see Localization section for more details |
maxDate | string | YYYY-MM-DD format, if set prevents selection & navigation past that date |
minDate | string | YYYY-MM-DD format, if set prevents selection & navigation before that date |
mode | 'single' \| 'range' \| 'multiple' \| number | Sets the selection mode for the datepicker, number is a max # of dates |
onChange | function(string[] \| string) | Function called whenever the selected dates change (string in single mode, otherwise an array) |
onClose | function() | Function which is executed when date selection criteria is satisfied |
selectDates | string[] \| string | YYYY-MM-DD format, pre-selects the supplied dates |
weekStart | 0 \| 1 | Changes the start day of the week from Sunday to Monday |
Returned props
All returned props are fully typed in Typescript. This small subset is provided here for quick reference. View the full types.
| Property | Type | Description |
|---|---|---|
calendar | CalendarDay[][] | Represents the current month's calendar, see CalendarDay type for more details |
displayDaysOfTheWeek | DisplayDaysOfTheWeek[] | Each day of the week, localized, available in full, short and narrow formats |
displayMonth | string | Full month name, localized, of the displayed calendar month |
displayYear | string | 4 digit year of the displayed calendar month |
focusedDate | string | The date which currently has focus |
getCalendarContainerProps | function() | Getter to apply attributes, methods & props to the calendar container |
getCalendarDayContainerProps | function() | Getter to apply attributes, methods & props to the calendar day container |
getCalendarWeekContainerProps | function() | Getter to apply attributes, methods & props to the calendar week container |
getDayOfTheWeekProps | function() | Getter to apply attributes, methods & props to the each day of the week |
getDaysOfTheWeekContainerProps | function() | Getter to apply attributes, methods & props to the days of the week container |
getControlsContainerProps | function() | Getter to apply attributes, methods & props to the controls container (prev/next month/year) |
getDatepickerContainerProps | function() | Getter to apply attributes, methods & props to the datepicker container |
getDayButtonProps | function() | Getter to apply attributes, methods & props to the buttons of each day in the calendar |
getMonthYearContainerProps | function() | Getter to apply attributes, methods & props to the month/year container |
getNextMonthButtonProps | function() | Getter to apply attributes, methods & props to the next month button |
getNextYearButtonProps | function() | Getter to apply attributes, methods & props to the next year button |
getOnCloseButtonProps | function() | Getter to apply attributes, methods & props to the hide datepicker button |
getPreviousMonthButtonProps | function() | Getter to apply attributes, methods & props to the previous month button |
getPreviousYearButtonProps | function() | Getter to apply attributes, methods & props to the previous year button |
hoveredDate | string | The date which is currently hovered |
id | string | The id of the datepicker ] |
setMonth | function(number) | Set the month of the year for the calendar in the datepicker, 1 based (1-12) |
setYear | function(number) | Set the 4 digit year for the calendar in the datepicker |
today | string | Today's date in YYYY-MM-DD format |
CalendarDay type
| Property | Type | Description |
|---|---|---|
blocked | boolean | Whether the day is blocked and should not be selectable |
disabled | boolean | Whether the day is disabled and should not be selectable |
displayText | string | The number displayed in each cell of the calendar grid |
formatted | string | The YYYY-MM-DD formatted string of the day |
hovered | boolean | Whether the day is hovered |
index | number | The day of the week index for this particular day (0-6) |
inMonth | boolean | Whether the day is in the visible month |
inRange | boolean | Whether the day is in a selected range (mode: 'range') |
rangeEnd | boolean | Whether the day is the end of the selected range (mode: 'range') |
rangeStart | boolean | Whether the day is the start of the selected range (mode: 'range') |
selected | boolean | Whether the day is selected |
today | boolean | Whether the day is today |
Popover
If the datepicker is going to be contained in a popover, focusOnInit, hasFocusTrap and onClose should be set in useDatepicker for proper operation. The button which shows/hides the datepicker should have aria-haspopup={true}. If an icon is used in the button instead of descriptive text, it should also have the aria-label attribute with an appropriate label. aria-describedby should contain the id of the element which contains the updated selected date if the value of the date needs to be announced when focus is on the open datepicker button.
Localization
Intl.DateTimeFormat is used to automatically localize the days of the week and the months of the year for display if the locale prop is passed with a valid locale. There are labels that can be passed in for various elements which are used by screen readers, and by default English values are supplied, but for other languages, the labels will need to be supplied by your localization system.
Bundling
If your target project is bundled with Webpack, it should use Webpack 5 for proper support of modern Class syntax.
Installation
yarn add rhdpornpm install --save rhdp
Examples
- All defaults, no date pre-selected
- Single date pre-selected
- Range date pre-selected
- Multiple dates pre-selected
- Max multiple dates pre-selected
- Min date and max date set with single date pre-selected
- Blocked dates with single date pre-selected
- Datepicker with button launcher
- Datepicker with editable input
Storybook
yarn
git clone git@github.com:roypearce/rhdp.git
cd rhdp
yarn
yarn storybooknpm
git clone git@github.com:roypearce/rhdp.git
cd rhdp
npm install
npm run storybook