9.8 KiB
| id | title |
|---|---|
| interaction | Move, Resize & Layout |
Three features cover direct manipulation of a time grid. eventMoveFeature drags an event to a new
slot, eventResizeFeature drags one of its edges, and dayEventLayoutFeature positions events that
overlap. Each one is framework-agnostic. The React and
Solid adapters wrap the same controllers. This page documents the
core API.
Composing the features
Move and resize both declare requires: ['recurrence']. If you compose them without
eventRecurrenceFeature, createCalendar throws.
import {
calendarFeatures,
createCalendar,
dayEventLayoutFeature,
eventMoveFeature,
eventRecurrenceFeature,
eventResizeFeature,
} from '@tanstack/time'
const calendar = createCalendar({
viewMode: { value: 1, unit: 'week' },
timeZone: 'UTC',
features: calendarFeatures([
eventRecurrenceFeature,
eventMoveFeature,
eventResizeFeature,
dayEventLayoutFeature,
]),
events: [
{ id: 'e1', title: 'Stand-up', start: '2025-06-02T09:00:00', end: '2025-06-02T10:00:00' },
],
})
Moving an event
calendar.createMoveController(options?) returns a MoveController. You own the pointer events.
The controller turns them into a validated preview and commits the preview on drop.
const move = calendar.createMoveController({
containerHeight: 1440,
constraints: { snapToMinutes: 15 },
onMoveEnd: (eventId, newStart, newEnd) => {},
onMoveError: (error) => console.warn(error.message),
})
const unsubscribe = move.subscribe(() => render(move.getSnapshot()))
move.start({
eventId: 'e1',
originalStart: '2025-06-02T09:00:00',
originalEnd: '2025-06-02T10:00:00',
dayDate: '2025-06-02',
})
move.moveTo({ dayDate: '2025-06-03', deltaPixels: 60 })
move.end()
| Method | Effect |
|---|---|
start(args) |
Begins a drag. Returns false when enabled: false. |
moveTo({ dayDate?, deltaMinutes?, deltaPixels? }) |
Validates the position and updates the preview. |
end() |
Commits the preview through editEvent, then calls onMoveEnd. |
cancel() |
Drops the drag. Nothing is written. |
destroy() |
Clears the listeners and the state. |
getSnapshot() returns a MoveState: isMoving, eventId, previewStart, previewEnd,
originDayDate, targetDayDate and blocked. Render the ghost from previewStart/previewEnd.
calculateGhostPreviewStyle({ dayDate, previewStart, previewEnd }) gives you a percentage top and
height for each day column.
Pixels and minutes
deltaMinutes takes priority over deltaPixels. Pixels convert as
deltaPixels / containerHeight * 1440, so containerHeight is the height of the full 24-hour
column, not of the visible part. If containerHeight is missing or 0, pixel deltas resolve to
zero minutes and the event does not move.
Granularity
Pass granularity: 'day' to start for all-day or month cells. The minute shift is then pinned to
zero and only dayDate changes the result. The default is 'time'.
Resizing an event
calendar.createResizeController(options?) returns a ResizeController. Unlike the move
controller, it attaches its own mousemove/mouseup listeners to document when a resize starts.
It also finds the target day from the day columns you register.
const resize = calendar.createResizeController({
containerHeight: 1440,
constraints: { snapToMinutes: 15, minDurationMinutes: 30 },
onResizeEnd: (eventId, newStart, newEnd) => {},
onResizeError: (error) => console.warn(error.message),
})
for (const column of document.querySelectorAll<HTMLElement>('[data-day]')) {
resize.registerDayColumn(column.dataset.day!, column)
}
handle.addEventListener('mousedown', (e) => {
resize.start({
eventId: 'e1',
edge: 'bottom',
originalStart: '2025-06-02T09:00:00',
originalEnd: '2025-06-02T10:00:00',
clientX: e.clientX,
clientY: e.clientY,
target: handle,
})
})
edge is 'top' | 'bottom' | 'left' | 'right'. left behaves as top and right behaves as
bottom. start returns false if enabled is false or if no registered column contains the
pointer. Mouse moves are batched to one per animation frame. handleMouseUp commits through
commitUpdate, and cancel() stops the resize without a write.
For a horizontal timeline, set orientation: 'horizontal' and containerWidth. The drag then
scales across every day in the view.
Split segments
A multi-day event is rendered as one segment per day. Always give the controllers the original bounds of the event, not the bounds of the segment:
const { originalStart, originalEnd, isFirstSegment, isLastSegment } =
calendar.getEventSegmentInfo(event)
Use isFirstSegment to decide where to show a top handle and isLastSegment for a bottom handle.
Snapping
Both controllers snap to constraints.snapToMinutes. The default is 15 for both. Resize also
clamps to minDurationMinutes, which defaults to 15. A controller calls the validator only when the
snapped position changes. Thus a 60 → 62 minute drag is one validation, not two.
How validation vetoes a drop
Every processed position goes through validateEventMove or validateResize. You can call either
one directly. For example, to check a keyboard move:
const validation = calendar.validateEventMove({
eventId: 'e1',
originalStart: '2025-06-02T09:00:00',
originalEnd: '2025-06-02T10:00:00',
originalDayDate: '2025-06-02',
targetDayDate: '2025-06-02',
minuteShift: -180,
})
if (validation.blocked) {
validation.error?.message
validation.error?.conflicts
}
A move is checked against dependency anchors, scheduling constraints, duration rules and resource availability, when those features are composed (see Features and Availability). A resize is also checked against unavailable time on the days it crosses, capacity, dependencies and successors that it would push.
A blocked result returns the original times in result and originalDayDate in targetDayDate.
The controller then does the following:
- It sets
blocked: trueand keeps the last valid preview on screen. - It calls
onMoveError/onResizeErrorand emitsevent:update:erroron the time client. The same message for the same event is throttled to once per 500 ms. - On drop, it commits the last valid preview. A drag that was never valid commits nothing.
A move is also rejected if editEvent refuses the write at commit time. The rejection arrives as
onMoveError with kind: 'move', and onMoveEnd does not fire.
Recurring occurrences
Pass occurrenceStart to start when the user drags an occurrence. Both controllers then commit
through editRecurringEvent instead of a plain write:
- With
recurrenceScopeset, the controller commits with that scope. - With no scope and an
onRecurringMoveEnd/onRecurringResizeEndcallback, the controller does not commit. It passes you the event id,occurrenceStart, and the original and new times, so you can ask "this event or all events?" and calleditRecurringEventyourself. - With neither, the scope is
'this'.
See Recurrence.
Overlap layout
calendar.getEventProps(event, layoutOptions?) returns start, end, isSplitEvent and
overlappingEvents. In day and week views it also returns layout and a style that you can
spread directly:
const { style, layout } = calendar.getEventProps(event)
Object.assign(element.style, style)
style holds percentages. It needs no container size, so it stays correct when the container
resizes or the page zooms. top/height map the event onto the 24-hour day. Set a minimum
visible height for short events in your own CSS. In month views, layout and style are
undefined.
Overlaps resolve per cluster, not pairwise. A chain A–B–C where only neighbours overlap uses two columns. All-day events are laid out only against other all-day events.
strategy |
Placement |
|---|---|
'columns' (default) |
Equal-width columns. |
'expand' |
Each event expands right into free columns. |
'cascade' |
Offset stack with a zIndex. Tune it with cascadeOffset (0.2) and minCrossSize (0.3). |
(info) => ({ crossStart, crossSize, zIndex? }) |
Your own placement from the OverlapInfo. |
Set the default with createCalendar({ layout: { strategy: 'cascade' } }). You can override it per
call with getEventProps(event, { strategy: 'columns' }).
For canvas or virtualized rendering, read layout instead of style. It contains the raw
startFraction, endFraction, column, columnCount, columnSpan, depth and concurrency.
layoutDaySegments(events, options) and toLayoutStyle(layout, orientation) are exported for use
outside a calendar instance. See
ADR 0003
for why the core emits fractions and not pixels.