@rehookify/datepicker

@rehookify/datepicker

The ultimate tiny tool for creating date, range and time pickers in your React applications.

#StandWithUkraine 💙💛

We have war at our home 🇺🇦

Help us in our struggle, 💰 United24, KOLO, Come Back Alive

Features

• Small size.
• Zero dependencies.
• Modular Hooks will help you to use only what you need.
• You can get accessible component props with prop-getters.
• You have full power to manipulate the state with actions.
• Available as a hook or context.
• Support localization with .toLocaleString, .toLocalTimeString

Install

npm i -S @rehookify/datepicker

📚 Check the Examples

Quickstart: modular use

With modular hooks

import { useState } from 'react';
import { useDatePickerState, useCalendars } from '@rehookify/datepicker';

const DatePicker = () => {
  const [selectedDates, onDatesChange] = useState<Date[]>([]);
  const dpState = useDatePickerState({
    selectedDates,
    onDatesChange,
    dates: { toggle: true, mode: 'multiple' },
  });
  const { calendars, weekDays } = useCalendars(dpState);

  const { month, year, days } = calendars[0];

  return (
    <section>
      <header>
        <div>
          <p>{month} {year}</p>
        </div>
        <ul>
          {weekDays.map((day) => (
            <li key={`${month}-${day}`}>{day}</li>
          ))}
        </ul>
      </header>
      <ul>
        {days.map((dpDay) => (
          <li key={`${month}-${dpDay.day}`}>
            <button>{dpDay.day}</button>
          </li>
        ))}
      </ul>
    </section>
  );
}

With modular context

import { useState } from 'react';
import {
  DatePickerStateProvider,
  useContextCalendars,
  useContextDaysPropGetters,
  useContextTime,
  useContextTimePropGetters,
} from '@rehookify/datepicker';

const DatePicker = () => {
  const { calendars, weekDays } = useContextCalendars();
  const { dayButton } = useContextDaysPropGetters();

  const { year, month, days } = calendars[0];

  return (
    <main>
      <header>
        <div>
          <p>{month} {year}</p>
        </div>
        <ul>
          {weekDays.map((day) => (
            <li key={`${month}-${day}`}>{day}</li>
          ))}
        </ul>
      </header>
      <ul>
        {days.map((dpDay) => (
          <li key={`${month}-${dpDay.day}`}>
            <button {...dayButton(dpDay)}>{dpDay.day}</button>
          </li>
        ))}
      </ul>
    </main>
  )
}

const TimePicker = () => {
  const { time } = useContextTime();
  const { timeButton } = useContextTimePropGetters();

  return (
    <ul>
      {time.map((t) => (
        <li key={t.$date.toString()}>
          <button {...timeButton(t)}>{t.time}</>
        </li>
      ))}
    </ul>
  )
}

const App = () => {
  const d = new Date();
  const [selectedDates, onDatesChange] = useState<Date[]>([d]);
  return (
    <DatePickerStateProvider
      config={{
        selectedDates,
        focusDate: d,
        onDatesChange,
        dates: { mode: 'multiple' },
      }}
    >
      <section>
        <DatePicker />
        <TimePicker />
      </section>
    </DatePickerStateProvider>
  );
}

Quickstart: everything in one place

With hook

import { MouseEvent, useState } from 'react';
import { useDatePicker } from '@rehookify/datepicker';

