README
dayzed
Primitives to build simple, flexible, WAI-ARIA compliant React date-picker components.
The problem
You need a date-picker in your application that is accessible, can fit a number of use cases (single date, multi date, range), and has styling and layout that can be easily extended.
This solution
This is a component that focuses on controlling user interactions so you can focus on creating beautiful, accessible, and useful date-pickers. It uses a render function as children. This means you are responsible for rendering everything, but props are provided by the render function, through a pattern called prop getters, which can be used to help enhance what you are rendering.
This differs from other solutions which render things for their use case and then expose many options to allow for extensibility resulting in a bigger API that is less flexible as well as making the implementation more complicated and harder to contribute to.
Table of Contents
- Installation
- Usage
- Props
- Control Props
- Render Prop Function
- Inspiration and Thanks!
- Other Solutions
- Contributors
- LICENSE
Installation
This module is distributed via npm which is bundled with node and
should be installed as one of your project's dependencies
:
npm install --save dayzed
Or, you can install this module through the yarn package manager.
yarn add dayzed
This package also depends on
react
,prop-types
, anddate-fns
. Please make sure you have those installed as well.
Note also this library supports
preact
out of the box. If you are usingpreact
then use the corresponding module in thepreact/dist
folder. You can evenimport Dayzed from 'dayzed/preact'
Usage
import React from 'react';
import Dayzed from 'dayzed';
const monthNamesShort = [
'Jan',
'Feb',
'Mar',
'Apr',
'May',
'Jun',
'Jul',
'Aug',
'Sep',
'Oct',
'Nov',
'Dec'
];
const weekdayNamesShort = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
class Datepicker extends React.Component {
render() {
return (
<Dayzed
onDateSelected={this.props.onDateSelected}
selected={this.props.selected}
render={({
calendars,
getBackProps,
getForwardProps,
getDateProps
}) => {
if (calendars.length) {
return (
<div
style={{ maxWidth: 800, margin: '0 auto', textAlign: 'center' }}
>
<div>
<button {...getBackProps({ calendars })}>Back</button>
<button {...getForwardProps({ calendars })}>Next</button>
</div>
{calendars.map(calendar => (
<div
key={`${calendar.month}${calendar.year}`}
style={{
display: 'inline-block',
width: '50%',
padding: '0 10px 30px',
boxSizing: 'border-box'
}}
>
<div>
{monthNamesShort[calendar.month]} {calendar.year}
</div>
{weekdayNamesShort.map(weekday => (
<div
key={`${calendar.month}${calendar.year}${weekday}`}
style={{
display: 'inline-block',
width: 'calc(100% / 7)',
border: 'none',
background: 'transparent'
}}
>
{weekday}
</div>
))}
{calendar.weeks.map((week, weekIndex) =>
week.map((dateObj, index) => {
let key = `${calendar.month}${
calendar.year
}${weekIndex}${index}`;
if (!dateObj) {
return (
<div
key={key}
style={{
display: 'inline-block',
width: 'calc(100% / 7)',
border: 'none',
background: 'transparent'
}}
/>
);
}
let { date, selected, selectable, today } = dateObj;
let background = today ? 'cornflowerblue' : '';
background = selected ? 'purple' : background;
background = !selectable ? 'teal' : background;
return (
<button
style={{
display: 'inline-block',
width: 'calc(100% / 7)',
border: 'none',
background
}}
key={key}
{...getDateProps({ dateObj })}
>
{selectable ? date.getDate() : 'X'}
</button>
);
})
)}
</div>
))}
</div>
);
}
return null;
}}
/>
);
}
}
class Single extends React.Component {
state = { selectedDate: null };
_handleOnDateSelected = ({ selected, selectable, date }) => {
this.setState(state => ({ selectedDate: date }));
};
render() {
let { selectedDate } = this.state;
return (
<div>
<Datepicker
selected={this.state.selectedDate}
onDateSelected={this._handleOnDateSelected}
/>
{this.state.selectedDate && (
<div style={{ paddingTop: 20, textAlign: 'center' }}>
<p>Selected:</p>
<p>{`${selectedDate.toLocaleDateString()}`}</p>
</div>
)}
</div>
);
}
}
export default Single;
Props
date
date
| defaults tonew Date()
Used to calculate what month to display on initial render.
maxDate
date
| optional
Used to calculate the maximum month to render.
minDate
date
| optional
Used to calculate the minimum month to render.
monthsToDisplay
number
| defaults to1
Number of months returned, based off the date
and offset
props.
firstDayOfWeek
number
| defaults to0
First day of the week with possible values 0-6 (Sunday to Saturday). Defaults to Sunday.
showOutsideDays
boolean
| defaults to false
Flag to fill front and back weeks with dates from adjacent months.
fillAdjacentMonths
boolean
| defaults to false
(Deprecated) Use showOutsideDays instead.
selected
any
| optional
An array of Date
s or a single Date
that has been selected.
onDateSelected
function(selectedDate: date)
| required
Called when the user selects a date.
selectedDate
: The date that was just selected.
render
function({})
| required
This is called with an object. Read more about the properties of this object in the section "Render Prop Function".
offset
number
| control prop (read more about this in the "Control Props" section below) - defaults to0
if not controlled.
Number off months to offset from the date
prop.
onOffsetChanged
function(offset: number)
| control prop (read more about this in the "Control Props" section below)
Called when the user selects to go forward or back. This function is required if offset
is being provided as a prop.
offset
: The number of months offset.
Control Props
dayzed manages its own offset
state internally and calls your onOffsetChanged
handler when the offset changes. Your render prop function (read more below) can be used to manipulate this state from within the render function and can likely support many of your use cases.
However, if more control is needed, you can pass offset
as a prop (as indicated above) and that state becomes controlled. As soon as this.props.offset !== undefined
, internally, dayzed
will determine its state based on your prop's value rather than its own internal state. You will be required to keep the state up to date (this is where the onOffsetChanged
handler comes in really handy), but you can also control the state from anywhere, be that state from other components, redux
, react-router
, or anywhere else.
Note: This is very similar to how normal controlled components work elsewhere in react (like
<input />
). If you want to learn more about this concept, you can learn about that from this the "Controlled Components" lecture
Render Prop Function
This is where you render whatever you want to based on the state of dayzed
.
It's a regular prop called render
: <Dayzed render={/* right here*/} />
.
You can also pass it as the children prop if you prefer to do things that way
<Dayzed>{/* right here*/}</Dayzed>
The properties of this object can be split into two categories as indicated below:
prop getters
These functions are used to apply props to the elements that you render. This
gives you maximum flexibility to render what, when, and wherever you like. You
call these on the element in question (for example: <button {...getDateProps()}
)). It's advisable to pass all your props to that function
rather than applying them on the element yourself to avoid your props being
overridden (or overriding the props returned). For example:
getDateProps({onClick(event) {console.log(event)}})
.
property | type | description |
---|---|---|
getDateProps |
function({}) |
Returns the props you should apply to the date button elements you render. |
getBackProps |
function({}) |
Returns the props you should apply to any back button element you render. |
getForwardProps |
function({}) |
Returns the props you should apply to any forward button element you render. |
state
These are values that represent the current state of the dayzed component.
property | type | description |
---|---|---|
calendars |
any |
An array containing objects of each month's data. |
calendars[{}].month |
number |
Zero-based number of the month. (0 - 11) |
calendars[{}].year |
number |
The year of the month. |
calendars[{}].firstDayOfMonth |
date |
First day of the month. |
calendars[{}].lastDayOfMonth |
date |
Last day of the month. |
calendars[{}].weeks |
any |
An array containing an array of date objects for each week of the month. Starting from Sunday to Saturday. [ ["", "", "", "", dateObj, dateObj, dateObj] ] |
calendars[{}].weeks[[{}]].date |
date |
A Date object for that day of the week. |
calendars[{}].weeks[[{}]].selected |
boolean |
Whether the Date was given as part of the provided selected prop. |
calendars[{}].weeks[[{}]].selectable |
boolean |
Whether the Date is selectable given the provided maxDate and minDate props. |
calendars[{}].weeks[[{}]].today |
boolean |
Whether the Date is today's date. |
calendars[{}].weeks[[{}]].prevMonth |
boolean |
Whether the Date is in the previous month. Useful when the showOutsideDays flag is used. |
calendars[{}].weeks[[{}]].nextMonth |
boolean |
Whether the Date is in the next month. Useful when the showOutsideDays flag is used. |
Inspiration and Thanks!
- Jen Luker
- For help with naming and reviewing this library.
- Kent C. Dodds
- This library borrows heavily from his awesome downshift library!
- Michael Jackson & Ryan Florence
- For teaching the use of the render prop pattern.
Other Solutions
Here are some other great daypicker solutions:
Contributors
Thanks goes to these people (emoji key):
Morgan Kartchner 💻 📖 💡 🤔 👀 ⚠️ |
Jen Luker 💻 💡 🤔 |
Sam Gale 💻 🤔 |
Arthur Denner 💻 🤔 |
Dony Sukardi 💻 💡 ⚠️ |
Amit Solanki 📖 |
---|
This project follows the all-contributors specification. Contributions of any kind welcome!
LICENSE
MIT