use-date-input

React hooks for building date input and datepicker components.

• useDateInput
• useCalendar
• useDatepicker

Installation

To use this hook you need to install date-fns.

yarn add date-fns
yarn add use-date-input

or with npm:

npm install date-fns
npm install use-date-input

useDateInput

▸ useDateInput(props: UseDateInputProps): UseDateInput

Hook that manages state of masked date input.

Uses IMask for input masking and date-fns for date formatting and parsing.

Props

UseDateInputProps

Name	Type	Description
dateFormat	string	date-fns date format, see https://date-fns.org/v2.22.1/docs/format
maskBlocks?	MaskedDateOptions["blocks"]	Blocks defining each date part, see https://imask.js.org/guide.html#masked-date for more info
onComplete?	(value?: Date) => void	This will execute when input satisfies given format (mask), usually this function should be used to update date value
value?	Date	Date value of input

Return value

UseDateInput

Name	Type	Description
inputValue	string	Value of input element
onKeyPress	KeyboardEventHandler	Apply to input element if you wish to autocomplete date when user presses enter key. Parsing is done using dateFns parse with dateFormat truncated to the length of current inputValue and using current date as reference. For example if today is 07/08/2021 and input value is 2, on enter press, input value will become 02/08/2021
ref	RefObject<HTMLInputElement>	Input element ref
resetValueOnDelete	ChangeEventHandler<HTMLInputElement>	Will call onComplete with undefined value if e.target.value is falsy. Use it to reset value when user deletes the input.
setInputValue	Dispatch<SetStateAction<string>>	Sets inputValue, note that you don't need to set input value on input element change, this is done internally by using IMask's accept event

Usage

// define maskBlocks as constant or memoize in component
const maskBlocks = {
  dd: {
    mask: IMask.MaskedRange,
    from: 1,
    to: 31,
    maxLength: 2,
  },
  MM: {
    mask: IMask.MaskedRange,
    from: 1,
    to: 12,
    maxLength: 2,
  },
  yyyy: {
    mask: IMask.MaskedRange,
    from: 1900,
    to: 9999,
  },
};

const DateInput = () => {
  const [value, setValue] = useState<Date>();
  const { ref, inputValue, resetValueOnDelete } = useDateInput({
    value,
    dateFormat: "dd-MM-yyyy",
    maskBlocks,
    onComplete: setValue,
  });

  return <input ref={ref} value={inputValue} onChange={resetValueOnDelete} />;
};

useCalendar

▸ useCalendar(props: UseCalendarProps): UseCalendar

Manages calendar state.

You can use this hook to render calendar view. Focused date state is used as reference to return calendar days.

Uses date-fns for date manipulation.

Props

UseCalendarProps

Name	Type	Description
maxDate?	Date	Only dates before this date will be marked valid For best performance memoize this date, this will prevent recalculation of calendar days on each render.
minDate?	Date	Only dates after this date will be marked valid. For best performance memoize this date, this will prevent recalculation of calendar days on each render.
startDate?	Date	If provided calendar will start at the month of provided date
validate?	(date: Date) => boolean	Validation function, dates that fail this test will be marked invalid. For best performance memoize this function, this will prevent recalculation of calendar days on each render.
value?	Date	Datepicker value
weekStartsOn?	0 1 2 3 4 5 6	Day that a week starts on. 0 - sunday, 1 - monday ..., default is 0

Return value

UseCalendar

Name	Type	Description
days	UseDatepickerDay[]	Returns all dates that can be seen in calendar view along with flags for each date that indicate if it is in the same month as focused date and if it is valid (available for selection). Use this function to render month view of calendar.
focusedDate	Date	First day of month that represents current calendar view
isSelected	(date: Date) => boolean	Compares given date with value.
months	Date[]	Dates representing each month in the same year as focusedDate. You can use this function render month selection for calendar view.
nextMonth	() => void	Adds one month to focusedDate. Use it to move calendar view to next month.
nextYear	() => void	Adds one year to focusedDate. Use it to move calendar view to next year.
previousMonth	() => void	Subtracts one month from focusedDate. Use it to move calendar view to previous month.
previousYear	() => void	Adds one month to focusedDate. Use it to move calendar view to next month.
setFocusedDate	Dispatch<SetStateAction<Date>>	Changes focusedDate, make sure to only pass first day of the month dates. By changing focusedDate you are actually changing the reference point of calendar which means, once focused date is changed, days and months functions will use new focusedDate value as reference point.
years?	Date[]	Dates representing eachYear from minDate to maxDate. Returns undefined if minDate or maxDate is not defined

UseDatePickerDay

Name	Type	Description
date	Date	Represents calendar day
inMonth	boolean	Indicates if this date is in currently viewed calendar month
isValid	boolean	If true this date can be selected according to provided min and max date and validate function

Usage

