mq-timeline-calendar

# mq-timeline-calendar

A flexible, headless timeline/calendar component for React with smooth scrolling, zooming, and drag-and-drop capabilities.


Features

- 🎯 Headless by default - Full control over styling and rendering
- 📅 Smooth scrolling - Navigate through time seamlessly with mouse wheel
- 🔍 Continuous zoom - Smooth, cursor-relative zoom (Ctrl/Cmd + wheel)
- 🎨 Built-in themes - Light and dark themes included
- 🖱️ Drag & Drop - Move items horizontally (time) and vertically (rows)
- 📍 Pinpoint markers - Display events and milestones with automatic clustering
- 📊 Row grouping - Organize timeline items with collapsible row groups
- 🌍 Localization - Support for 13+ European languages
- ⏰ Availability overlay - Show working hours and available time periods
- 📊 Smart aggregation - Auto-aggregate items when zoomed out for better performance
- ⚛️ React first - Optimized React components with hooks
- 📦 TypeScript - Full type safety and IntelliSense support
- 🚀 Framework-agnostic core - Core engine can be used with any framework

Installation

``bash
npm install mq-timeline-calendar
`

Live Demo

Try out the timeline calendar in StackBlitz:

![Open in StackBlitz](https://stackblitz.com/github/markQsa/mq-calendar-demo?file=README.md)

Open Demo →

Quick Start

`tsx
import { TimelineCalendar, TimelineItem, TimelineRow, TimelineRowGroup } from 'mq-timeline-calendar/react';

