Event Timeline - Events
Configure event properties including color, timezone, recurrence, and custom data mapping.
Event properties
Resource
Use the resource property to link an event to its resource:
const event = {
// ...other properties
resource: 'work',
};
Dynamic resource
Use the eventModelStructure property to switch the resource between several fields:
All day
Use the allDay property to define an event as all-day.
An all-day event has no time and no timezone: it covers whole days, the same ones wherever it is displayed.
Its start and end are YYYY-MM-DD dates, and end is exclusive: the day after the last day.
On a timed event, a YYYY-MM-DD string is midnight of that day in the event's timezone: an event with these dates but without allDay: true is a 24-hour timed event.
const event = {
// ...other properties
start: '2025-07-04',
end: '2025-07-05', // July 4th only
allDay: true,
};
The occurrences the Scheduler provides end at the start of the day after the last day too: see Reading occurrence dates.
The exDates of a recurring all-day event are dates as well.
The timezone property of an all-day event only applies to a date-time until of its recurrence rule, read as its date in that timezone. When the event becomes timed, its timezone becomes the display timezone.
A timed event made all-day without new dates keeps the dates of its timezone, so its recurrence rule and exception dates stay valid.
The Scheduler throws when an all-day event does not follow this format:
- a
startorendthat is not aYYYY-MM-DDdate, a date-time like2025-07-04T00:00:00included; - an
endon or before thestart, which covers no day; - an exception date of an all-day series that is not a
YYYY-MM-DDdate.
Timezone
Use the timezone property to specify the timezone for an event's dates:
const event = {
// ...other properties
timezone: 'America/New_York',
};
See Timezone for details.
Color
Use the color property to define an event's color:
const event = {
// ...other properties
color: 'lime',
};
The available color palettes are shown below:
Class name
Use the className property to apply custom CSS styles to an event:
const event = {
// ...other properties
className: 'highlighted-event',
};
When defined, it applies to the event root DOM element across all views.
Drag interactions
Use the draggable property on the event model to prevent an event from being dragged to a different time slot:
const event = {
// ...other properties
draggable: false,
};
Use the resizable property on the event model to prevent an event from being resized by dragging its start or end edge:
const event = {
// ...other properties
resizable: false,
resizable: "start" // only the start edge is draggable.
resizable: "end" // only the end edge is draggable.
};
See Drag interactions for details.
Read-only
Use the readOnly property to prevent an event from being modified:
const event = {
// ...other properties
readOnly: true,
};
See Editing—Read-only for details.
Recurring events
Use the rrule property to define an event's recurring rule:
const event = {
// ...other properties
rrule: 'FREQ=WEEKLY;INTERVAL=2;BYDAY=TH',
};
The Event Timeline expands recurring events only when the recurringEvents feature is enabled through the features prop:
import { EventTimelinePremium } from '@mui/x-scheduler-premium/event-timeline-premium';
import { recurringEventsFeature } from '@mui/x-scheduler-premium/recurring-events';
<EventTimelinePremium features={{ recurringEvents: recurringEventsFeature }} />;
See Recurring events for details.
Store data in custom properties
Use the eventModelStructure prop to define how to read and write event properties when your data doesn't match the expected model:
const eventModelStructure = {
title: {
getter: (event) => event.name,
setter: (event, newValue) => {
event.name = newValue;
return event;
},
},
};
function Timeline() {
return (
<EventTimelinePremium
events={[{ name: 'Event 1' /** ... */ }]}
eventModelStructure={eventModelStructure}
/>
);
}
A property declared with a getter but no setter is read-only: the Event Timeline displays it but never writes it back to your model. When start or end is read-only, events can't be dragged or created, and only the other edge can be resized. Saving an occurrence of a recurring event with the "Only this event" or "This and following events" scope is refused with an error, since it needs to write a new date. With dependencies, a change whose cascade would need to write such a date is refused as a whole.
Custom event content
Use the timelineEventContent slot to replace the text rendered inside an event block.
The slot receives the occurrence, the resource of the row it is rendered in and the variant of the block.
It is placed inside the block, so the block keeps its geometry, its drag and resize handles, and its button semantics.
The slot also renders in the placeholder that previews a drag, a resize or a creation, with variant set to "placeholder" and an occurrence carrying the pending dates.
The slot doesn't change the accessible name of the event, which is built from its title, dates, resource, and recurrence.
To announce the details the slot adds, pass getEventAriaLabel: it receives the occurrence, the row resource and the defaultAriaLabel, and returns the name to use.
The demo above appends the ticket code to the default name.
The block is a button, so keep the content presentational (text, icons, a tooltip) rather than adding links or buttons of its own.
Typing custom slot props
Pass extra props to the slot through slotProps.timelineEventContent and type them by augmenting the TimelineEventContentPropsOverrides interface:
declare module '@mui/x-scheduler-premium/models' {
interface TimelineEventContentPropsOverrides {
showCode?: boolean;
}
}
<EventTimelinePremium
slots={{ timelineEventContent: EventContent }}
slotProps={{ timelineEventContent: { showCode: true } }}
/>;
Event constraints 🚧
With this feature, users would be able to define constraints on events, such as restricting them to specific time ranges or resources.
API
See the documentation below for a complete reference to all of the props and classes available to the components mentioned here.