# Events data
Package: @mantine/schedule
Import: import { ScheduleEventsData } from '@mantine/schedule';
Description: Event data shapes and callback payloads for @mantine/schedule

## Overview

All `@mantine/schedule` components accept events through the `events` prop.
An event is one of three shapes:

* **One-off event** – a regular event without recurrence
* **Recurring series event** – a source event that expands into multiple occurrences
* **Recurring override event** – an event that replaces a single occurrence of a series

All three shapes share the base fields described below.

## ScheduleEventBase

```tsx
import type { DateTimeStringValue, EventPayload } from '@mantine/schedule';
import type { MantineColor } from '@mantine/core';

interface ScheduleEventBase<Payload extends EventPayload = EventPayload> {
  /** Unique event id, used for key and identification */
  id: string | number;

  /** Event title, displayed in month, week and day views */
  title: string;

  /** Event start date/time */
  start: Date | DateTimeStringValue;

  /** Event end date/time */
  end: Date | DateTimeStringValue;

  /** Event background color. Key of `theme.colors` or any valid CSS color. */
  color: MantineColor;

  /** Event variant, default is `'light'` */
  variant?: 'filled' | 'light';

  /** Event display mode. Background events render as full-width blocks behind regular
   *  events, non-interactive unless `withInteractiveBackgroundEvents` is set on the view.
   *  @default 'default' */
  display?: 'default' | 'background';

  /** Additional event data, defined by the user, not used internally by the library */
  payload?: Payload;
}
```

`start` and `end` accept a `Date` instance or a string in `YYYY-MM-DD HH:mm:ss` format.

## ScheduleSingleEventData

A regular event without recurrence, the most common shape:

```tsx
import type { ScheduleSingleEventData } from '@mantine/schedule';

const event: ScheduleSingleEventData = {
  id: 'meeting-1',
  title: 'Team sync',
  start: '2024-01-15 10:00:00',
  end: '2024-01-15 11:00:00',
  color: 'blue',
};
```

## ScheduleRecurringSeriesEventData