const Calendar = () => {
  const [value, setValue] = useState<Date>();
  const { previousYear, nextYear, focusedDate, previousMonth, nextMonth, days, isSelected } = useCalendar({ value });

  return (
    <div style={{ width: "420px" }}>
      <div style={{ width: "100%" }}>
        <button onClick={previousYear}>{"<"}</button>
        {format(focusedDate, "yyyy")}
        <button onClick={nextYear}>{">"}</button>
      </div>
      <div style={{ width: "100%" }}>
        <button onClick={previousMonth}>{"<"}</button>
        {format(focusedDate, "MMMM")}
        <button onClick={nextMonth}>{">"}</button>
      </div>
      <div style={{ display: "flex", flexWrap: "wrap" }}>
        {days.map(({ date, inMonth }) => (
          <button
            disabled={!inMonth}
            style={{ width: "60px", backgroundColor: isSelected(date) ? "aliceblue" : "initial" }}
            key={date.toDateString()}
            onClick={() => setValue(date)}>
            {format(date, "d")}
          </button>
        ))}
      </div>
    </div>
  );
};

useDatepicker

▸ useDatepicker<T>(props: UseCalendarProps & UseDropdownProps): UseCalendar & UseDropdown<T>

Combines useCalendar and useDropdown hooks into one.

Props

Name	Type	Description
additionalRefs?	RefObject<HTMLElement>[]	These refs will be used when determining what constitutes a click outside of dropdown.
disabled?	boolean	If true, open and close will do nothing
onClose?	() => void	Executed when close is called
onOpen?	() => void	Executed when open is called
maxDate?	Date	Only dates before this date will be marked valid For best performance memoize this date, this will prevent recalculation of calendar days on each render.
minDate?	Date	Only dates after this date will be marked valid. For best performance memoize this date, this will prevent recalculation of calendar days on each render.
startDate?	Date	If provided calendar will start at the month of provided date
validate?	(date: Date) => boolean	Validation function, dates that fail this test will be marked invalid. For best performance memoize this function, this will prevent recalculation of calendar days on each render.
value?	Date	Datepicker value
weekStartsOn?	0 1 2 3 4 5 6	Day that a week starts on. 0 - sunday, 1 - monday ..., default is 0

Return value

Name	Type	Description
dropdownRef	RefObject<T>	Ref for dropdown element
isOpen	boolean	Dropdown state
open	() => void	Sets isOpen to true
close	() => void	Sets isOpen to false
days	UseDatepickerDay[]	Returns all dates that can be seen in calendar view along with flags for each date that indicate if it is in the same month as focused date and if it is valid (available for selection). Use this function to render month view of calendar.
focusedDate	Date	First day of month that represents current calendar view
isSelected	(date: Date) => boolean	Compares given date with value.
months	Date[]	Dates representing each month in the same year as focusedDate. You can use this function render month selection for calendar view.
nextMonth	() => void	Adds one month to focusedDate. Use it to move calendar view to next month.
nextYear	() => void	Adds one year to focusedDate. Use it to move calendar view to next year.
previousMonth	() => void	Subtracts one month from focusedDate. Use it to move calendar view to previous month.
previousYear	() => void	Adds one month to focusedDate. Use it to move calendar view to next month.
setFocusedDate	Dispatch<SetStateAction<Date>>	Changes focusedDate, make sure to only pass first day of the month dates. By changing focusedDate you are actually changing the reference point of calendar which means, once focused date is changed, days and months functions will use new focusedDate value as reference point.
years?	Date[]	Dates representing eachYear from minDate to maxDate. Returns undefined if minDate or maxDate is not defined

Usage

const DateInputWithDatepicker = () => {
  const [value, setValue] = useState<Date>();
  const { ref, inputValue, resetValueOnDelete } = useDateInput({
    value,
    dateFormat: "dd-MM-yyyy",
    maskBlocks,
    onComplete: setValue,
  });
  const {
    isOpen,
    open,
    days,
    previousYear,
    nextYear,
    previousMonth,
    nextMonth,
    focusedDate,
    dropdownRef,
    isSelected,
  } = useDatepicker<HTMLDivElement>({
    value,
  });

  return (
    <div ref={dropdownRef}>
      <input ref={ref} value={inputValue} onChange={resetValueOnDelete} onFocus={open} />
      {isOpen && (
        <div style={{ width: "420px" }}>
          <div style={{ width: "100%" }}>
            <button onClick={previousYear}>{"<"}</button>
            {format(focusedDate, "yyyy")}
            <button onClick={nextYear}>{">"}</button>
          </div>
          <div style={{ width: "100%" }}>
            <button onClick={previousMonth}>{"<"}</button>
            {format(focusedDate, "MMMM")}
            <button onClick={nextMonth}>{">"}</button>
          </div>
          <div style={{ display: "flex", flexWrap: "wrap" }}>
            {days.map(({ date, inMonth }) => (
              <button
                disabled={!inMonth}
                style={{ width: "60px", backgroundColor: isSelected(date) ? "aliceblue" : "initial" }}
                key={date.toDateString()}
                onClick={() => setValue(date)}>
                {format(date, "d")}
              </button>
            ))}
          </div>
        </div>
      )}
    </div>
  );
};