const DatePicker = () => {
  const [selectedDates, onDatesChange] = useState<Date[]>([]);
  const {
    data: { weekDays, calendars },
    propGetters: {
      dayButton,
      previousMonthButton,
      nextMonthButton,
    },
  } = useDatePicker({
    selectedDates,
    onDatesChange,
  });

  // calendars[0] is always present, this is an initial calendar
  const { year, month, days } = calendars[0];

  const onDayClick = (evt: MouseEvent<HTMLElement>, date: Date) => {
    // In case you need any action with evt
    evt.stopPropagation();

    // In case you need any additional action with date
    console.log(date);
  }

  // selectedDates is an array of dates
  // formatted with date.toLocaleDateString(locale, options)
  return (
    <section>
      {selectedDates.length > 0 && <h1>{selectedDates[0]}</h1>}
      <header>
        <div>
          <button {...previousMonthButton()}>&lt;</button>
          <p>{month} {year}</p>
          <button {...nextMonthButton()}>&gt;</button>
        </div>
        <ul>
          {weekDays.map((day) => (
            <li key={`${month}-${day}`}>{day}</li>
          ))}
        </ul>
      </header>
      <ul>
        {days.map((dpDay) => (
          <li key={`${month}-${dpDay.day}`}>
            <button
              {...dayButton(dpDay, { onClick: onDayClick })}
            >
              {dpDay.day}
            </button>
          </li>
        ))}
      </ul>
    </section>
  )
}

With context

import { useState } from 'react';
import {
  DatePickerProvider,
  useDatePickerContext,
} from '@rehookify/datepicker';

const DatePicker = () => {
  const {
    data: { weekDays, calendars, years, months },
  } = useDatePickerContext();

  const { year, month, days } = calendars[0];

  return (
    <section>
      <header>{month} {year}</header>
      ...
    </section>
  )
}

const App = () => {
  const [selectedDates, onDatesChange] = useState<Date[]>([]);

  return (
    <DatePickerProvider
      config={{
        selectedDates,
        onDatesChange,
        dates: { mode: 'range' },
      }}
    >
      <DatePicker />
    </DatePickerProvider>
  );
}

API reference

• State
  • data
    • calendars
    • weekDays
    • months
    • years
    • selectedDates
    • formattedDates
    • time
  • propGetters
    • dayButton
    • monthButton
    • nextMonthButton
    • previousMonthButton
    • yearButton
    • nextYearsButton
    • previousYearsButton
    • timeButton
  • actions
    • setMonth
    • setYear
    • setNextYears
    • setPreviousYears
    • setNextMonth
    • setPreviousMonth
• Configuration
  • Default configuration
  • General configuration
  • Locale configuration
  • Calendar configuration
  • Dates configuration
  • Years configuration
  • Time configuration
• Modular Hooks
  • useDatePickerState
  • useCalendars
  • useDays
  • useDaysPropGetters
  • useMonths
  • useMonthsPropGetters
  • useMonthsActions
  • useTime
  • useTimePropGetters
  • useYears
  • useYearsPropGetters
  • useYearsActions
  • Context Hooks

State

The state consists of three main parts: data, propGetters and actions.

Data

The data represents all entities that you could use in your date picker. It consists of calendars, weekDays, months, years, selectedDates and time

interface Data {
  calendars: Calendar[];
  formattedDates: Date[];
  months: CalendarMonth[];
  selectedDates: Date[];
  time: Time[];
  weekDays: string[];
  years: CalendarYears[];
}

calendars

calendars are an array of objects with year, month and days properties. It always has at least one member - an initial calendar calendars[0]. For calendars configuration 👀 Calendar config

export type DayRange =
  | 'in-range'
  | 'range-start'
  | 'range-end'
  | 'range-start range-end'
  | 'will-be-in-range'
  | 'will-be-range-start'
  | 'will-be-range-end'
  | '';

interface CalendarDay {
  $date: Date;
  day: string;
  disabled: boolean;
  inCurrentMonth: boolean;
  now: boolean;
  range: DayRange;
  selected: boolean;
}

interface Calendar {
  days: CalendarDay[];
  month: string;
  year: string;
}

weekDays

Weekdays are an array of day names [Mon, Tue, Wed, ...]. The name format can be changed by locale.weekdays property 👀 Locale configuration

type Weekdays = string[]

months

Months are an array of objects with $date, active, disabled, month, now and selected properties. The month name format could be changed by locale.monthName property 👀 Locale configuration.

interface CalendarMonth {
  $date: Date;
  active: boolean;
  disabled: boolean;
  month: string;
  now: boolean;
  selected: boolean;
}

active - shows that a user sees this month as current.

month - month name e.g 'December'

now - shows that this month is current in real life

