### Install React Calendar Timeline with Yarn

Source: https://github.com/namespace-ee/react-calendar-timeline/blob/main/README.md

Install react-calendar-timeline using yarn.

```bash
yarn add react-calendar-timeline
```

--------------------------------

### Install React Calendar Timeline Beta

Source: https://github.com/namespace-ee/react-calendar-timeline/blob/main/README.md

Install the beta version of react-calendar-timeline using npm.

```bash
npm install react-calendar-timeline@beta
```

--------------------------------

### Install React Calendar Timeline

Source: https://context7.com/namespace-ee/react-calendar-timeline/llms.txt

Install the library and its peer dependencies using npm.

```bash
npm install react-calendar-timeline dayjs interactjs react react-dom
```

--------------------------------

### Contribute to React Calendar Timeline

Source: https://github.com/namespace-ee/react-calendar-timeline/blob/main/README.md

To contribute, fork the repository, install dependencies, and start the development server. Ensure you run linters and tests before submitting a pull request.

```bash
$ git clone https://github.com/namespace-ee/react-calendar-timeline.git react-calendar-timeline
$ cd react-calendar-timeline
$ npm install
$ npm start
```

```bash
npm run lint
```

```bash
npm run test
```

--------------------------------

### Install React Calendar Timeline Stable

Source: https://github.com/namespace-ee/react-calendar-timeline/blob/main/README.md

Install the latest stable version of react-calendar-timeline using npm.

```bash
npm install react-calendar-timeline
```

--------------------------------

### Run Development Server in Next.js

Source: https://github.com/namespace-ee/react-calendar-timeline/blob/main/demo-next/README.md

Use these commands to start the Next.js development server. Open http://localhost:3000 in your browser to view the result.

```bash
npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev
```

--------------------------------

### Basic React Calendar Timeline Usage

Source: https://github.com/namespace-ee/react-calendar-timeline/blob/main/README.md

A minimal example demonstrating how to render the Timeline component with groups and items. Ensure the timeline stylesheet is imported for proper styling. This example uses dayjs for date manipulation.

```jsx
import Timeline from 'react-calendar-timeline'
// make sure you include the timeline stylesheet or the timeline will not be styled
import 'react-calendar-timeline/style.css'
import dayjs from 'dayjs'
import { createRoot } from 'react-dom/client'

const groups = [{ id: 1, title: 'group 1' }, { id: 2, title: 'group 2' }]

const items = [
  {
    id: 1,
    group: 1,
    title: 'item 1',
    start_time: dayjs(),
    end_time: dayjs().add(1, 'hour')
  },
  {
    id: 2,
    group: 2,
    title: 'item 2',
    start_time: dayjs().add(-0.5, 'hour'),
    end_time: dayjs().add(0.5, 'hour')
  },
  {
    id: 3,
    group: 1,
    title: 'item 3',
    start_time: dayjs().add(2, 'hour'),
    end_time: dayjs().add(3, 'hour')
  }
]

createRoot(document.getElementById('root')).render(
  <div>
    Rendered by react!
    <Timeline
      groups={groups}
      items={items}
      defaultTimeStart={dayjs().add(-12, 'hour')}
      defaultTimeEnd={dayjs().add(12, 'hour')}
    />
  </div>
)
```

--------------------------------

### Custom Timeline Headers

Source: https://github.com/namespace-ee/react-calendar-timeline/blob/main/README.md

Provides an example of setting up custom timeline headers, including SidebarHeader and DateHeader components, within a TimelineHeaders wrapper. Ensure necessary imports are included.

```jsx
import Timeline, {
  TimelineHeaders,
  SidebarHeader,
  DateHeader
} from 'react-calendar-timeline'

<Timeline>
  <TimelineHeaders>
    <SidebarHeader>
      {({ getRootProps }) => {
        return <div {...getRootProps()}>Left</div>
      }}
    </SidebarHeader>
    <DateHeader unit="primaryHeader" />
    <DateHeader />
  </TimelineHeaders>
</Timeline>
```

--------------------------------

### verticalLineClassNamesForTime(start, end)

Source: https://github.com/namespace-ee/react-calendar-timeline/blob/main/README.md

This function is called when a vertical line is rendered. It receives the start and end Unix timestamps (in milliseconds) for the current column and should return an array of class names to be applied to the column, allowing for visual highlighting of specific times like holidays or office hours.

```APIDOC
## verticalLineClassNamesForTime(start, end)

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):

```jsx
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)
```

--------------------------------

### Custom Header Example with Interval Renderer

Source: https://github.com/namespace-ee/react-calendar-timeline/blob/main/README.md

Demonstrates how to use custom headers, including a DateHeader with a custom intervalRenderer. The intervalRenderer allows for customized rendering of each interval using provided props and context.

```jsx
import Timeline, {
  TimelineHeaders,
  SidebarHeader,
  DateHeader
} from 'react-calendar-timeline'

<Timeline>
  <TimelineHeaders>
    <SidebarHeader>
      {({ getRootProps }) => {
        return <div {...getRootProps()}>Left</div>
      }}
    </SidebarHeader>
    <DateHeader unit="primaryHeader" />
    <DateHeader />
    <DateHeader
      unit="day"
      labelFormat="MM/DD"
      style={{ height: 50 }}
      data={{someData: 'example'}}
      intervalRenderer={({ getIntervalProps, intervalContext, data }) => {
        return <div {...getIntervalProps()}>
          {intervalContext.intervalText}
          {data.example}
        </div>
      }}
    />
  </TimelineHeaders>
