react-calendar-carousel

Calendar carousal is a mobile friendly component which give emphasis on selected date and time, you might have seen similar examples in booking related websites where selected dates must remain visible at all times for good UX.

Table of contents

• Project Name
  • Table of contents
  • Installation
  • Usage
  • API
    • Components
      • CalendarConfigProvider
      • Calendar
    • Hooks
      • useCalendar
    • Custom Types
      • IDate
      • Formats
      • CardBreakpoint
      • ClosedHoursRange
      • Selected
      • CalendarTheme
        • AliasToken
        • CustomStyles
      • PanelsToShow
    • Utils
      • getDatesFromRange
      • getDurationInHours
      • getFormattedDate
      • getFormattedTime
  • Built With
  • License

Installation

You can install react-calendar-carousel using npm.

npm i react-calendar-carousel --save

Usage

import Calendar, { CalendarConfigProvider } from 'react-calendar-carousel'

const MyCalendarComponent = () => {
  return (
    <CalendarConfigProvider>
      <Calendar />
    </CalendarConfigProvider>
  )
}

export default MyCalendarComponent

API

The Calendar component can be used by wrapping it in the CalendarConfigProvider, both imported from react-calendar-carousel. All of the calendar’s state management and date logic are bundled in useCalendar custom hook.

Components 

CalendarConfigProvider

Prop	Description	Type	Default
dates	The dates displayed in the Carousel	DateRange	One week
durationStep	The minutes by which duration should increase or decrease by	number	15
formats	The display format for date, time, and clock	Formats	-
minDuration	Lower threshold for the duration (in minutes)	number	60
maxDuration	Upper threshold for the duration (in minutes)	number	180
cards	Amount of cards per screen to be displayed	CardBreakpoint	-
closedDate	Function that specifies the dates that cannot be selected	(date: Dayjs) => boolean	false
closedHours	Hours that should be closed	ClosedHoursRange	-
theme	Theme for the calendar and the components within	CalendarTheme	-

Calendar

Prop	Description	Type	Default
panelsToShow	Panels that will be filtered out or not shown	PanelsToShow	-
activePanels	What panels should initially be opened	string | string[]	['1', '2']
dateComponent	Component that will replace the card carousel	ReactNode	-
timeComponent	Component that will replace the time picker	ReactNode	-
durationComponent	Component that will replace the duration setter	ReactNode	-

Hooks 

useCalendar

This custom hook provides access to all the state values of the package, along with the functions to update the state.

Name	Description	Type
selected	Selected date, time, and duration	Selected
setDate	Function to update the selected date	(date: Dayjs) => void
setTime	Function to update the selected time	(time: Dayjs) => void
increaseDuration	Function to increase the selected duration	(offset: number) => number
decreaseDuration	Function to decrease the selected duration	(offset: number) => number
dates	The dates displayed in the carousel	IDate[]
durationStep	The minutes by which duration should increase or decrease by	number
formats	The display format for date, time, and clock	Formats
minDuration	Lower threshold for the duration (in minutes)	number
maxDuration	Upper threshold for the duration (in minutes)	number
cards	Amount of cards per screen to be displayed	CardBreakpoint
closedDate	Function that specifies the dates that cannot be selected	(date: Dayjs) => boolean
closedHours	Hours that should be closed	ClosedHoursRange

Custom Types

DateRange

Range of dates given by start and end.

type DateRange = {
  start: Dayjs
  end: Dayjs
}

IDate

Date entry with its associated information.

type IDate = {
  date: Dayjs
  closed?: boolean
}

Formats

Display format for the date, time and allow the selection of 12 or 24 hour format.

type Formats = {
  date: string /** @default "DD MMMM YYYY"*/
  time: string /** @default "hh:mm a" */
  clock: '12h' | '24h' /** @default "12h" */
}

CardBreakpoint

Number of cards to display per slide based on the different screen sizes.

export type CardBreakpoint = {
  xs: number /** @default 1 */
  sm: number /** @default 4 */
  md: number /** @default 6 */
  lg: number /** @default 8 */
  xl: number /** @default 10 */
  xxl: number /** @default 14 */
}

ClosedHoursRange

Range of closed hours, including start and end.

type ClosedHoursRange = {
  start: number
  end: number
}

Selected

export type Selected = {
  date: Dayjs | null
  time: Dayjs | null
  duration: number /** @default average(minDuration, maxDuration)*/
}

CalendarTheme

type CalendarTheme = {
  isDark: boolean /**@default false */
  general?: Partial<AliasToken>
  custom?: Partial<CustomStyles>
}

AliasToken

general styles are applied using Ant Design tokens. More info here. The general styles are inherited if a custom property is not provided.

CustomStyles

custom styles allow for component-specific customization. Below are the styles that can be applied.

Name	Description	Type
colorCardHeader	Header color for open date cards	string
colorCardHeaderDisabled	Header color for closed date cards	string
colorCardHeaderText	Text color for date card header	string
colorCardBodyText	Text color for date card body	string
colorButton	Color for the buttons that update duration	string
colorTimePicker	Color for the TimePicker component	string
cardGap	Gap between the date cards in the carousel	number
buttonBorderRadius	Border radius of buttons that update duration	number
carouselWidth	Width of the entire Calendar component	number

PanelsToShow

export type PanelsToShow = {
  date?: boolean /** @default true */
  time?: boolean /** @default true */
  duration?: boolean /** @default true */
}

Utils

getDatesFromRange

returns: IDate[]
Get a list of dates by providing a range of dates.

Param	Description	Type
range	Range of dates	DateRange
closedDate	Function that specifies the dates that cannot be selected	(date: Dayjs) => boolean

getDurationInHours

returns: string
Convert minutes into hour representation.

Param	Description	Type
minutes	The duration in minutes	number

getFormattedDate

returns: string
Convert date to a formatted string.

Param	Description	Type
date	The date to format	Dayjs | null
format	The format to return	string

getFormattedTime

returns: string
Convert time to a formatted string.

Param	Description	Type
time	The time to format	Dayjs | null
format	The format to return	string

Built With

• React + TypeScript using Vite
• Dayjs
• Ant Design

License

Copyright © 2023 Hassam Ud Din.
This project is MIT licensed.