A modern and responsive react timeline component.
A modern and responsive react timeline component.
A modern and responsive React timeline component.
Version 0.30.0-beta.17 Now Available!
We're excited to announce the beta release of v0.30.0 which includes:
moment.js replaced with dayjs (much smaller bundle)height override propitemVerticalGap timeline prop for consistent spacing between itemsdayjs dependency with locale supportThe beta version is available via:
npm install react-calendar-timeline@beta
We encourage users to try out the beta and provide feedback before the stable release. Please report any issues on GitHub.
The latest stable release is 0.28.0. If you are not ready to upgrade to the beta, install the stable version:
npm install react-calendar-timeline
The stable version uses moment.js as its date library. For stable version documentation, refer to the 0.28.0 README.
The rest of this README documents the 0.30.0 beta API.
moment has been replaced with dayjs. Update your peer dependency and all date-related code accordingly.'react-calendar-timeline/lib/Timeline.css' is now 'react-calendar-timeline/style.css'immutableJS arrays are no longer supported — use plain JavaScript arrays@types/react-calendar-timeline)Checkout the examples here!
# via yarn
yarn add react-calendar-timeline
# via npm
npm install --save react-calendar-timeline
react-calendar-timeline has react, react-dom, dayjs and interactjs as peer dependencies.
At the very minimum:
…
NB! All props need to be immutable. For example, this means if you wish to change the title of one of your items, please pass in a whole new items array instead of changing the title in the old array. Here's more info.
The component can take many props:
Expects an array of objects with the following attributes:
{
id: 1,
title: 'group 1',
rightTitle: 'title in the right sidebar',
stackItems?: true,
height?: 30
}
If you use the right sidebar, you can pass optional rightTitle property here.
If you want to overwrite the calculated height with a custom height, you can pass a height property as an int in pixels here. This can be very useful for categorized groups.
Expects an array of objects with the following attributes:
{
id: 1,
group: 1,
title: 'Random title',
start_time: 1457902922261,
end_time: 1457902922261 + 86400000,
canMove: true,
canResize: false,
canChangeGroup: false,
itemProps: {
// these optional attributes are passed to the root
{itemContext.useResizeHandle ?
)}
}
React component that will be used to render the content of groups in the
sidebar. Will be passed the group and isRightSidebar as props.
let groups = [
{
id: 1,
title: 'Title',
tip: 'additional information'
}
]
groupRenderer = ({ group }) => {
return (
)
}
The component automatically detects when the window has been resized. Optionally you can also detect when the component's DOM element has been resized.
To do this, pass a resizeDetector. Since bundling it by default would add ~18kb of minimized JS, you need to opt in to this like so:
import containerResizeDetector from 'react-calendar-timeline/lib/resize-detector/container'
<Timeline resizeDetector={containerResizeDetector} ... />
This function is called when the vertical line is rendered. start and end are unix timestamps in milliseconds for the current column. The function should return an array of strings containing the classNames which should be applied to the column. This makes it possible to visually highlight e.g. public holidays or office hours.
An example could look like (see: demo/vertical-classes):
verticalLineClassNamesForTime = (timeStart, timeEnd) => {
const currentTimeStart = dayjs(timeStart)
const currentTimeEnd = dayjs(timeEnd)
for (let holiday of holidays) {
if (
holiday.isSame(currentTimeStart, 'day') &&
holiday.isSame(currentTimeEnd, 'day')
) {
return ['holiday']
}
}
}
Be aware that this function should be as optimized for performance as possible as it will be called on each render of the timeline (i.e. when the canvas is reset, when zooming, etc)
This function is called when the horizontal line is rendered. group is the group which will be rendered into the current row. The function should return an array of strings containing the classNames which should be applied to the row. This makes it possible to visually highlight categories or important items.
An example could look like:
horizontalLineClassNamesForGroup={(group) => group.root ? ["row-root"] : []}
Timeline markers are markers that are overlayed on the canvas at specific datepoints.
Markers can be placed in the Timeline by declaring them as children of the Timeline component:
import Timeline, {
TimelineMarkers,
CustomMarker,
TodayMarker,
CursorMarker
} from 'react-calendar-timeline'
<Timeline>
<TimelineMarkers>
<TodayMarker />
<CustomMarker date={today} />
<CustomMarker date={tomorrow}>
{/* custom renderer for this marker */}
{({ styles, date }) => {
const customStyles = {
...styles,
backgroundColor: 'deeppink',
width: '4px'
}
return
}}
</SidebarHeader>
<DateHeader unit="primaryHeader" />
<DateHeader />
</TimelineHeaders>
</Timeline>
Custom headers are implemented through a set of component with mostly function as a child component pattern, designed to give the user the most control on how to render the headers.
TimelineHeaderIs the core component wrapper component for custom headers
style
object
applied to the root component of headers
className
string
applied to the root component of the headers
calendarHeaderStyle
object
applied to the root component of the calendar headers -scrollable div- DateHeader and CustomHeader)
calendarHeaderClassName
string
applied to the root component of the calendar headers -scrollable div- DateHeader and CustomHeader)
headerRef
function
used to get the ref of the header element
SidebarHeaderResponsible for rendering the headers above the left and right sidebars.
variant
left (default), right
renders above the left or right sidebar
children
Function
function as a child component to render the header
headerData
any
Contextual data to be passed to the item renderer as a data prop
a Function provides multiple parameters that can be used to render the sidebar headers
Prop getters functionsRather than applying props on the element yourself and to avoid your props being overridden (or overriding the props returned). You can pass an object to the prop getters to avoid any problems. This object will only accept some properties that our component manage so the component make sure to combine them correctly.
property type descriptiongetRootProps
function(props={})
returns the props you should apply to the root div element.
data
any
Contextual data passed by headerData prop
getRootProps The returned props are:
These properties can be override using the prop argument with properties:
import Timeline, {
TimelineHeaders,
SidebarHeader,
DateHeader
} from 'react-calendar-timeline'
<Timeline>
<TimelineHeaders>
<SidebarHeader>
{({ getRootProps }) => {
return
}}
</SidebarHeader>
<SidebarHeader variant="right" headerData={{someData: 'extra'}}>
{({ getRootProps, data }) => {
return
}}
</SidebarHeader>
<DateHeader unit="primaryHeader" />
<DateHeader />
</TimelineHeaders>
</Timeline>
Note : the Child function renderer can be a component or a function for convenience
DateHeaderResponsible for rendering the headers above calendar part of the timeline. Consists of time intervals dividing the headers in columns.
style
object
applied to the root of the header
className
string
applied to the root of the header
unit
second, minute, hour, day, week, month, year or primaryHeader
intervals between columns
labelFormat
Function or string
controls the how to format the interval label
intervalRenderer
Function
render prop to render each interval in the header
`heade
No open issues yet, or sync has not completed.