</Timeline>
```

--------------------------------

### Example of Custom Header Implementation

Source: https://github.com/namespace-ee/react-calendar-timeline/blob/main/README.md

Demonstrates how to implement a custom header, including a SidebarHeader and a DateHeader, within the Timeline component. It shows how to use prop getters and helper functions to manage element properties and interactions.

```jsx
import Timeline, {
  TimelineHeaders,
  SidebarHeader,
  DateHeader
} from 'react-calendar-timeline'

<Timeline>
  <TimelineHeaders>
    <SidebarHeader>
      {({ getRootProps }) => {
        return <div {...getRootProps()}>Left</div>
      }}
    </SidebarHeader>
    <DateHeader unit="primaryHeader" />
    <DateHeader />
    <CustomHeader height={50} headerData={{someData: 'data'}} unit="year">
      {({
        headerContext: { intervals },
        getRootProps,
        getIntervalProps,
        showPeriod,
        data,
      }) => {
        return (
          <div {...getRootProps()}>
            {intervals.map(interval => {
              const intervalStyle = {
                lineHeight: '30px',
                textAlign: 'center',
                borderLeft: '1px solid black',
                cursor: 'pointer',
                backgroundColor: 'Turquoise',
                color: 'white'
              }
              return (
                <div
                  onClick={() => {
                    showPeriod(interval.startTime, interval.endTime)
                  }}
                  {...getIntervalProps({
                    interval,
                    style: intervalStyle
                  })}
                >
                  <div className="sticky">
                    {interval.startTime.format('YYYY')}
                  </div>
                </div>
              )
            })}
          </div>
        )
      }}
    </CustomHeader>
  </TimelineHeaders>
</Timeline>
```

--------------------------------

### Custom Item Renderer with Prop Getters

Source: https://github.com/namespace-ee/react-calendar-timeline/blob/main/README.md

Example of a custom item renderer that utilizes `getItemProps` for the root element and `getResizeProps` for resize handles. This allows for custom styling and behavior of timeline items.

```jsx
let items = [
  {
    id: 1,
    group: 1,
    title: 'Title',
    tip: 'additional information',
    color: 'rgb(158, 14, 206)',
    selectedBgColor: 'rgba(225, 166, 244, 1)',
    bgColor : 'rgba(225, 166, 244, 0.6)',
    ...
  }
]

itemRenderer: ({ 
  item,
  itemContext,
  getItemProps,
  getResizeProps
}) => {
  const { left: leftResizeProps, right: rightResizeProps } = getResizeProps()
  return (
    <div {...getItemProps(item.itemProps)}>
      {itemContext.useResizeHandle ? <div {...leftResizeProps} /> : ''}

      <div
        className="rct-item-content"
        style={{ maxHeight: `${itemContext.dimensions.height}` }}
      >
        {itemContext.title}
      </div>

      {itemContext.useResizeHandle ? <div {...rightResizeProps} /> : ''}
    </div>
  )

}
```

--------------------------------

### Groups Prop Interface and Example

Source: https://context7.com/namespace-ee/react-calendar-timeline/llms.txt

Defines the structure for timeline rows, including required `id` and `title`, and optional fields for stacking behavior, custom height, and right sidebar content.

```tsx
interface MyGroup {
  id: number
  title: string
  rightTitle?: string
  stackItems?: boolean  // override global stackItems for this row
  height?: number       // fixed pixel height for this row
}

const groups: MyGroup[] = [
  { id: 1, title: 'Engineering', rightTitle: 'ENG', stackItems: true, height: 60 },
  { id: 2, title: 'Design',      rightTitle: 'DES', stackItems: false },
  { id: 3, title: 'QA',          rightTitle: 'QA',  height: 50 },
]

<Timeline groups={groups} items={items} defaultTimeStart={...} defaultTimeEnd={...} />
```

--------------------------------

### Move/Resize Validation Example

Source: https://github.com/namespace-ee/react-calendar-timeline/blob/main/README.md

Custom validation function to prevent items from moving into the past and to enforce 15-minute intervals. This function is called when an item is being moved or resized.

```js
function (action, item, time, resizeEdge) {
  if (time < new Date().getTime()) {
    var newTime = Math.ceil(new Date().getTime() / (15*60*1000)) * (15*60*1000);
    return newTime;
  }

  return time
}
```

--------------------------------

### Real-Time Drag/Resize Feedback with `onItemDrag`

Source: https://context7.com/namespace-ee/react-calendar-timeline/llms.txt

Get real-time feedback during item dragging or resizing using the `onItemDrag` prop. This callback fires continuously, providing information about the event type, item ID, new position, or resize edge. Use it for live previews or updating external state.

```tsx
import { OnItemDragObjectMove, OnItemDragObjectResize } from 'react-calendar-timeline'

const handleItemDrag = (dragObject: OnItemDragObjectMove | OnItemDragObjectResize) => {
  if (dragObject.eventType === 'move') {
    console.log(
      `Moving item ${dragObject.itemId} to group index ${dragObject.newGroupOrder}`,
      `at ${dayjs(dragObject.time).format('HH:mm')}`
    )
  } else {
    console.log(
      `Resizing item ${dragObject.itemId} from ${dragObject.edge} edge`,
      `to ${dayjs(dragObject.time).format('HH:mm')}`
    )
  }
}

<Timeline
  groups={groups}
  items={items}
  defaultTimeStart={...}
  defaultTimeEnd={...}
  onItemDrag={handleItemDrag}
  onItemMove={(itemId, dragTime, newGroupOrder) => {
    // Commit the move after drag ends
    setItems(prev => prev.map(item =>
      item.id === itemId
        ? { ...item, start_time: dragTime, end_time: dragTime + (item.end_time - item.start_time), group: groups[newGroupOrder].id }
        : item
    ))
  }}
