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.