selected - shaws that we have a date selected for this month.

years

Years are an array of objects with $date, active, disabled, now, selected and year properties.

interface CalendarYear {
  $date: Date;
  active: boolean;
  disabled: boolean;
  now: boolean;
  selected: boolean;
  year: number;
}

active - shows that a user sees this year as current.

now - shows that this year is current in real life

selected - shows that we have a date selected for this year.

year - year value e.g 2023

selectedDates

An array of raw dates

type SelectedDates = Date[];

formattedDates

An array of formatted dates date.toLocaleDateString(locale, options) 👀 Locale configuration

type FormattedDates = string[];

time

Time is an array of objects with $date, disabled, now, selected and value properties. You can change time format with hour12, hour and minute options 👀 Locale configuration

export interface Time {
  $date: Date;
  disabled: boolean;
  selected: boolean;
  time: string;
}

time - time value e.g 15:30 or 3:30 pm

Prop-Getters

A prop-getters is a pattern that allows you to get all the necessary pops and logic for your components. It gives you the possibility to pass additional configuration. @rehookify/datepicker composes onClick and calls it with event and date - onClick(event, date).

Each prop-getter accepts a configuration object to enhance the properties and functionality of the component.

interface PropsGetterConfig extends Record<string, unknown> {
  onClick?(evt?: MouseEvent<HTMLElement>, date?: Date): void;
  disabled?: boolean;
}

Each prop-getter returns an object with properties:

interface PropGetterReturnValue extends Omit<PropsGetterConfig, 'onClick' | 'disabled'>{
  role: 'button',
  tabIndex: 0,
  disabled: boolean,
  'area-disabled': boolean;
  onClick?(evt: MouseEvent<HTMLElement>),
}

dayButton

dayButton produces properties for calendar days and sets the selectedDates state when a user clicks on a day.

Params:

• day: Calendar - you could get it from the calendars 👆 #Calendars
• props?: PropsGetterConfig

Returns:

interface DayButtonReturnValue extends PropGetterReturnValue {
  onMouseEnter?(): void;
}

✏️ NOTE: onMouseMove - appears only if dates mode is range, it is not composable. 👀 Dates configuration

monthButton

monthButton produces properties for calendar months and changes month when a user clicks on a month.

Params:

• month: CalendarMonth - you could get it from the months 👆 Months
• props?: PropsGetterConfig

nextMonthButton

nextMonthButton moves months pagination one step forward.

Params:

• props?: PropsGetterConfig

previousMonthButton

previousMonthButton moves months pagination one step backward.

Params:

• props?: PropsGetterConfig

yearButton

yearButton produces properties for calendar years and changes the year when user clicks on a year.

Params:

• year: CalendarYear - you could get it from the years 👆 Years
• props?: PropsGetterConfig

nextYearsButton

nextYearsButton moves years pagination one step forward.

Params:

• props?: PropsGetterConfig

✏️ NOTE: onClick - callback function doesn't get date as a second parameter.

previousYearsButton

previousYearsButton moves years pagination one step backward.

Params:

• props?: PropsGetterConfig

✏️ NOTE: onClick - callback function doesn't get date as a second parameter.

timeButton

timeButton produces properties for time button and changes corresponding selectedDate and focusDate.

Params:

• time: Time - you could get it from the years 👆 Time
• props?: PropsGetterConfig

Params:

• props?: PropsGetterConfig

✏️ NOTE: onClick - callback function doesn't get date as a second parameter.

Actions

Actions allow you to control the date picker's state. They don't have any additional logic. You need to check the state of days, months and years or disable the months and years pagination buttons.

setMonth

setMonth - set the month that a user sees.

Params:

• date: Date - javascript Date object, you could get it from the month.$date 👆 Months, or create new Date(2022, 10, 18)

setNextMonth

setNextMonth adds one month to current

setPreviousMonth

setPreviousMonth subtracts one month from current

setYear

setYear set the year that user sees

Params:

• date: Date - javascript Date object, you could get it from the year.$date 👆 Years, or create new Date(2022, 10, 18)