A source event of a recurring series. It has a `recurrence` field with an [RFC 5545](https://datatracker.ietf.org/doc/html/rfc5545)
recurrence rule:

```tsx
import type { ScheduleRecurringSeriesEventData } from '@mantine/schedule';

const series: ScheduleRecurringSeriesEventData = {
  id: 'weekly-planning',
  title: 'Weekly planning',
  start: '2024-01-15 10:00:00',
  end: '2024-01-15 11:00:00',
  color: 'blue',
  recurrence: {
    rrule: 'FREQ=WEEKLY;BYDAY=MO;COUNT=12',
    exdate: ['2024-02-12 10:00:00'],
    dtstart: '2024-01-15 10:00:00',
  },
};
```

The `recurrence` object has the following shape:

```tsx
interface ScheduleRecurrenceData {
  /** Recurrence rule string, for example: `FREQ=WEEKLY;BYDAY=MO,WE` */
  rrule: string;

  /** Exception datetimes in `YYYY-MM-DD HH:mm:ss` or valid date string format */
  exdate?: DateTimeStringValue[];

  /** Optional explicit series start datetime */
  dtstart?: DateTimeStringValue;
}
```

See [recurring events guide](https://alpha.mantine.dev/llms/schedule-recurring-events.md) for rule examples and expansion details.

## ScheduleRecurringOverrideEventData

An override event replaces a single generated occurrence of a series:

```tsx
import type { ScheduleRecurringOverrideEventData } from '@mantine/schedule';

const override: ScheduleRecurringOverrideEventData = {
  id: 'weekly-planning-override',
  title: 'Weekly planning (moved)',
  start: '2024-01-17 16:00:00',
  end: '2024-01-17 17:00:00',
  color: 'grape',
  recurringEventId: 'weekly-planning',
  recurrenceId: '2024-01-15 10:00:00',
};
```

* `recurringEventId` – id of the parent series event
* `recurrenceId` – original occurrence datetime in `YYYY-MM-DD HH:mm:ss` format

## EventPayload

Use the `payload` field to attach your own data to events. The library does not read it,
it is available in callbacks and custom event renderers:

```tsx
import type { ScheduleEventData } from '@mantine/schedule';

interface MyEventPayload {
  description: string;
  attendees: string[];
  location?: string;
}

const event: ScheduleEventData<MyEventPayload> = {
  id: 'meeting-1',
  title: 'Team sync',
  start: '2024-01-15 10:00:00',
  end: '2024-01-15 11:00:00',
  color: 'blue',
  payload: {
    description: 'Weekly planning meeting',
    attendees: ['Alice', 'Bob'],
    location: 'Conference room A',
  },
};
```

Pass your payload type as a generic argument to get typed access: `ScheduleEventData<MyPayload>`.

## Recurring instance metadata

Each event generated from a recurring series has a `recurringInstance` object.
Read it in callbacks and custom renderers to tell generated occurrences from regular events:

```tsx
interface RecurringInstanceMeta {
  /** If true, event is generated from recurrence rule */
  isRecurringInstance: boolean;

  /** Parent series event id */
  recurringEventId: string | number;

  /** Original occurrence datetime key */
  recurrenceId: DateTimeStringValue;

  /** Original occurrence dates before any drag/drop updates */
  originalStart: DateTimeStringValue;
  originalEnd: DateTimeStringValue;
}
```

Example of reading the metadata in `onEventClick`:

```tsx
<Schedule
  events={events}
  onEventClick={(event) => {
    if (event.recurringInstance?.isRecurringInstance) {
      console.log('Clicked generated occurrence of', event.recurringInstance.recurringEventId);
    } else {
      console.log('Clicked regular event', event.id);
    }
  }}
/>
```

## Callback payloads

### onEventClick

Called when an event is clicked in any view:

```tsx
onEventClick?: (
  event: ScheduleEventData,
  e: React.MouseEvent<HTMLButtonElement>
) => void;
```

### onEventDrop

Called when an event is dropped after a drag (requires `withEventsDragAndDrop`):

```tsx
onEventDrop?: (data: {
  eventId: string | number;
  newStart: DateTimeStringValue;
  newEnd: DateTimeStringValue;
  event: ScheduleEventData;
}) => void;
```

For generated recurring occurrences, `eventId` is the occurrence id, not the series id.
Use `event.recurringInstance?.recurringEventId` to get the series id.

### onEventResize

Called when an event is resized by dragging its top or bottom edge
(requires `withEventResize`):

```tsx
onEventResize?: (data: {
  eventId: string | number;
  newStart: DateTimeStringValue;
  newEnd: DateTimeStringValue;
  event: ScheduleEventData;
}) => void;
```

The payload has the same shape as in `onEventDrop`, including the `eventId` note
for generated recurring occurrences.

### onEventDragStart / onEventDragEnd

Called when an event drag starts or ends:

```tsx
onEventDragStart?: (event: ScheduleEventData) => void;
onEventDragEnd?: () => void;
```

`onEventDragEnd` is called for both successful drops and cancelled drags.
Use `onEventDrop` to get the new position.

### onTimeSlotClick

Called when a time slot is clicked in `DayView` or `WeekView`:

```tsx
onTimeSlotClick?: (data: {
  slotStart: DateTimeStringValue;
  slotEnd: DateTimeStringValue;
  nativeEvent: React.MouseEvent<HTMLButtonElement>;
}) => void;
```

Slot length is controlled by the view's `intervalMinutes` prop.

### onAllDaySlotClick

Called when the all-day slot is clicked in `DayView` or `WeekView`:

```tsx
onAllDaySlotClick?: (
  date: DateStringValue,
  event: React.MouseEvent<HTMLButtonElement>
) => void;
```

### onDayClick

Called when a day is clicked in `MonthView` or `YearView`:

```tsx
onDayClick?: (
  date: DateStringValue,
  event: React.MouseEvent<HTMLButtonElement>
) => void;
```

### onSlotDragEnd

Called when a slot range is selected by dragging across time slots or day cells
(requires `withDragSlotSelect`):

```tsx
onSlotDragEnd?: (
  rangeStart: DateTimeStringValue,
  rangeEnd: DateTimeStringValue
) => void;
```

### onExternalEventDrop

Called when an item is dragged from outside the schedule and dropped onto a slot:

```tsx
onExternalEventDrop?: (
  dataTransfer: DataTransfer,
  dropDateTime: DateTimeStringValue
) => void;
```

`dataTransfer` is the native object set by the external item in its `onDragStart` handler.
Read your data with `dataTransfer.getData(type)`.

### Callbacks in resources views

In resources views, `onDayClick`, `onSlotDragEnd` and `onExternalEventDrop` are called with
a single object that includes `resourceId` of the row. `onTimeSlotClick` payload includes `resourceId` as well:

```tsx
onDayClick?: (data: {
  date: DateStringValue;
  nativeEvent: React.MouseEvent<HTMLButtonElement>;
  resourceId?: string | number;
}) => void;

onSlotDragEnd?: (data: {
  rangeStart: DateTimeStringValue;
  rangeEnd: DateTimeStringValue;
  resourceId?: string | number;
}) => void;

onExternalEventDrop?: (data: {
  dataTransfer: DataTransfer;
  dropDateTime: DateTimeStringValue;
  resourceId?: string | number;
}) => void;
```

### canDragEvent / canResizeEvent

Return `false` to prevent dragging or resizing of a specific event:

```tsx
canDragEvent?: (event: ScheduleEventData) => boolean;
canResizeEvent?: (event: ScheduleEventData) => boolean;
```

### preventEventOverlap

Rejects drops and resizes that would make the event overlap another event, see
[drop validation](https://alpha.mantine.dev/llms/schedule-schedule.md#drop-validation) for what counts as a conflict:

```tsx
preventEventOverlap?:
  | boolean
  | ((stillEvent: ScheduleEventData, movingEvent: ScheduleEventData) => boolean);
```

Pass a function to decide per pair of events, return `true` to forbid the overlap.
`movingEvent` has the new `start` and `end` and, in resources views, the target `resourceId`.
The function is called many times while dragging, it must be pure and cheap.

### canDropEvent / canResizeEventTo / canDropExternalEvent

Return `false` to reject a drop or resize based on where the event is being placed.
The callbacks are called many times while dragging, they must be pure and cheap:

```tsx
canDropEvent?: (data: {
  event: ScheduleEventData;
  start: DateTimeStringValue;
  end: DateTimeStringValue;
  resourceId?: string | number;
}) => boolean;

canResizeEventTo?: (data: {
  event: ScheduleEventData;
  start: DateTimeStringValue;
  end: DateTimeStringValue;
  edge: 'start' | 'end';
}) => boolean;

canDropExternalEvent?: (data: {
  dataTransfer: DataTransfer;
  start: DateTimeStringValue;
  resourceId?: string | number;
}) => boolean;
```

`canDropExternalEvent` has no `end`, the schedule does not know the duration of an external item.
Only `dataTransfer.types` can be read while the drag is in progress.

### onEventPlacementRejected

Called when a drop, resize or external drop is rejected by `preventEventOverlap` or by one of
the placement callbacks above. The payload shape depends on `action`:

```tsx
onEventPlacementRejected?: (
  data:
    | {
        action: 'drop';
        event: ScheduleEventData;
        start: DateTimeStringValue;
        end: DateTimeStringValue;
        conflicts: ScheduleEventData[];
        reason: 'overlap' | 'rejected';
        resourceId?: string | number;
      }
    | {
        action: 'resize';
        event: ScheduleEventData;
        edge: 'start' | 'end';
        start: DateTimeStringValue;
        end: DateTimeStringValue;
        conflicts: ScheduleEventData[];
        reason: 'overlap' | 'rejected';
        resourceId?: string | number;
      }
    | {
        action: 'external-drop';
        dataTransfer: DataTransfer;
        start: DateTimeStringValue;
        conflicts: [];
        reason: 'rejected';
        resourceId?: string | number;
      }
) => void;
```

* `conflicts` – events the placement collided with, empty when the rejection came from a callback
* `reason` – `'overlap'` when `preventEventOverlap` found a conflict, `'rejected'` when a callback returned `false`
* `resourceId` – only in resources views: the target resource for drops, the event's own resource for `resize`

## Date and time value formats

Event data and callback payloads use two string formats:

* `DateStringValue` – `YYYY-MM-DD`, for example `2024-01-15`
* `DateTimeStringValue` – `YYYY-MM-DD HH:mm:ss`, for example `2024-01-15 10:00:00`

Both types are exported from `@mantine/dates` and `@mantine/schedule`.
