Skip to content

Latest commit

 

History

History
152 lines (109 loc) · 9.79 KB

README.md

File metadata and controls

152 lines (109 loc) · 9.79 KB
Raw

📅 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.

npm bundle size code style: prettier All Contributors PRs Welcome jest

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:

Advanced CalendarX Example

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
Michael Fix
💻		Filipe
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.