/>
```

--------------------------------

### Add Sticky Header to Timeline

Source: https://github.com/namespace-ee/react-calendar-timeline/blob/main/README.md

To make the timeline header stick to the top when scrolling, follow the example provided in the documentation for sticky headers.

```html
you need to add sticky to the header like [this example](https://github.com/FoothillSolutions/react-calendar-timeline/tree/dest-build/examples#sticky-header).
```

--------------------------------

### onItemMove

Source: https://github.com/namespace-ee/react-calendar-timeline/blob/main/README.md

Callback function invoked when an item has been successfully moved. Returns the item's ID, new start time, and new group index.

```APIDOC
## onItemMove(itemId, dragTime, newGroupOrder)

Callback when an item is moved. Returns 1) the item's ID, 2) the new start time and 3) the index of the new group in the `groups` array.
```

--------------------------------

### Custom Group Renderer

Source: https://github.com/namespace-ee/react-calendar-timeline/blob/main/README.md

A React component example for rendering custom group elements in the sidebar. It receives the `group` object and `isRightSidebar` boolean as props.

```jsx
let groups = [
  {
    id: 1,
    title: 'Title',
    tip: 'additional information'
  }
]

groupRenderer = ({ group }) => {
  return (
    <div className="custom-group">
      <span className="title">{group.title}</span>
      <p className="tip">{group.tip}</p>
    </div>
  )
}
```

--------------------------------

### Customize Vertical Line Class Names

Source: https://github.com/namespace-ee/react-calendar-timeline/blob/main/README.md

Implement `verticalLineClassNamesForTime` to return an array of class names for vertical lines. This function is called for each column and receives start and end Unix timestamps. Optimize this function for performance as it's called frequently.

```jsx
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']
    }
  }
}
```

--------------------------------

### onTimeChange

Source: https://github.com/namespace-ee/react-calendar-timeline/blob/main/README.md

Callback function invoked when the user attempts to scroll the timeline. It receives the current visible start and end times, and a function to update the canvas scroll. This can be used to control or limit scrolling behavior.

```APIDOC
## onTimeChange(visibleTimeStart, visibleTimeEnd, updateScrollCanvas, unit)

### Description
A function that's called when the user tries to scroll. Call the passed `updateScrollCanvas(start, end)` with the updated visibleTimeStart and visibleTimeEnd (as unix timestamps in milliseconds) to change the scroll behavior, for example to limit scrolling.

### Parameters
- **visibleTimeStart** (number) - The starting timestamp of the visible timeline.
- **visibleTimeEnd** (number) - The ending timestamp of the visible timeline.
- **updateScrollCanvas** (function) - A function to call with new start and end timestamps to update the scroll position.
- **unit** (string) - The current unit of time being displayed.

### Example
```javascript
// this limits the timeline to -6 months ... +6 months
const minTime = dayjs().add(-6, 'month').valueOf()
const maxTime = dayjs().add(6, 'month').valueOf()

function (visibleTimeStart, visibleTimeEnd, updateScrollCanvas) {
  if (visibleTimeStart < minTime && visibleTimeEnd > maxTime) {
    updateScrollCanvas(minTime, maxTime)
  } else if (visibleTimeStart < minTime) {
    updateScrollCanvas(minTime, minTime + (visibleTimeEnd - visibleTimeStart))
  } else if (visibleTimeEnd > maxTime) {
    updateScrollCanvas(maxTime - (visibleTimeEnd - visibleTimeStart), maxTime)
  } else {
    updateScrollCanvas(visibleTimeStart, visibleTimeEnd)
  }
}
```
```

--------------------------------

### Define Custom Item Properties for React Calendar Timeline

Source: https://context7.com/namespace-ee/react-calendar-timeline/llms.txt

Define the structure for individual timeline items, including custom properties for movement and resizing. Unix timestamps in milliseconds are preferred for start and end times.

```tsx
interface MyItem {
  id: number
  group: number         // references a group id
  title: string
  start_time: number    // Unix ms
  end_time: number      // Unix ms
  canMove?: boolean
  canResize?: boolean | 'left' | 'right' | 'both'
  canChangeGroup?: boolean
  className?: string
  style?: React.CSSProperties
  itemProps?: React.HTMLProps<HTMLDivElement>  // passed to root <div>
  height?: number       // per-item height override in pixels
}

const items: MyItem[] = [
  {
    id: 1,
    group: 1,
    title: 'Sprint Planning',
    start_time: dayjs().valueOf(),
    end_time: dayjs().add(2, 'hour').valueOf(),
    canMove: false,       // locked in time
    canResize: 'right',
    style: { background: '#4a90e2', color: '#fff' },
    itemProps: { 'data-tip': 'Sprint Planning session' },
  },
  {
    id: 2,
    group: 2,
    title: 'Design Handoff',
    start_time: dayjs().add(3, 'hour').valueOf(),
    end_time: dayjs().add(5, 'hour').valueOf(),
    height: 50,           // taller than default line height
  },
]
```

--------------------------------

### Import Timeline Component and Stylesheet

Source: https://context7.com/namespace-ee/react-calendar-timeline/llms.txt

Import the necessary component and its default stylesheet for basic usage.

```tsx
// Import the component and its stylesheet
import Timeline from 'react-calendar-timeline'
import 'react-calendar-timeline/style.css'
```

--------------------------------

### CustomMarker Usage

Source: https://github.com/namespace-ee/react-calendar-timeline/blob/main/README.md

Demonstrates basic and custom rendering of CustomMarker. Ensure styles are passed to the root component for proper positioning.

```jsx
const today = Date.now()
<CustomMarker date={today} />
```

```jsx
//custom renderer
<CustomMarker date={today}>
  {({ styles, date }) => <div style={styles} />}