function App() {
return (
startDate={new Date('2025-01-01')}
endDate={new Date('2025-12-31')}
height="600px"
showCurrentTime={true}
theme="light"
>


startTime="2025-03-15"
duration="1 week"
row={0}
>


`tsx
startDate={new Date('2024-01-01')}
endDate={new Date('2026-12-31')}
width="100%"
height="600px"
minZoom="1000 years"
maxZoom="100 milliseconds"
showNavigation={false}
showCurrentTime={true}
locale={fiFI}
theme="dark"
onViewportChange={(start, end) => console.log('Viewport:', start, end)}
onZoomChange={(pixelsPerMs) => console.log('Zoom:', pixelsPerMs)}
>
{/ Timeline items and rows /}

`

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| startDate | TimeValue | required | Start date of the timeline |
| endDate | TimeValue | required | End date of the timeline |
| width | string \| number | "100%" | Width of the container |
| height | string \| number | "600px" | Height of the container |
| minZoom | number \| string | - | Minimum zoom level (e.g., "5 years") |
| maxZoom | number \| string | - | Maximum zoom level (e.g., "1 hour") |
| showNavigation | boolean | false | Show navigation buttons |
| showCurrentTime | boolean | false | Show current time indicator |
| currentTimeLineWidth | number | 2 | Width of current time line in pixels |
| locale | CalendarLocale | - | Locale for date formatting |
| theme | 'light' \| 'dark' \| TimelineTheme | 'light' | Theme preset or custom theme object |
| availability | AvailabilityConfig | - | Availability/working hours configuration |
| onViewportChange | (start: Date, end: Date) => void | - | Called when viewport changes |
| onZoomChange | (pixelsPerMs: number) => void | - | Called when zoom level changes |

$3

Individual items placed on the timeline at specific times.

`tsx
startTime="2025-03-15"
duration="1 week"
row={0}
draggable={true}
allowRowChange={true}
onDragStart={(timestamp, row, rowGroupId) => console.log('Drag started')}
onDrag={(timestamp, row, rowGroupId) => console.log('Dragging')}
onDragEnd={(newTime, oldTime, newRow, oldRow, newGroupId, oldGroupId) => {
console.log('Dropped at:', new Date(newTime), 'row:', newRow);
}}
>


| Prop | Type | Default | Description |
|------|------|---------|-------------|
| startTime | TimeValue | required | Start time (Date, timestamp, or ISO string) |
| duration | DurationValue | required | Duration (ms or human-readable like "1 week") |
| endTime | TimeValue | - | Alternative to duration - specify end time directly |
| row | number | 0 | Row/lane for vertical positioning |
| draggable | boolean | false | Enable drag and drop |
| allowRowChange | boolean | false | Allow dragging between rows (vertical) |
| onDragStart | (timestamp, row, rowGroupId?) => void | - | Called when drag starts |
| onDrag | (timestamp, row, rowGroupId?) => void | - | Called during drag |
| onRowChange | (newRow, oldRow, newGroupId?, oldGroupId?) => void | - | Called when row changes |
| onDragEnd | (newTime, oldTime, newRow, oldRow, newGroupId?, oldGroupId?) => void | - | Called when drag ends |
| className | string | - | CSS class name |
| style | CSSProperties | - | Inline styles |

$3

Organize timeline items into rows with optional collapsible headers.

`tsx

id="line-a"
label="Production Line A"
rowCount={2}
collapsible={true}
defaultExpanded={true}
>



| Prop | Type | Default | Description |
|------|------|---------|-------------|
| id | string | auto-generated | Unique identifier |
| label | string | - | Label text for header |
| rowCount | number | 1 | Number of rows this component occupies |
| collapsible | boolean | false | Whether row can be collapsed |
| showHeader | boolean | true | Show header (only if collapsible=true) |
| defaultExpanded | boolean | true | Initial expanded state |
| headerClassName | string | - | CSS class for header |
| headerStyle | CSSProperties | - | Inline styles for header |
| aggregation | AggregationConfig | - | Aggregation configuration (see Aggregation section) |
| renderAggregatedPeriod | (params) => ReactNode | - | Custom renderer for aggregated periods |
| getAggregatedTypeStyle | (type: string) => StyleObject | - | Function to get style for aggregated bar segments |

Drag and Drop

$3

Move items forward or backward in time:

`tsx
const [itemTime, setItemTime] = useState(new Date('2025-03-15'));

startTime={itemTime}
duration="5 days"
row={0}
draggable={true}
onDragEnd={(newTimestamp) => {
setItemTime(new Date(newTimestamp));
}}
>


`tsx
const [itemRow, setItemRow] = useState(0);


startTime="2025-03-15"
duration="5 days"
row={itemRow}
draggable={true}
allowRowChange={true}
onDragEnd={(newTime, oldTime, newRow) => {
setItemRow(newRow);
}}
>


- Direction-locked: Once drag starts, it's locked to either horizontal (time) or vertical (row) based on initial movement
- Snapping: Time changes snap to 15-minute intervals by default
- Threshold: 5-pixel movement required before drag activates (prevents accidental drags)
- Row constraints: Vertical dragging is constrained within the TimelineRow's rowCount

Time Formats

The component accepts multiple time formats:

`tsx
// Date object
startTime={new Date('2025-03-15')}

// ISO string
startTime="2025-03-15T10:00:00Z"

// Timestamp (milliseconds)
startTime={1710504000000}

// Duration can be:
duration={7 24 60 60 1000} // milliseconds
duration="1 week" // human-readable
duration="3 days"
duration="2 hours"
duration="30 minutes"
`

Themes

$3

`tsx
// Light theme (default)


// Dark theme

`

$3

`tsx
theme={{
colors: {
background: '#1a1a1a',
gridLine: '#333333',
headerBackground: '#2a2a2a',
headerText: '#ffffff',
currentTimeLine: '#3b82f6'
},
spacing: {
headerHeight: 100,
rowHeight: 60
}
}}
>
`

Availability / Working Hours

Show available and unavailable time periods:

`tsx
availability={{
// Weekly pattern: define working hours for each day
weekly: {
1: [{ start: '08:00', end: '17:30' }], // Monday
2: [{ start: '09:00', end: '16:00' }], // Tuesday
3: [{ start: '08:00', end: '17:30' }], // Wednesday
4: [{ start: '09:00', end: '16:00' }], // Thursday
5: [{ start: '08:00', end: '15:00' }], // Friday
},
unavailableStyle: {
backgroundColor: 'rgba(156, 163, 175, 0.12)',
}
}}
>
`

Pinpoint Markers

Display point-in-time markers (milestones, events, deadlines) with automatic clustering when markers are too close together.

$3

`tsx
import { TimelinePinpoint, TimelinePinpointGroup, TimelineRow } from 'mq-timeline-calendar/react';

startDate={new Date('2025-01-01')}
endDate={new Date('2025-12-31')}
>


{/ Individual pinpoints - automatically cluster when too close /}
time="2025-03-10T10:00:00"
color="#10b981"
data={{ type: 'inspection', name: 'Safety Check' }}
>
✓


time="2025-03-10T14:00:00"
color="#3b82f6"
data={{ type: 'meeting', name: 'Team Sync' }}
>
👥


time="2025-03-15T09:00:00"
color="#ef4444"
data={{ type: 'deadline' }}
onClick={(timestamp, data) => {
console.log('Clicked:', new Date(timestamp), data);
}}
>
!




`

$3

`tsx
{/ Different sizes /}
time="2025-03-01T10:00:00"
size={32} // Circle size in pixels (default: 24)
color="#10b981"
>
✓


{/ Different alignments /}
time="2025-03-05T10:00:00"
alignment="top" // 'top' (default), 'center', or 'bottom'
>
📍


time="2025-03-10T10:00:00"
alignment="center" // Center alignment hides the vertical line
>
◆


{/ Custom line styles /}
time="2025-03-15T10:00:00"
lineStyle="dashed" // 'solid', 'dashed', or 'dotted'
lineWidth={3} // Line width in pixels (default: 2)
lineLength={50} // Line length in pixels (default: half row height)
>
!

`

$3

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| time | TimeValue | required | Time of the pinpoint (Date, timestamp, or ISO string) |
| row | number | 0 | Row/lane for vertical positioning |
| size | number | 24 | Circle marker size in pixels |
| color | string | theme color | Color of marker and line |
| alignment | 'top' \| 'center' \| 'bottom' | 'top' | Vertical position; 'center' hides line |
| lineWidth | number | 2 | Width of vertical line in pixels |
| lineLength | number | half row height | Length of vertical line in pixels |
| lineStyle | 'solid' \| 'dashed' \| 'dotted' | 'solid' | Style of vertical line |
| children | ReactNode | - | Icon/emoji to display in marker |
| data | any | - | Custom data to associate with pinpoint |
| onClick | (timestamp, data?) => void | - | Click handler |

$3

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| row | number | 0 | Row/lane for vertical positioning |
| clusterDistance | number | 30 | Pixel distance threshold for clustering |
| clusterColor | string | theme color | Color for cluster markers |
| clusterSize | number | 24 | Size of cluster circle marker in pixels |
| pinpointSize | number | 24 | Default size for individual pinpoint markers in pixels |
| pinpointLineWidth | number | 2 | Default line width for pinpoints in pixels |
| pinpointLineLength | number | half row height | Default line length for pinpoints in pixels |
| onClusterClick | (timestamp, items) => void | - | Custom cluster click handler (default: zoom in) |

$3

- Pinpoints within clusterDistance pixels are automatically grouped into clusters
- Cluster markers display the count of pinpoints
- Clicking a cluster smoothly zooms in to separate the pinpoints
- Custom cluster click handler can override default zoom behavior

$3

Set default properties for all pinpoints in a group:

`tsx
{/ All pinpoints inherit size and line properties /}
row={0}
clusterDistance={30}
clusterSize={32} // Larger cluster markers
clusterColor="#ec4899"
pinpointSize={16} // All pinpoints default to 16px
pinpointLineWidth={3} // Thicker lines for all
pinpointLineLength={25} // Shorter lines
>
✓
👥
🔧
{/ All inherit group defaults /}


{/ Individual pinpoints can override group defaults /}
row={1}
pinpointSize={24} // Default size for group
pinpointLineWidth={2}
>
✓ {/ Overrides to 16px /}
👥 {/ Uses group default 24px /}

`

Timeline Aggregation

When working with large datasets, the timeline can automatically aggregate items into grouped periods for better performance and visualization.

$3

When you zoom out far enough (beyond the configured threshold) and have many items, the timeline automatically switches from individual item rendering to an aggregated view. The aggregated view shows:

- Stacked bar charts grouped by week or month
- Occupancy percentage - how much of the available time is occupied
- Item counts by type
- Color-coded segments representing different item types

$3

Add the aggregation prop to TimelineRow:

`tsx
id="production-line"
label="Production Line A"
rowCount={2}
aggregation={{
enabled: true,
threshold: "6 months", // Switch to aggregated view when viewport > 6 months
granularity: "dynamic", // "week" | "month" | "dynamic"
minItemsForAggregation: 50 // Only aggregate if row has 50+ items
}}
getAggregatedTypeStyle={(type) => ({
backgroundColor: type === 'urgent' ? '#ef4444' : '#3b82f6',
color: 'white'
})}
renderAggregatedPeriod={({ period, position, width, height }) => (


| Prop | Type | Default | Description |
|------|------|---------|-------------|
| enabled | boolean | true | Enable/disable aggregation |
| threshold | DurationValue | "6 months" | Viewport duration that triggers aggregation |
| granularity | 'week' \| 'month' \| 'dynamic' | "dynamic" | How to group periods |
| minItemsForAggregation | number | 50 | Minimum items needed to activate aggregation |

$3

You can customize the aggregated view rendering:

`tsx
aggregation={{ enabled: true }}
renderAggregatedPeriod={({ period, position, width, height }) => {
const { occupancyPercent, byType } = period;

return (
style={{
position: 'absolute',
left: position,
width,
height,
background: linear-gradient(to top,
rgba(59, 130, 246, ${occupancyPercent / 100}) 0%,
rgba(59, 130, 246, 0.2) 100%)
}}
>
{occupancyPercent.toFixed(0)}%