Unopinionated React Calendar Component
npm install kalendaryoBuild flexible react date components using primitives :atom_symbol: + :date:fns
>= react@0.14.x``js`
npm i -d kalendaryo // <-- for npm peeps
yarn add kalendaryo // <-- for yarn peeps
jsx
// Step 1: Import the component
import Kalendaryo from 'kalendaryo'// Step 2: Invoke and pass your desired calendar as a function in the render prop
const BasicCalendar = () =>
// Step 3: Build your calendar!
function MyCalendar(kalendaryo) {
const {
getFormattedDate,
getWeeksInMonth,
getDayLabelsInWeek,
setDatePrevMonth,
setDateNextMonth,
setSelectedDate
} = kalendaryo
const currentDate = getFormattedDate("MMMM YYYY")
const weeksInCurrentMonth = getWeeksInMonth()
const dayLabels = getDayLabelsInWeek()
const selectDay = date => () => setSelectedDate(date)
/* For this basic example we're going to build a calendar that has:
* 1. A header where you have:
* 1.1 Controls for moving to the previous/next month of the current date
* 1.2 A label for current month & year of the current date
* 2. A body where you have:
* 2.1 A row for the label of the days of a week
* 2.2 Rows containing the days of each week in the current date's month where you can:
* 2.2.1 Select a date by clicking on a day
*/
return (
// (1)
// (1.1)
// (1.2)
{currentDate}
// (1.1)
// (2)
// (2.1)
{dayLabels.map(label => (
{label}
))}
// (2.2)
{weeksInCurrentMonth.map((week, i) => (
{week.map(day => (
// (2.2.1)
onClick={selectDay(day.dateValue)}
>
{day.label}
))}
))}
See this basic usage snippet in action here!
API
This section contains descriptions of the various things the component has to offer which are split into three parts: *
state: Description of the component's state that could change
* props: Description of the component's props that you can change or hook into
* methods: Description of the component's various helper methods you can use from the render prop$3
#### #date
type: Date
default: new Date()
Is the state for the current date the component is in. By convention, this should only change when the calendar changes its current date, i.e. moving to and from a month or year on the calendar.
#### #selectedDate
type: Date
default: new Date()
Is the state for the selected date on the component. By convention, this should only change when the calendar receives a date selection input from the user, i.e. selecting a day on the calendar.
$3
#### #startCurrentDateAt
type: Date
required: false
default: new Date()
#date. Great for when you want your calendar to boot up in some date other than today.Note: Passing non-
Date types to this prop sets the #date state to today.`jsx
const birthday = new Date(1995, 4, 27)
`
#### #startSelectedDateAt
type: Date
required: false
default: new Date()
. Great for when you want your calendar's selected date to boot up in another date than today.Note: Passing non-
Date types to this prop sets the #selectedDate state to today.`jsx
const birthday = new Date(1988, 4, 27)
`
#### #defaultFormat
type: String
required: false
default: 'MM/DD/YY'
method. Accepts any format that date-fns' format function can support.`jsx
const myFormat = 'yyyy-mm-dd'
`
#### #startWeekAt
type: Number[0..6]
required: false
default: 0
& #getDayLabelsInWeek. Defaults to 0 (sunday)jsx
const monday = 1
`
#### #onChange
type: func(state: Object): void
required: false
& #selectedDate states.`jsx
const logState = (state) => console.log(state)
`
#### #onDateChange
type: func(date: Date): void
required: false
state.`jsx
const logDateState = (date) => console.log(date)
`
#### #onSelectedChange
type: func(date: Date): void
required: false
state.`jsx
const logSelectedDateState = (selectedDate) => console.log(selectedDate)
`
#### #render
type: func(props: Object): void
required: true
Callback prop responsible for rendering the date component. This function receives an object which has the
, methods, as well as props you pass that are invalid(see passing variables to the render prop for more information).`jsx
const MyCalendar = (kalendaryo) => {
console.log(kalendaryo)
return Some layout
}
`
#### Passing variables to the render prop
Sometimes you may need to have states other than the
and #selectedDate state, i.e for a date range calendar component, you may need to have a state for its startDate and endDate and may need to create the calendar component as a method inside the date range calendar's class like so:`jsx
class DateRangeCalendar extends React.Component {
state = {
startDate: null,
endDate: null
} Calendar = (props) => {
const { startDate, endDate } = this.state
return // Your calendar layout
}
setDateRange = (selectedDate) => {
// Logic for updating the start and end date states
}
render() {
return
}
}
`This however, leaves the
component tightly coupled to the DateRangeCalendar component and makes it a little bit harder for us to keep track of what's going on with what.If only we could separate the
DateRangeCalendar's state logic and Calendar's UI renderingTo solve this, the
Kalendaryo component can receive unknown props. These are props that gets passed to the render prop callback when it does not convey any meaning to the Kalendaryo component.With unknown props we can pass any arbitrary variable to
Kalendaryo as long as it does not know what to do with it i.e. the startDate and endDate states. We would then have no need to put the Calendar function inside of the DateRangeCalendar class since the states are now an injected dependency to the Calendar e.g`jsx
class DateRangeCalendar extends React.Component {
state = {
startDate: null,
endDate: null
} setDateRange = (selectedDate) => {
// Logic for updating the start and end date states
}
render() {
return (
endDate={this.state.endDate}
onSelectedChange={this.setDateRange}
render={Calendar}
/>
)
}
}
function Calendar(props) {
const { startDate, endDate } = props
return // Your calendar component
}
`With this, the
and DateRangeCalendar are now separated to the things they're solely responsible for.
$3
#### #getFormattedDate
type: func(date?: Date | format?: String, format?: String): String
throws: Error exception when the types of the given argument are invalid
Returns the date formatted by the given format string. You can invoke this in four ways:
*
getFormattedDate() - Returns the #date state formatted as the value set on the #defaultFormat prop
getFormattedDate(date) - Returns the given date argument* formatted as the value set on the #defaultFormat prop
getFormattedDate(format) - Returns the #date state formatted to the given format string argument*
getFormattedDate(date, format) - Returns the given date argument formatted to the given format string argument*`jsx
function MyCalendar(kalendaryo) {
const birthday = new Date(1988, 4, 27)
const myFormattedDate = kalendaryo.getFormattedDate(birthday, 'yyyy-mm-dd') return
My birthday is at {myFormattedDate}
}
`
#### #getDateNextMonth
type: func(date?: Date | amount?: Number, amount?: Number): Date
throws: Error exception when the types of the given argument are invalid
Returns a date with months added from the given amount. You can invoke this in four ways:
- Returns the #date state with 1 month* added to it
getDateNextMonth(date) - Returns the given date argument with 1 month* added to it
getDateNextMonth(amount) - Returns the #date state with the months added to it from the given amount argument*
getDateNextMonth(date, amount) - Returns the given date argument with the months added to it from the given amount argument*`jsx
function MyCalendar(kalendaryo) {
const nextMonth = kalendaryo.getDateNextMonth()
const nextMonthFormatted = kalendaryo.getFormattedDate(nextMonth, 'MMMM') return
The next month from today is: {nextMonthFormatted}
}
`
#### #getDatePrevMonth
type: func(date?: Date | amount?: Number, amount?: Number): Date
throws: Error exception when the types of the given argument are invalid
Returns a date with months subtracted from the given amount. You can invoke this in four ways:
- Returns the #date state with 1 month* subtracted to it
getDatePrevMonth(date) - Returns the given date argument with 1 month* subtracted to it
getDatePrevMonth(amount) - Returns the #date state with the months subtracted to it from the given amount argument*
getDatePrevMonth(date, amount) - Returns the given date argument with the months subtracted to it from the given amount argument*`jsx
function MyCalendar(kalendaryo) {
const prevMonth = kalendaryo.getDatePrevMonth()
const prevMonthFormatted = kalendaryo.getFormattedDate(prevMonth, 'MMMM') return
The previous month from today is: {prevMonthFormatted}
}
`
#### #getDaysInMonth
type: func(date?: Date): DayObject[]
throws: Error exception when the types of the given argument are invalid
Returns an array of Day Objects for the month of a given date
*
- Returns all the days in the month of the #date state
getDaysInMonth(date) - Returns all the days in the month of the given date argument*`jsx
function MyCalendar(kalendaryo) {
const nextMonth = kalendaryo.getDateNextMonth()
const daysNextMonth = kalendaryo.getDaysInMonth(nextMonth) return (
{daysNextMonth.map((day) => (
onClick={() => console.log(day.dateValue)}
>
{day.label}
))}
)
}
`
#### #getWeeksInMonth
type: func(date?: Date, startingDayIndex?: Number): Week[DayObject[]]
throws: Error exception when the types of the given argument are invalid
Returns an array of weeks, each containing their respective days for the month of the given date
*
- Returns an array of weeks for the month of the #date state, with the weeks starting at the value specified from the #startWeekAt prop
getWeeksInMonth(date) - Returns an array of weeks for the month of the given date argument*, with the weeks starting at the value specified from the #startWeekAt prop
getWeeksInMonth(date, startingDayIndex) - Returns an array of weeks for the month of the given date argument, with the weeks starting at the value specified from the given startingDayIndex argument*`jsx
function MyCalendar(kalendaryo) {
const prevMonth = kalendaryo.getDatePrevMonth()
const weeksPrevMonth = kalendaryo.getWeeksInMonth(prevMonth, 1) return (
{weeksPrevMonth.map((week, i) => (
{week.map((day) => (
onClick={() => console.log(day.dateValue)}
>
{day.label}
))}
))}
)
}
`
#### #getDayLabelsInWeek
type: func(dayLabelFormat?: String): String[]
Returns an array of strings for each day on a week
*
- Returns an array of each day on a week formatted as 'ddd' and starts on
the week index based on the value set on the #startWeekAt prop *
getDayLabelsInWeek(dayLabelFormat) - Returns an array of each day on a week formatted as the given
dayLabelFormat argument and starts on the week index based on the value set on the #startWeekAt prop
#### #setDate
type: func(date: Date): void
throws: Error exception when the types of the given argument are invalid
#date state to the given date`jsx
function MyCalendar(kalendaryo) {
const birthday = new Date(1988, 4, 27)
const currentDate = kalendaryo.getFormattedDate()
const setDateToBday = () => kalendaryo.setDate(birthday) return (
The date is: {currentDate}
)
}
`
#### #setSelectedDate
type: func(selectedDate: Date): void
throws: Error exception when the types of the given argument are invalid
state to the given selected date`jsx
function MyCalendar(kalendaryo) {
const birthday = new Date(1988, 4, 27)
const currentDate = kalendaryo.getFormattedDate()
const selectedDate = kalendaryo.getFormattedDate(kalendaryo.selectedDate)
const selectBdayDate = () => kalendaryo.setSelectedDate(birthday) return (
The date is: {currentDate}
The selected date is: {selectedDate}
)
}
`
#### #pickDate
type: func(date: Date): void
throws: Error exception when the types of the given argument are invalid
& #selectedDate state to the given date`jsx
function MyCalendar(kalendaryo) {
const birthday = new Date(1988, 4, 27)
const currentDate = kalendaryo.getFormattedDate()
const selectedDate = kalendaryo.getFormattedDate(kalendaryo.selectedDate)
const selectBday = () => kalendaryo.pickDate(birthday) return (
The date is: {currentDate}
The selected date is: {selectedDate}
)
}
`
#### #setDateNextMonth
type: func(): void
state by adding 1 month`jsx
function MyCalendar(kalendaryo) {
const formattedDate = kalendaryo.getFormattedDate()
return (
The date today is {formattedDate}
)
}
`
#### #setDatePrevMonth
type: func(): void
state by subtracting 1 month`jsx
function MyCalendar(kalendaryo) {
const formattedDate = kalendaryo.getFormattedDate()
return (
The date today is {formattedDate}
)
}
``
[coveralls-badge]: https://coveralls.io/repos/github/geeofree/kalendaryo/badge.svg
[coveralls]: https://coveralls.io/github/geeofree/kalendaryo
[travis-badge]: https://travis-ci.org/geeofree/kalendaryo.svg?branch=master
[travis]: https://travis-ci.org/geeofree/kalendaryo
[npm-badge]: https://img.shields.io/npm/v/kalendaryo.svg
[npm-dl-badge]: https://img.shields.io/npm/dt/kalendaryo.svg
[npm]: https://www.npmjs.com/package/kalendaryo
[mit]: https://img.shields.io/github/license/mashape/apistatus.svg