</CustomMarker>
```

--------------------------------

### Default Time Steps Configuration

Source: https://github.com/namespace-ee/react-calendar-timeline/blob/main/README.md

Specifies the default step intervals for displaying time units (second, minute, hour, day, month, year).

```js
{
  second: 1,
  minute: 1,
  hour: 1,
  day: 1,
  month: 1,
  year: 1
}
```

--------------------------------

### Limit Timeline Scrolling with onTimeChange

Source: https://github.com/namespace-ee/react-calendar-timeline/blob/main/README.md

Use the onTimeChange handler to restrict the visible date range of the timeline. This example limits the view to a 12-month period centered around the current date.

```javascript
// this limits the timeline to -6 months ... +6 months
const minTime = dayjs().add(-6, 'month').valueOf()
const maxTime = dayjs().add(6, 'month').valueOf()

function (visibleTimeStart, visibleTimeEnd, updateScrollCanvas) {
  if (visibleTimeStart < minTime && visibleTimeEnd > maxTime) {
    updateScrollCanvas(minTime, maxTime)
  } else if (visibleTimeStart < minTime) {
    updateScrollCanvas(minTime, minTime + (visibleTimeEnd - visibleTimeStart))
  } else if (visibleTimeEnd > maxTime) {
    updateScrollCanvas(maxTime - (visibleTimeEnd - visibleTimeStart), maxTime)
  } else {
    updateScrollCanvas(visibleTimeStart, visibleTimeEnd)
  }
}
```

--------------------------------

### Timeline Interaction Shortcuts

Source: https://github.com/namespace-ee/react-calendar-timeline/blob/main/README.md

Users can interact with and navigate the timeline using keyboard shortcuts combined with mouse wheel actions for moving and zooming.

```text
shift + mousewheel = move timeline left/right
alt + mousewheel = zoom in/out
ctrl + mousewheel = zoom in/out 10× faster
meta + mousewheel = zoom in/out 3x faster (win or cmd + mousewheel)
```

--------------------------------

### Format Date Header Labels

Source: https://github.com/namespace-ee/react-calendar-timeline/blob/main/README.md

Customize the format of date header labels using a string or a function. The function provides more control by receiving start and end times, unit, and label width.

```typescript
type Unit = `second` | `minute` | `hour` | `day` | `month` | `year`
([startTime, endTime] : [Dayjs, Dayjs], unit: Unit, labelWidth: number, formatOptions: LabelFormat = defaultFormat ) => string
```

--------------------------------

### Control Timeline Viewport with `visibleTimeStart`, `visibleTimeEnd`, and `onTimeChange`

Source: https://context7.com/namespace-ee/react-calendar-timeline/llms.txt

Implement controlled scrolling for the timeline by managing `visibleTimeStart` and `visibleTimeEnd` states. The `onTimeChange` handler allows programmatic updates and clamping of the scroll range.

```tsx
import { useState } from 'react'
import Timeline from 'react-calendar-timeline'
import dayjs from 'dayjs'

const MIN_TIME = dayjs().add(-6, 'month').valueOf()
const MAX_TIME = dayjs().add(6, 'month').valueOf()

function ControlledTimeline({ groups, items }) {
  const [visibleTimeStart, setStart] = useState(dayjs().startOf('day').valueOf())
  const [visibleTimeEnd, setEnd]   = useState(dayjs().startOf('day').add(1, 'day').valueOf())

  const handleTimeChange = (newStart, newEnd, updateScrollCanvas) => {
    // Clamp scroll to ±6 months
    if (newStart < MIN_TIME && newEnd > MAX_TIME) {
      updateScrollCanvas(MIN_TIME, MAX_TIME)
    } else if (newNewStart < MIN_TIME) {
      updateScrollCanvas(MIN_TIME, MIN_TIME + (newEnd - newStart))
    } else if (newEnd > MAX_TIME) {
      updateScrollCanvas(MAX_TIME - (newEnd - newStart), MAX_TIME)
    } else {
      updateScrollCanvas(newStart, newEnd)
    }
    setStart(newStart)
    setEnd(newEnd)
  }

  return (
    <>
      <button onClick={() => { const z = visibleTimeEnd - visibleTimeStart; setStart(s => s - z); setEnd(e => e - z) }}>← Prev</button>
      <button onClick={() => { const z = visibleTimeEnd - visibleTimeStart; setStart(s => s + z); setEnd(e => e + z) }}>Next →</button>
      <Timeline
        groups={groups}
        items={items}
        visibleTimeStart={visibleTimeStart}
        visibleTimeEnd={visibleTimeEnd}
        onTimeChange={handleTimeChange}
      />
    </>
  )
}
```

--------------------------------

### Multiple CustomMarkers

Source: https://github.com/namespace-ee/react-calendar-timeline/blob/main/README.md

Shows how to render multiple CustomMarkers by mapping over an array of date objects within a TimelineMarkers component.

```jsx
// multiple CustomMarkers
const markerDates = [
  {date: today, id: 1,},
  {date: tomorrow, id: 2,},
  {date: nextFriday, id: 3,},
]

<TimelineMarkers>
  {markerDates.map(marker => <CustomMarker key={marker.date} date={marker.date}/> )}
</TimelineMarkers>
```

--------------------------------

### traditionalZoom

Source: https://github.com/namespace-ee/react-calendar-timeline/blob/main/README.md

Enables zooming in by scrolling the mouse wheel up/down. Defaults to false.

```APIDOC
## traditionalZoom