setNextYears

setNextYears moves years pagination one step forward

setPreviousYears

setPreviousYears moves years pagination one step backward

Configuration

useDatePicker, DatePickerProvider, useDatePickerState and DatePickerStateProvider accepts same configuration object that consists of locale, calendar, dates and years

Default configuration

{
  selectedDates: [],
  focusDate: null,
  onDatesChange: undefined,
  dates: {
    mode: 'single',
    selectedDates: [],
    minDate: null,
    maxDate: null,
    toggle: false,
    limit: undefined,
  },
  calendar: {
    mode: 'static',
    offsets: [0],
  },
  locale: {
    locale: 'en-GB',
    day: '2-digit',
    year: 'numeric',
    weekday: 'short',
    monthName: 'long',
    hour: '2-digit',
    minute: '2-digit',
    hour12: undefined,
    second: undefined,
  },
  time: {
    interval: 30,
    minTime: null,
    maxTime: null,
  },
  years: {
    mode: 'decade',
    numberOfYears: 12;
    step: 10,
  },
}

General configuration

selectedDates: Date[];
focusDate: Date | null;
onDatesChange(d: Date[]): void;

The date-picker is a controlled component that utilizes the selectedDates property to create all entities and display the user's selection. If you don't provide a selectedDates value, it will default to an empty array, but the selection won't be visible. Every time a date is selected, it will be passed to the onDatesChange function.

A typical setup is to use the useState hook to handle updates.

const [selectedDates, onDatesChange] = useState<Date[]>([]);
const { data } = useDatePicker({
  selectedDates,
  onDatesChange,
})

focusDate is initial value for the time-picker, if it is null or not present in the selectedDates array all time buttons will be disabled.

Locale configuration

Locale configuration consists of values compatible with date.toLocaleString().

For more information about locale you can reed at MDN doc.

interface LocaleConfig {
  locale?: Intl.LocalesArgument;
  options?: Intl.DateTimeFormatOptions;
  day?: Intl.DateTimeFormatOptions['day'];
  year?: Intl.DateTimeFormatOptions['year'];
  monthName?: Intl.DateTimeFormatOptions['month'];
  weekday?: Intl.DateTimeFormatOptions['weekday'];
  hour: Intl.DateTimeFormatOptions['hour'];
  minute: Intl.DateTimeFormatOptions['minute'];
  second?: Intl.DateTimeFormatOptions['second'];
  hour12?: Intl.DateTimeFormatOptions['hour12'];
}

• locale: UnicodeBCP47LocaleIdentifier | Locale | (UnicodeBCP47LocaleIdentifier | Locale)[] | undefined - used to format all instances, a string with a BCP 47 language tag.
• options: Intl.DateTimeFormatOptions it is left undefined to allow you to control how selectedDates will formatted.
• day: "2-digit" | "numeric" | undefined - defines the date's format in Calendars
• year: "numeric" | "2-digit" | undefined - defines the year's format in Years
• monthName: "numeric" | "2-digit" | "long" | "short" | "narrow" | undefined - defines the moths format in Months
• weekday: "long" | "short" | "narrow" | undefined - defines weekday's format in Weekdays
• hour: "numeric" | "2-digit" | undefined - defines hours format in Time
• minute: "numeric" | "2-digit" | undefined - defines minutes format in Time
• second: "numeric" | "2-digit" | undefined - defines seconds format in Time
• hour12: boolean | undefined - defines time format in general 12:12 or 12:12 pm

Calendar configuration

interface CalendarConfig {
  mode?: 'static' | 'fluid';
  offsets?: number[];
  startDay: 0 | 1 | 2 | 3 | 4 | 5 | 6;
}

• mode: 'static' | 'fluid' controls how calendar will look like

Calendars in static mode have 6 rows by 7 days. This prevents UI from jumping while switching between months and years.

🗓 February 2022 in static mode:

30 31 01 02 03 04 05
06 07 08 09 10 11 12
13 14 15 16 17 18 19
20 21 22 23 24 25 26
27 28 01 02 03 04 05
06 07 08 09 10 11 12

