calendarx

📅 Calendarx

Your go-to, prescribed, Calendar component for React

Calendarx is a state container that makes creating custom calendar components a breeze. With a simple API, Calendarx makes it easy to display days and events, change views, and advance between the months, weeks, and days.

---

Getting Started

yarn add calendarx

or

npm install calendarx

Example Usage

import Calendar from 'calendarx'

import { Row, Column, Events } from './components'

const events = [{ date: new Date(), id: 'birthday-1' }] // optional

export default () => (
  <Calendar events={events}>
    {({ days, date, goToNext, goToPrev, goToToday }) => (
      <div>
        <Row>
          <span>{date.toDateString()}</span>
          <button onClick={() => goToPrev()}>&lt;</button>
          <button onClick={goToToday}>Today</button>
          <button onClick={() => goToNext()}>&gt;</button>
        </Row>
        {days.map((week, i) => (
          <Row key={i}>
            {week.map((day, j) => (
              <Column key={j}>
                {day.events.map(event => (
                  <Event isToday={day.isToday} key={event.id} {...event} />
                ))}
              </Column>
            ))}
          </Row>
        ))}
      </div>
    )}
  </Calendar>
)

or use as a React hook:

import { useCalendar } from 'calendarx'

export default MyCalendar() {
  const { days } = useCalendar(options)

 // ...
}

for an Advanced example, check out:

Props

Name	Default	Type	Description
children	undefined	Function	Render prop component. See docs below for the options passed
initialDate, date	new Date()	Date, String, Number, Moment	initialDate sets the initial state of date for uncontrolled usage, otherwise use date for controlled usage. Used as the date to center the calendar around
initialNumDays, numDays	35	Number	Number of days the calendar should display. If numDays > 10, this will be raised to the next multiple of 7. Use initialNumDays for uncontrolled usage, numDays for controlled
events	[]	Array<{ date: DateLike } , { startDate: DateLike, endDate: DateLike }>	Events passed into the calendar. These objects will be injected into the correct array by date. Use date for an event on a specific date, and startDate combined with endDate for events spanning multiple dates
weekStartsOn	0	Number[0-6]	Weekday to start the week on. Sunday (0) - Saturday (6)
headers	['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday']	String[]	Replace the headers that get passed to children, for convience
render	undefined	Function	Optional, same as children

Note: the Calendarx days grid will adapt depending on the number of days that are specified in numDays. For example, if 4 is passed in, the first column will start with your initialDate. If 7 is passed in (anything <10), the calendar will align itself to the beginning of the week. If 10 < numDays < 365 (the default is 35), the calendar will align to include the entire month and potentially parts of the previous/next month in order to align the grid with your start of the week (default is Sunday).

Children Properties

The following will be passed to your props.children or props.render function:

Option	Type	Description
days	Day[][]	2-dimensional grid of objects representing each calendar day
date	Date	Current date state
view	String{'year','month','week','day'}	View according to numDays. day if <=4, week if <= 10, month < 365, or year
jump	Function(n: Number, units: {'years','months','weeks','days'})	Function to jump a specific amount of time
goToNext	Function()	Sets date state to next date according to numDays/view
goToToday	Function()	Set the date state to today
goToPrev	Function()	Same as goToNext, but in reverse
goToDate	Function(date: DateLike)	Set date state to arbitrary date

Types

Day

This object contains the following fields/getters:

• date: Date
• events: Event[]
• isToday: Boolean
• isSame(unit: 'year'|'month'|'week'|'day'): Boolean: Function

Event

Events will include the other properties you pass alongside date in your events prop.

Contributing

Please do! If you have ideas, bug fixes, or examples to showcase, please submit a PR/issue.

1. yarn
2. Make your changes
3. yarn test
4. Push a PR

Contributors

Thanks goes to these wonderful people (emoji key):

Michael Fix 💻

Filipe 💻

This project follows the all-contributors specification. Contributions of any kind welcome!

License

MIT

Inspiration 💫

This project was inspired by Kyle Stetz's CLNDR.