Zoom in when scrolling the mouse up/down. Defaults to `false`
```

--------------------------------

### Customizing Timeline Headers

Source: https://context7.com/namespace-ee/react-calendar-timeline/llms.txt

Demonstrates how to use TimelineHeaders with SidebarHeader, DateHeader, and CustomHeader to create custom header layouts. Imports are required from 'react-calendar-timeline' and 'dayjs'.

```tsx
import Timeline, {
  TimelineHeaders,
  SidebarHeader,
  DateHeader,
  CustomHeader,
} from 'react-calendar-timeline'
import dayjs from 'dayjs'

<Timeline groups={groups} items={items} defaultTimeStart={...} defaultTimeEnd={...} sidebarWidth={150} rightSidebarWidth={80}>
  <TimelineHeaders calendarHeaderStyle={{ background: '#1a1a2e' }}>

    {/* Custom content above left sidebar */}
    <SidebarHeader>
      {({ getRootProps }) => (
        <div {...getRootProps({ style: { background: '#16213e', color: '#fff', display: 'flex', alignItems: 'center', padding: '0 8px' } })}>
          Resources
        </div>
      )}
    </SidebarHeader>

    {/* Custom content above right sidebar */}
    <SidebarHeader variant="right" headerData={{ label: 'Hours' }}>
      {({ getRootProps, data }) => (
        <div {...getRootProps({ style: { background: '#0f3460', color: '#eee', textAlign: 'center' } })}>
          {data.label}
        </div>
      )}
    </SidebarHeader>

    {/* Primary (larger unit) date row */}
    <DateHeader unit="primaryHeader" style={{ background: '#e94560', color: '#fff' }} />

    {/* Secondary (timeline unit) date row */}
    <DateHeader />

    {/* Fully custom header: show week numbers */}
    <CustomHeader unit="week" height={28} headerData={{ prefix: 'W' }}>
      {({ headerContext: { intervals }, getRootProps, getIntervalProps, showPeriod, data }) => (
        <div {...getRootProps()}>
          {intervals.map(interval => (
            <div
              key={interval.startTime.valueOf()}
              {...getIntervalProps({ interval, style: { cursor: 'pointer', borderLeft: '1px solid #ccc', textAlign: 'center', fontSize: 11 } })}
              onClick={() => showPeriod(interval.startTime, interval.endTime)}
            >
              {data.prefix}{interval.startTime.week()}
            </div>
          ))}
        </div>
      )}
    </CustomHeader>

  </TimelineHeaders>
</Timeline>
```

--------------------------------

### useResizeHandle

Source: https://github.com/namespace-ee/react-calendar-timeline/blob/main/README.md

Enables a special drag handle (.rct-drag-right) for resizing items. Defaults to false.

```APIDOC
## useResizeHandle

Append a special `.rct-drag-right` handle to the elements and only resize if dragged from there. Defaults to `false`
```

--------------------------------

### onZoom

Source: https://github.com/namespace-ee/react-calendar-timeline/blob/main/README.md

Callback function invoked when the timeline is zoomed (via mouse, pinch, or header click). Provides timeline context and the new unit.

```APIDOC
## onZoom(timelineContext, unit)

Called when the timeline is zoomed, either via mouse/pinch zoom or clicking header to change timeline units
```

--------------------------------

### Default Keys Configuration

Source: https://github.com/namespace-ee/react-calendar-timeline/blob/main/README.md

Specifies the keys used to access properties within 'items' and 'groups' objects. Customize these if your data uses different property names.

```js
{
  groupIdKey: 'id',
  groupTitleKey: 'title',
  groupRightTitleKey: 'rightTitle',
  itemIdKey: 'id',
  itemTitleKey: 'title',    // key for item div content
  itemDivTitleKey: 'title', // key for item div title (<div title="text"/>)
  itemGroupKey: 'group',
  itemTimeStartKey: 'start_time',
  itemTimeEndKey: 'end_time',
}
```

--------------------------------

### Programmatic Scroll and Lazy Loading with `scrollRef` and `onBoundsChange`

Source: https://context7.com/namespace-ee/react-calendar-timeline/llms.txt

Implement programmatic scrolling to a specific element using `scrollRef` and handle canvas boundary changes with `onBoundsChange` for lazy data loading. The `onBoundsChange` callback provides the current visible time window.

```tsx
import { useRef, useCallback } from 'react'

function LazyTimeline({ groups, items, fetchMoreItems }) {
  const scrollContainerRef = useRef(null)

  const handleBoundsChange = useCallback((canvasTimeStart, canvasTimeEnd) => {
    fetchMoreItems(canvasTimeStart, canvasTimeEnd)
  }, [fetchMoreItems])

  const scrollToNow = () => {
    if (!scrollContainerRef.current) return
    scrollContainerRef.current.scrollLeft = 0
  }

  return (
    <>
      <button onClick={scrollToNow}>Jump to Now</button>
      <Timeline
        groups={groups}
        items={items}
        defaultTimeStart={dayjs().add(-12, 'hour').valueOf()}
        defaultTimeEnd={dayjs().add(12, 'hour').valueOf()}
        scrollRef={(el) => { scrollContainerRef.current = el }}
        onBoundsChange={handleBoundsChange}
      />
    </>
  )
}

```

--------------------------------

### Item Object Structure

Source: https://github.com/namespace-ee/react-calendar-timeline/blob/main/README.md

Defines the structure for item objects. 'start_time' and 'end_time' should be Unix timestamps in milliseconds for optimal performance. 'itemProps' can be used to pass custom attributes and event handlers.

```js
{
  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 <div /> of each item as <div {...itemProps} />
    'data-custom-attribute': 'Random content',
    'aria-hidden': true,
    onDoubleClick: () => { console.log('You clicked double!') },
    className: 'weekend',
    style: {
      background: 'fuchsia'
    }
  }
}
```

--------------------------------

### onItemClick

Source: https://github.com/namespace-ee/react-calendar-timeline/blob/main/README.md

Callback function invoked when an item is clicked. Note: item must be selected first, unless itemTouchSendsClick is enabled for touch events. Provides item ID, event object, and time.

```APIDOC
## onItemClick(itemId, e, time)