Calendars in fluid mode counts start and end offsets.

🗓 February 2022 in fluid mode:

30 31 01 02 03 04 05
06 07 08 09 10 11 12
13 14 15 16 17 18 19
20 21 22 23 24 25 26
27 28 01 02 03 04 05

• offsets: number[] - adds additional calendars to the Calendars;

The first calendar is always [0] - offsets comes next.

The values of offsets could be negative, -1, this will add month before current.

offsets: [-1, 1] gives you 3 calendars November, October, December (today is November 2022).

startDay - The day of the week that will be the first in the calendar. It accepts a number in the range of 0-6, where 0 represents Sunday and 6 represents Saturday.

Dates configuration

interface DatesUserConfig {
  mode?: 'single' | 'multiple' | 'range';
  minDate?: Date;
  maxDate?: Date;
  selectedDates?: Date | Date[];
  toggle?: boolean;
  limit?: number;
}

• mode: 'single' | 'multiple' | 'range' - defines how date picker behaves with days

single - a user can pick only 1 date

multiple - a user can pick unlimited number of dates until limit is set

range - a user can pick one dates range. selectedDates will have 2 dates

• minDate: Date - all dates in prop-getters before the minDate will be marked as disabled.

✏️ NOTE: if minDate > NOW - initial calendar will show the month with minDate

• maxDate: Date - all dates in prop-getters after the maxDate will be marked as disabled.

✏️ NOTE: if maxDate < NOW - initial calendar will show the month with maxDate

• selectedDates: Date | Date[] - dates that will be added to selectedDates state.

✏️ NOTE: If mode: 'single' - after the first click selectedDates will be reset to 1 date.

• toggle: boolean - allows a user to unselect dates.
• limit: number - number of dates that a user could select.

✏️ NOTE: works only with mode: 'multiple'

Time configuration

export interface TimeLimit {
  h: number;
  m: number;
}
export interface TimeConfig {
  interval: number;
  minTime: TimeLimit;
  maxTime: TimeLimit;
}

• interval - time segments value in minutes for example, interval 30 is 48 segments 2 for each hour

• minTime - all times in prop-getters before the minTime will be marked as disabled

• maxTime - all times in prop-getters after the maxTime will be marked as disabled

✏️ NOTE: config will sort minTime and maxTime if both present.

Years configuration

type YearsMode = 'decade' | 'fluid';

interface YearsConfig {
  mode: YearsMode,
  numberOfYears: number;
  step: number;
},

• numberOfYears: number - the number of years you want to show to a user.
• mode: 'decade' | 'fluid' | 'exact' - it defines how current year will be centered;

✏️ NOTE: difference between decade and fluid mode

Years matrix for decade mode.

It will count current decade (for 2022 is 2020-2029) and adds end of the previous and start of the next decade

2019 2020 2021
2022 2023 2024
2025 2026 2027
2028 2029 2030

Years matrix for fluid mode.

It will place current year in the middle of the list -1 (we want to look at the future more) 😉

2017 2018 2019
2020 2021 2022
2023 2024 2025
2026 2027 2028

Years matrix for exact mode.

It will place current year at the end of the list

2012 2013 2014
2015 2016 2017
2018 2019 2020
2021 2022 2023

• step: number - it defines step for previous/nextYearsButton

Modular Hooks

The main aim of modular hooks is to safe bundle size of your app.

All entities are consists of 3 hooks: data, prop-getters and actions (for example useDays, useDaysPropGetters and useDaysActions).

useDatePickerState

interface State {
  config: DatePickerConfig;
  focusDate: Date | null;
  offsetDate: Date;
  offsetYear: number;
  rangeEnd: Date | null;
}

type Action =
  | SetFocusDate
  | SetOffsetDate
  | SetYearAction
  | SetRangeEndAction;

type DPState = {
  dispatch: Dispatch<Action>;
  selectedDates: Date[];
  state: State;
}

type UseDatePickerState = (config: DatePickerConfig) =>
  DPState;

Under the hook, it uses useReducer to capture date-picker state and provides dispatch for state manipulation.

