Event Timeline - Navigation

Control the visible date and navigate programmatically with the imperative API.

Default visible date

Use the defaultVisibleDate prop to initialize the visible date:

const defaultVisibleDate = DateTime.fromISO('2025-11-01');

<EventTimelinePremium defaultVisibleDate={defaultVisibleDate} />;

Resource title

You can also control the visible date using the visibleDate and onVisibleDateChange props:

const [visibleDate, setVisibleDate] = React.useState(() => DateTime.now());

return (
  <EventTimelinePremium
    visibleDate={visibleDate}
    onVisibleDateChange={setVisibleDate}
  />
);

Imperative API

To use the apiRef object, initialize it with the useEventTimelinePremiumApiRef() hook:

const apiRef = useEventTimelinePremiumApiRef();

return <EventTimelinePremium apiRef={apiRef} events={EVENTS} />;

When your component first renders, apiRef.current is undefined. After the initial render, apiRef holds methods to interact imperatively with the Event Timeline.

Set the visible date

Use the setVisibleDate() API method to navigate to a given date:

apiRef.current.setVisibleDate({
  // The DOM event that triggered the change (will be passed to onVisibleDateChange if provided).
  event,
  // The date to navigate to.
  visibleDate,
});

Resource title

Navigate to the next and previous range

Use the goToNextVisibleDate() and goToPreviousVisibleDate() API methods to navigate forward and backward in time. The step size is automatically determined by the current view:

View	Step
`time`	4 days
`days`	56 days (8 weeks)
`weeks`	16 weeks
`months`	36 months (3 years)
`years`	30 years

// Navigate to the next date range
apiRef.current.goToNextVisibleDate(event);

// Navigate to the previous date range
apiRef.current.goToPreviousVisibleDate(event);

Resource title

API

See the documentation below for a complete reference to all of the props and classes available to the components mentioned here.

<EventTimelinePremium />