Called when an item is clicked. Note: the item must be selected before it's clicked... except if it's a touch event and `itemTouchSendsClick` is enabled. `time` is the time that corresponds to where you click on the item in the timeline.
```

--------------------------------

### Custom Renderer for TodayMarker

Source: https://github.com/namespace-ee/react-calendar-timeline/blob/main/README.md

Provide a function as a child to `TodayMarker` for custom rendering. This function receives `styles` (for positioning) and `date`. Ensure `styles` are applied to the root component.

```jsx
// custom interval
const twoSeconds = 2000

<TodayMarker interval={twoSeconds} />

//custom renderer

<TodayMarker>
  {({ styles, date }) =>
    // date is value of current date. Use this to render special styles for the marker
    // or any other custom logic based on date:
    // e.g. styles = {...styles, backgroundColor: isDateInAfternoon(date) ? 'red' : 'limegreen'}
    <div style={styles} />
  }
</TodayMarker>
```

--------------------------------

### Set and Switch Timeline Locales with Day.js

Source: https://context7.com/namespace-ee/react-calendar-timeline/llms.txt

Use `Timeline.setDayjsLocale` to set the locale globally before rendering or switch it at runtime. Ensure the desired Day.js locale is imported.

```tsx
import Timeline from 'react-calendar-timeline'
import 'dayjs/locale/de'
import 'dayjs/locale/fr'

// Set locale globally before rendering
Timeline.setDayjsLocale('de')

// Or switch locale at runtime
function LocaleSwitcher() {
  return (
    <>
      <button onClick={() => Timeline.setDayjsLocale('en')}>English</button>
      <button onClick={() => Timeline.setDayjsLocale('de')}>Deutsch</button>
      <button onClick={() => Timeline.setDayjsLocale('fr')}>Français</button>
      <Timeline
        groups={groups}
        items={items}
        defaultTimeStart={dayjs().add(-7, 'day').valueOf()}
        defaultTimeEnd={dayjs().add(7, 'day').valueOf()}
      />
    </>
  )
}
```

--------------------------------

### Patch Version Update

Source: https://github.com/namespace-ee/react-calendar-timeline/blob/main/README.md

For core team members, use this command to update the package version with a patch.

```bash
npm version patch
```

--------------------------------

### Add Timeline Markers for Key Events

Source: https://context7.com/namespace-ee/react-calendar-timeline/llms.txt

Overlay markers on the timeline canvas at specific time positions using `<TimelineMarkers>`. Customize marker appearance with render-prop children or use default styles.

```tsx
import Timeline, {
  TimelineMarkers,
  TodayMarker,
  CustomMarker,
  CursorMarker,
} from 'react-calendar-timeline'
import dayjs from 'dayjs'

const deadline = dayjs().add(2, 'day').valueOf()
const sprintEnd = dayjs().endOf('week').valueOf()

<Timeline groups={groups} items={items} defaultTimeStart={...} defaultTimeEnd={...}>
  <TimelineMarkers>
    {/* Auto-updating marker at current time, refreshes every 5 seconds */}
    <TodayMarker interval={5000}>
      {({ styles, date }) => (
        <div style={{ ...styles, backgroundColor: 'red', width: 2 }}>
          <span style={{ position: 'absolute', top: 0, left: 4, fontSize: 10, color: 'red', whiteSpace: 'nowrap' }}>
            NOW
          </span>
        </div>
      )}
    </TodayMarker>

    {/* Fixed marker at a specific date */}
    <CustomMarker date={deadline}>
      {({ styles }) => (
        <div style={{ ...styles, backgroundColor: 'orange', width: 2, borderLeft: '2px dashed orange' }} />
      )}
    </CustomMarker>

    <CustomMarker date={sprintEnd} />  {/* Default styled marker */}

    {/* Follows the mouse cursor */}
    <CursorMarker>
      {({ styles, date }) => (
        <div style={{ ...styles, backgroundColor: 'rgba(0,0,200,0.4)', width: 1 }}>
          <div style={{ position: 'absolute', bottom: 0, left: 4, fontSize: 10 }}>
            {dayjs(date).format('HH:mm')}
          </div>
        </div>
      )}
    </CursorMarker>
  </TimelineMarkers>
</Timeline>
```

--------------------------------

### TimelineMarkers

Source: https://github.com/namespace-ee/react-calendar-timeline/blob/main/README.md

Wrapper component for timeline markers that you want rendered on the canvas.

```APIDOC
# Timeline Markers

Timeline markers are markers that are overlayed on the canvas at specific datepoints.

## Overview

Markers can be placed in the Timeline by declaring them as `children` of the `Timeline` component:

```jsx
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 <div style={customStyles} onClick={someCustomHandler} />
      }}
    </CustomMarker>
    <CursorMarker />
  </TimelineMarkers>
</Timeline>
```