Modular hooks use state and dispatch to derive their entities and update the date-picker.

DatePickerStateProvider uses this hook and propagates state and dispatch through context.

type DatePickerStateProviderValue = DPState;

useCalendars

type UseCalendars = (state: DPState) => {
  calendars: Calendar[];
  weekDays: string[];
}

• calendars - 👀 calendars
• weekDays - 👀 weekDays

Basic entities to build UI without interactivity.

useDays

type UseDays = (state: DPState) => {
  selectedDates: Date[];
  formattedDates: string[];
};

Set of data with raw and formatted dates

• selectedDates - 👀 selecteDates
• formattedDates - 👀 formattedDates

useDaysPropGetters

type UseDaysPropGetters = (state: DPState) => {
  dayButton(day: CalendarDay, config: PropsGetterConfig): void;
};

Prop-getter for dates selection.

• dayButton - propGetter 👀 dayButton

useMonths

type UseMonths = (state: DPState) => {
  months: CalendarMonth[],
};

Months data.

• months - 👀 months

useMonthsPropGetters

type UseMonthsPropGetters = (state: DPState) => {
  monthButton(month: CalendarMonth, config: PropsGetterConfig): void,
  nextMonthButton(config: PropsGetterConfig): void,
  previousMonthButton(config: PropsGetterConfig): void,
};

Prop-getters for month manipulation.

• monthButton - propGetter 👀 monthButton
• nextMonthButton - propGetter 👀 nextMonthButton
• previousMonthButton - propGetter 👀 previousMonthButton

useMonthsActions

type UseMonthsActions = (state: DPState) => {
  setMonth(date: Date): void,
  setNextMonth(): void,
  setPreviousMonth(): void,
};

Actions for month manipulation.

• setMonth - action 👀 setMonth
• setNextMonth - action 👀 setNextMonth
• setPreviousMonth - action 👀 setPreviousMonth

useTime

type UseTime = (state: DPState) => {
  time: Time[]
};

Years data.

• time - 👀 Time

useTimePropGetters

type UseTimePropGetters = (state: DPState) => {
  timeButton(time: Time, config: PropsGetterConfig): void,
};

Prop-getters for time manipulation.

• timeButton - propGetter 👀 timeButton

useYears

type UseYears = (state: DPState) => {
  years: CalendarYear[]
};

Years data.

• years - 👀 years

useYearsPropGetters

type UseYearsPropGetters = (state: DPState) => {
  yearButton(year: CalendarYear, config: PropsGetterConfig): void;
  nextYearsButton(config: PropsGetterConfig): void;
  previousYearsButton(config: PropsGetterConfig): void;
};

Prop-getters for years manipulation.

• yearButton - propGetter 👀 yearButton
• nextYearsButton - propGetter 👀 nextYearsButton
• previousYearsButton - propGetter 👀 previousYearsButton

useYearsActions

type UseYearsActions = (state: DPState) => {
  setYear(date: Date): void;
  setNextYears(): void;
  setPreviousYears(): void;
};

Actions for years manipulation.

• setYear - action 👀 setYear
• setNextYears - action 👀 setNextYears
• setPreviousYears - action 👀 setPreviousYears

Context Hooks

We have set of context hooks that have similar API with regular one.

• useContextCalendars - 👀 useColendars
• useContextDays - 👀 useDay
• useContextDaysPropsGetters - 👀 useDayPropGetters
• useContextMonths - 👀 useMonths
• useContextMonthsPropGetters - 👀 useMonthsPropGetters
• useContextMonthsActions - 👀 useMonthsActions
• useContextTime - 👀 useTime
• useContextTimePropGetters - 👀 useTimePropGetters
• useContextYears - 👀 useYears
• useContextYearsPropGetters - 👀 useYearsPropGetters
• useContextYearsActions - 👀 useYearsActions

The main difference that they use context value from the DatePickerStateProvider. You don't need to pass any parameters to them.

✏️ NOTE: You can use them only inside DatePickerStateProvider! 👀 With modular context