Each marker allows for passing in a custom renderer via a [function as a child component](https://medium.com/merrickchristensen/function-as-child-components-5f3920a9ace9). This allows the user to render whatever they want (event handlers, custom styling, etc). This custom renderer receives an object with two properties:

> styles: {position: 'absolute', top: 0, bottom: 0, left: number}

This object _must_ be passed to the root component's `style` prop in order to be rendered properly. Note that you can merge this object with any other properties.

> date: number

Date in unix timestamp of this marker. This can be used to change how your marker is rendered (or if its rendered at all)

## TimelineMarkers

Wrapper for timeline markers that you want rendered.
```

--------------------------------

### TodayMarker

Source: https://github.com/namespace-ee/react-calendar-timeline/blob/main/README.md

A marker that is placed on the current date/time. It can be configured with a custom refresh interval and a custom renderer.

```APIDOC
## TodayMarker

Marker that is placed on the current date/time.

> interval: number | default: 10000

How often the TodayMarker refreshes. Value represents milliseconds.

> children: function({styles: object, date: number}) => JSX.Element

Custom renderer for this marker. Ensure that you always pass `styles` to the root component's `style` prop as this object contains positioning of the marker.

```jsx
// custom interval
const twoSeconds = 2000

<TodayMarker interval={twoSeconds} />

//custom renderer

<TodayMarker>
  {({ styles, date }) =>
    // date is value of current date. Use this to render special styles for the marker
    // or any other custom logic based on date:
    // e.g. styles = {...styles, backgroundColor: isDateInAfternoon(date) ? 'red' : 'limegreen'}
    <div style={styles} />
  }
</TodayMarker>
```

--------------------------------

### Custom Item Rendering with `itemRenderer`

Source: https://context7.com/namespace-ee/react-calendar-timeline/llms.txt

Replace the default item appearance by providing a custom `itemRenderer` function. This function receives item data, context, and prop getters for resizing handles. Configure styles and dynamic backgrounds based on item state.

```tsx
import Timeline from 'react-calendar-timeline'

const itemRenderer = ({ item, itemContext, getItemProps, getResizeProps }) => {
  const { left: leftResizeProps, right: rightResizeProps } = getResizeProps()
  const bg = itemContext.selected
    ? itemContext.dragging ? '#e74c3c' : '#2ecc71'
    : item.bgColor ?? '#3498db'

  return (
    <div
      {...getItemProps({
        style: {
          background: bg,
          color: '#fff',
          borderRadius: 4,
          border: `2px solid ${itemContext.resizing ? 'orange' : 'transparent'}`, 
          fontSize: 12,
          padding: '0 6px',
        },
      })}
    >
      {itemContext.useResizeHandle && <div {...leftResizeProps} />}

      <div
        style={{
          height: itemContext.dimensions.height,
          overflow: 'hidden',
          textOverflow: 'ellipsis',
          whiteSpace: 'nowrap',
          lineHeight: `${itemContext.dimensions.height}px`,
        }}
      >
        {itemContext.title}
        {itemContext.dragging && ` → group ${itemContext.dragGroupDelta}`}
      </div>

      {itemContext.useResizeHandle && <div {...rightResizeProps} />}
    </div>
  )
}

<Timeline groups={groups} items={items} defaultTimeStart={...} defaultTimeEnd={...} itemRenderer={itemRenderer} useResizeHandle />
```

--------------------------------

### onItemSelect

Source: https://github.com/namespace-ee/react-calendar-timeline/blob/main/README.md

Callback function invoked when an item is selected (first click). Provides the item's ID, event object, and the time at the click point.

```APIDOC
## onItemSelect(itemId, e, time)

Called when an item is selected. This is sent on the first click on an item. `time` is the time that corresponds to where you click/select on the item in the timeline.
```

--------------------------------

### Core Timeline Component Usage

Source: https://context7.com/namespace-ee/react-calendar-timeline/llms.txt

Renders the full timeline with groups and items. Requires either uncontrolled (defaultTimeStart/End) or controlled (visibleTimeStart/End + onTimeChange) time props. Configure item stacking, movement, resizing, and event handlers.

```tsx
import Timeline from 'react-calendar-timeline'
import 'react-calendar-timeline/style.css'
import dayjs from 'dayjs'
import { createRoot } from 'react-dom/client'

const groups = [
  { id: 1, title: 'Team Alpha' },
  { id: 2, title: 'Team Beta' },
]

const items = [
  {
    id: 1,
    group: 1,
    title: 'Deploy v1.0',
    start_time: dayjs().valueOf(),
    end_time: dayjs().add(3, 'hour').valueOf(),
    canMove: true,
    canResize: 'both',
  },
  {
    id: 2,
    group: 2,
    title: 'Code Review',
    start_time: dayjs().add(1, 'hour').valueOf(),
    end_time: dayjs().add(4, 'hour').valueOf(),
  },
]

createRoot(document.getElementById('root')!).render(
  <Timeline
    groups={groups}
    items={items}
    defaultTimeStart={dayjs().add(-6, 'hour').valueOf()}
    defaultTimeEnd={dayjs().add(6, 'hour').valueOf()}
    stackItems
    canMove
    canResize="right"
    lineHeight={40}
    itemHeightRatio={0.75}
    sidebarWidth={200}
    onItemMove={(itemId, dragTime, newGroupOrder) => {
      console.log('Item moved:', itemId, 'to time:', dragTime, 'group index:', newGroupOrder)
    }}
    onItemResize={(itemId, time, edge) => {
      console.log('Item resized:', itemId, edge, 'new time:', time)
    }}
    onCanvasClick={(groupId, time, e) => {
      console.log('Canvas clicked in group', groupId, 'at', dayjs(time).format())
    }}
  />
)
```

--------------------------------

### itemTouchSendsClick

Source: https://github.com/namespace-ee/react-calendar-timeline/blob/main/README.md

If true, a tap on an item will trigger the same behavior as a click, including opening the item and sending the onItemClick event. Defaults to false.

```APIDOC
## itemTouchSendsClick

Normally tapping (touching) an item selects it. If this is set to true, a tap will have the same effect, as selecting with the first click and then clicking again to open and send the onItemClick event. Defaults to `false`.
```

--------------------------------

### Custom Header Interval Granularity with `timeSteps`

Source: https://context7.com/namespace-ee/react-calendar-timeline/llms.txt

Control the granularity of time units displayed in the timeline header. Setting a specific unit to a value other than 1 will only display multiples of that value (e.g., `minute: 15` shows 0, 15, 30, 45).

```tsx
const timeSteps = {
  second: 30,
  minute: 15,
  hour: 1,
  day: 1,
  month: 1,
  year: 1,
}

<Timeline
  groups={groups}
  items={items}
  defaultTimeStart={dayjs().add(-1, 'hour').valueOf()}
  defaultTimeEnd={dayjs().add(3, 'hour').valueOf()}
  timeSteps={timeSteps}
  minZoom={60 * 1000}  // allow zooming down to 1 minute
/>
```

--------------------------------

### onItemContextMenu

Source: https://github.com/namespace-ee/react-calendar-timeline/blob/main/README.md

Callback function invoked when an item is right-clicked. Provides item ID, event object, and time. If set, the default context menu is suppressed.

```APIDOC
## onItemContextMenu(itemId, e, time)

Called when the item is clicked by the right button of the mouse. `time` is the time that corresponds to where you context click on the item in the timeline. Note: If this property is set the default context menu doesn't appear.
```

--------------------------------

### CursorMarker Usage

Source: https://github.com/namespace-ee/react-calendar-timeline/blob/main/README.md

Illustrates the default and custom rendering of CursorMarker, which displays a marker at the cursor's position. Custom renderers can use the date value for conditional styling.

```jsx
// render default marker for Cursor
<CursorMarker />
```

```jsx
//custom renderer
<CursorMarker>
  {({ styles, date }) =>
    // date is value of current date. Use this to render special styles for the marker
    // or any other custom logic based on date:
    // e.g. styles = {...styles, backgroundColor: isDateInAfternoon(date) ? 'red' : 'limegreen'}
    <div style={styles} />
  }
</CursorMarker>
```

--------------------------------

### Render Sidebar Headers with Child Functions

Source: https://github.com/namespace-ee/react-calendar-timeline/blob/main/README.md

Use child function renderers within TimelineHeaders to customize sidebar headers. The `getRootProps` function getter is available to apply necessary props to the root element.

```jsx
import Timeline, {
  TimelineHeaders,
  SidebarHeader,
  DateHeader
} from 'react-calendar-timeline'

<Timeline>
  <TimelineHeaders>
    <SidebarHeader>
      {({ getRootProps }) => {
        return <div {...getRootProps()}>Left</div>
      }}
    </SidebarHeader>
    <SidebarHeader variant="right" headerData={{someData: 'extra'}}>
      {({ getRootProps, data }) => {
        return <div {...getRootProps()}>Right {data.someData}</div>
      }}
    </SidebarHeader>
    <DateHeader unit="primaryHeader" />
    <DateHeader />
  </TimelineHeaders>
</Timeline>
```

--------------------------------

### onItemResize

Source: https://github.com/namespace-ee/react-calendar-timeline/blob/main/README.md

Callback function invoked when an item has been resized. Returns the item's ID, new time, and the edge that was dragged.

```APIDOC
## onItemResize(itemId, time, edge)

Callback when an item is resized. Returns 1) the item's ID, 2) the new start or end time of the item 3) The edge that was dragged (`left` or `right`)
```

--------------------------------

### CustomMarker

Source: https://github.com/namespace-ee/react-calendar-timeline/blob/main/README.md

A marker that can be placed at a specific datepoint on the timeline. It accepts a `date` prop and can be customized with a renderer function.

```APIDOC
## CustomMarker

This marker allows you to place a marker at a specific date.

> date: number

Date in unix timestamp of this marker. This can be used to change how your marker is rendered (or if its rendered at all)

> children: function({styles: object, date: number}) => JSX.Element

Custom renderer for this marker. Ensure that you always pass `styles` to the root component's `style` prop as this object contains positioning of the marker.
```

--------------------------------

### Enable Container Resize Detection

Source: https://github.com/namespace-ee/react-calendar-timeline/blob/main/README.md

Pass `containerResizeDetector` to the `resizeDetector` prop to enable detection of DOM element resize events. This is an opt-in feature to minimize bundle size.

```jsx
import containerResizeDetector from 'react-calendar-timeline/lib/resize-detector/container'

<Timeline resizeDetector={containerResizeDetector} ... />
```

--------------------------------

### onCanvasClick

Source: https://github.com/namespace-ee/react-calendar-timeline/blob/main/README.md

Callback function invoked when an empty spot on the canvas is clicked. Provides group ID, time, and event object. Useful for opening new item windows.

```APIDOC
## onCanvasClick(groupId, time, e)

Called when an empty spot on the canvas was clicked. Get the group ID and the time as arguments. For example open a "new item" window after this.
```

--------------------------------

### timeSteps

Source: https://github.com/namespace-ee/react-calendar-timeline/blob/main/README.md

Defines the interval for displaying different time units (second, minute, hour, day, month, year).

```APIDOC
## timeSteps

With what step to display different units. E.g. `15` for `minute` means only minutes 0, 15, 30 and 45 will be shown.

Default:

```js
{
  second: 1,
  minute: 1,
  hour: 1,
  day: 1,
  month: 1,
  year: 1
}
```
```

--------------------------------

### onItemDoubleClick

Source: https://github.com/namespace-ee/react-calendar-timeline/blob/main/README.md

Callback function invoked when an item is double-clicked. Provides item ID, event object, and time.

```APIDOC
## onItemDoubleClick(itemId, e, time)

Called when an item was double clicked. `time` is the time that corresponds to where you double click on the item in the timeline.
```