V4 Release Notes and Upgrade Guide

No need to use a separate <link> tag for a print-only stylesheet. It will be automatically included within the normal core/main.css, by use of media queries. Issue 3594

Instead of using jQuery like $().fullCalendar('next'), do something like this:

calendar.next();

Top-level utility functions that were called like $.fullCalendar.formatDate() must now be accessed like import { formatDate } from '@fullcalendar/core' or via the global like FullCalendar.formatDate.

The this context will always be the Calendar object, as opposed to something arbitrary. Issue 2463 and 2699

var calendar = new Calendar(calendarEl, {
  select: function() {
    console.log(this === calendar); // true
  }
});

The on and off methods no longer accept namespaced event names like eventClick.namespace1.namespace2

Instead of using jQuery to get options like $().fullCalendar('option', 'optionName'), use getOption:

var optionValue = calendar.getOption('optionName');

And instead of using jQuery to set options like $().fullCalendar('option', 'optionName', 'optionValue'), use setOption:

calendar.setOption('optionName', 'optionValue');

To get the current View Object, access the Calendar’s view property instead. The getView() method has been removed.

When called after initialization, will rerender everything, not just merely adjust the calendar’s size. For that, use updateSize. Issue 2709

No longer receives a view as its second parameter.

Will readjust a calendar’s sizing (what the render method used to do).

Will group operations and consolidate them into a single rerender. Solves issue 3262

The amount of milliseconds to wait before rerendering anything on a calendar.

Moment JS has been removed as a dependency and thus there is no need to include moment(.min).js. The API now deals in native Date objects as opposed to Moment objects. Related to issue 3937, 3672, 3672.

Will now be Date objects with a time of 00:00:00. Callbacks nearly always provide an allDay boolean in addition. Issue 2981

Instead of specifying date formats as command strings like MMMM d, YYYY, you specify them as objects like { month: 'long', day: 'numeric', year: 'numeric' }. This technique leverages the native DateTimeFormat which results in greater flexibility across locales and smaller locale files.

Also, you can use functions to programmatically generate date string text. Issue 3664

You can still use command strings, but you’ll need to use the moment or luxon plugins.

Signature has been changed from formatRange( moment1, moment2, formatString [, separator, isRTL ] ) to formatRange( date1, date2, settings ). Both date1 and date2 are Date object inputs and settings accepts formatting keys and other stuff too.

Instead of Moment Duration objects, these objects are plain objects in the form { years, months, days, milliseconds }.

You can use the moment or luxon plugins to convert them to something more powerful.

When specifying a function, the function will receive a single Date object, not a Moment.

Determines the separator text used for date-formatting ranges throughout the API, except for the toolbar title text, which is affected by titleRangeSeparator.

Formats a date into a string.

Formats a date into a string. Inherits the locale and time zone settings of the calendar it’s called on.

Formats a date into an ISO8601 string. Outputs a UTC offset appropriate to the calendar it’s called on.

Formats two dates, a start and an end, into a string. Inherits settings from the calendar it’s called on.

Renamed to timeZone (to be more consistent with native naming conventions)

The current timeZone will affect how you will interpret the Date objects emitted from the API. Whether you will use local methods like getHours() or UTC methods like getUTCHours().

Will now be Date objects in UTC. Issue 2981

The default timezone is now local. It used to be false, a technique that forced all dates into UTC, which has been removed…

The timezone: false technique is no longer available. Instead, use a named time zone like America/Chicago without any time zone plugins. Addresses 2981, 2780, 3951

Browsers have a tough time supporting time zones other than local and UTC, which is why the default named time zone implementation essentially shoehorns everything into UTC Date objects. However you can use third-party adapter plugins like moment-timezone or luxon for more authentic time zone implementations, though browser support will vary. Issue 3188

locale/*.js files have been moved to locales/*.js (added an s)

locale-all.js files has been moved to locales-all.js (added an s)

Use the dir settings instead.

isRTL: true becomes dir: 'rtl'

Removed. Use a date-formatting plugin or function instead.

Removed. Use a date-formatting plugin or function instead.

Removed. Use a date-formatting plugin or function instead.

Removed. Use a date-formatting plugin or function instead.

Previously, FullCalendar was kind enough to populate locales for jQuery UI Datepicker. This is no longer the case.

_id can no longer be specified.

Was previously used to group related events together, so that they could be dragged/resized together. That is now done with groupId. The id properties should now be unique across all events in a calendar!

These props were never officially supported. Use startTime, endTime, and daysOfWeek instead. See simple event recurrence.

_id is no longer available. If you need a unique ID for each event, generate it yourself and put it in the id.

All events with the same groupId will be dragged, resized, and mutated together. Issue 4147

A Date object. No longer a moment.

A Date object. No longer a moment.

Access backgroundColor and borderColor instead. Color is an alias for setting both of these at the same time.

Previously, any non-standard properties would be preserved as top-level keys. Now, they are moved into the extendedProps hash.

It is also possible to specify an explicit extendedProps hash in the plain object. Issue 3228

Removed. Use getResources instead, like event.getResources()[0].id

Removed. Use getResources instead, like event.getResources().map((resource) => resource.id)

Removed. For retrieving a single event, use getEventById. For retrieving all events, use getEvents. For retrieving a subset of events, filter the returned array:

var someEvents = calendar.getEvents().filter(function(event) {
  return event.title === 'My Event';
});

Removed. Instead, retrieve an Event object and then call a method that performs manipulation:

var event = calendar.getEventById('a');
event.setProp('title', 'new title');

Manipulation methods: setProp, setExtendedProp, setStart, setEnd, setDates, setAllDay, moveStart, moveEnd, moveDates

Removed. Instead, retrieve an Event object and then call its remove method:

var event = calendar.getEventById('a');
event.remove();

Removed. Instead, use multiple Event::remove calls. Group together for performance with batchRendering.

The default has changed from 2 hours to 1 hour.

Can longer specify a function. Use the calendar-wide eventOverlap instead.

Like the calendar-wide eventAllow but for this event source only.

A function that gets called when fetching succeeds. Will receive two arguments, the raw event array and an XHR if applicable. Can massage the response by returning an event source array to use instead.

A function that gets called when fetching failed. Probably because an AJAX request failed. Receives one argument, an error object.

Can now return false to exclude an event from being included. The calendar-wide eventDataTransform can do this too.

Removed. Instead, retreive an Event Source object and then calls its refetch method:

var eventSource = calendar.getEventSourceById('a');
eventSource.refetch();

Removed. Instead, retreive an Event Source object and then calls its remove method:

var eventSource = calendar.getEventSourceById('a');
eventSource.remove();

Removed. Instead, use multiple EventSource::remove calls. Group together for performance with batchRendering.

A function that gets called when fetching succeeds. Will receive two arguments, the raw event array and an XHR if applicable. Can massage the response by returning an event source array to use instead. Issue 2431

A function that gets called when fetching failed. Probably because an AJAX request failed. Receives one argument, an error object.

It is no longer possible to request events via JSONP. CORS will be used instead. Make sure your server is set up to do CORS.

The full range of jQuery.ajax settings are no longer accepted. However, can use the following new settings:

• method - something like 'GET' (the default) or 'POST'
• extraParams - will send GET/POST data to the server. the data property was previously used
• success - Will receive two arguments, the raw event array and an XHR
• failure - Receives one argument, an error object

The cache: false property is no longer available. Instead, adjust your script’s headers or use extraParams to insert your own cachebuster:

var calendar = new Calendar(calendarEl, {
  events: {
    url: '/myfeed.php',
    extraParams: function() {
      return {
        cachebuster: new Date().valueOf()
      };
    }
  }
});

Would previously generate strings like 2019-09-01 which did not have time parts or UTC offsets. Now, the string is guaranteed to have a time part (most likely 00:00:00) and will have a UTC offset that is dependant on the current timeZone. If the timeZone is set to 'local' and the user is localed in New York, the string might be 2019-09-01T00:00:00-05:00. Issue 3593

Same comments as startParam

Renamed to timeZoneParam. Defaults to "timeZone" instead of "timezone".

If your server-side scripts previously relied on a timezone= GET/POST parameter, change it to timeZone instead!

Removed. Use eventSourceFailure instead. Issue 3982

Previously, it was possible to specify timeZones with spaces such as “America/New York”. Now, you must use underscores like “America/New_York”.

In parity with how view names have been renamed, instead of specifying agenda and basic to affect views of a certain type, use timeGrid and dayGrid respectively.

When subclassing the View class, the methods that must be implemented have changed quite a bit. More info.

Previously, to globally define a new type of view, you would use this technique:

$.fullCalendar.views.specialView = {
  type: 'theViewType',
  defaults: { slotLabalInterval: '06:00' }
};

$.fullCalendar.views.customView = {
  'class': CustomViewClass
};

This must rewritten as a plugin:

import { createPlugin } from '@fullcalendar/core';

export default createPlugin({
  views: {
    specialView: {
      type: 'theViewType',
      slotLabalInterval: '06:00' // top-level property!
    },
    customView: CustomViewClass // can pass-in the class directly!
  }
})

Solves issue 3657.

Renamed to type

Renamed to currentStart / currentEnd. The current month/week/day/etc.

Renamed to activeStart / activeEnd. The date range that can be selected and accept events.

Renamed to datesRender. Parameters have changed.

Renamed to datesDestroy. Parameters have changed.

Triggered after a view’s non-date-related DOM structure has been rendered.

Triggered before a view’s DOM skeleton is removed from the DOM.

No longer accepts a format-string out of the box. Use a date-formatting object instead.

This deprecated alias of columnHeaderFormat has been removed. Use columnHeaderFormat instead.

No longer accepts a format-string out of the box. Use a date-formatting object instead.

Accepts a normal Date object now.

Instead of receiving ( date, el ), it now accepts an object. Stub example:

var calendar = new Calendar(calendarEl, {
  dayRender: function(info) {
    console.log(info.date.toISOString());
    console.log(info.el);
    console.log(info.view.type);
  }
});

Renamed to dateClick. Instead of ordered arguments, receives on object argument. Stub example:

var calendar = new Calendar(calendarEl, {
  dateClick: function(info) {
    console.log(info.date.toISOString());
    console.log(info.dateStr);
    console.log(info.allDay);
    console.log(info.dayEl);
    console.log(info.jsEvent);
  }
});

info.date is a Date object, not a Moment.

Also, this is now triggered when the user clicks on top of a background event. Issue 2843

Instead of ordered arguments, receives on object argument. Stub example:

var calendar = new Calendar(calendarEl, {
  select: function(info) {
    console.log(info.start.toISOString());
    console.log(info.end.toISOString());
    console.log(info.startStr + ' - ' + info.endStr);
    console.log(info.allDay);
  }
});

info.start and info.end are Date objects, not Moments.

Removed the ordered argument signature: ( start, end, resourceId ). Instead, pass in a single object { start, end, resourceId }. The ordered argument signature ( start, end ) is still supported.

Renamed to selectMirror.

A string that represents an event ID is no longer accepted. Instead, a string represents an event group ID. The simplest migration tactic is to assign groupId’s to your events with the same values as their id’s.

Default has been changed to 00:00:00. The previous default of 09:00:00 didn’t make a lot of sense. Issue 2902

Also, a bug with events that begin before the view’s start date has been fixed. Issue 3943

This value how has complete control over ordering events within a day, as opposed to before when events were always ordered by time first. The default is now 'start,-duration,allDay,title'. Issue 2907

If your old value for this setting was something like '-duration,title', you’ll want to include the start time in the value now. So, convert it to 'start,-duration,title'.

Instead of accepting ( event, el, view ), it now accepts an object. Stub example:

var calendar = new Calendar(calendarEl, {
  eventRender: function(info) {
    console.log(info.event.title);
    console.log(info.el);
    console.log(info.view);
    console.log(info.isStart);
    console.log(info.isEnd);
    console.log(info.isMirror);
  }
});

Addresses issue 3674, 3956, 2616, 3952, and 3311

Instead of accepting ( event, el, view ), it now accepts an object. Stub example:

var calendar = new Calendar(calendarEl, {
  eventDestroy: function(info) {
    console.log(info.event.title);
    console.log(info.el);
    console.log(info.view);
  }
});

Renamed to eventTimeFormat. Accepts a date-formatting object instead. Issue 1019

Renamed to eventPositioned. Instead of accepting ( event, el, view ), it now accepts an object.

Removed. The concecpt of event rendering being fully complete is flawed (such as when events are revealed in a +more popup). You should operate on individual events instead, via eventPositioned or use some other callback.

Removed. Use rerenderDelay instead, which waits before rerendering anything.

When to render multiple asynchronous event sources in an individual or batched manner. Issue 1672 and 4072

Renamed to addEvent. The stick parameter has been removed in favor of a source parameter. When this source is fetched going forward, the dynamic event will be removed. Not specifying a source is equivalent to setting stick to true. So, by default, events will stick!

Removed. Use multiple addEvent calls instead. Group together for performance with batchRendering.

Where previously received ordered arguments ( event, jsEvent, view ), will now receive a single object argument { event, el, jsEvent, view }. Now fires for background events. Issue 2808

You can no longer return false to cancel the browser’s navigation to the Event object’s URL. Instead, use the jsEvent:

var calendar = new Calendar(calendarEl, {
  eventClick: function(info) {
    info.jsEvent.preventDefault();
  }
});

Renamed to eventMouseEnter. Where previously received ordered arguments ( event, jsEvent, view ), will now receive a single object argument { event, el, jsEvent, view }. Now fires for background events. Issue 3005

Renamed to eventMouseLeave. Where previously received ordered arguments ( event, jsEvent, view ), will now receive a single object argument { event, el, jsEvent, view }. Now fires for background events. Issue 3005

Where previously received ordered arguments ( event, jsEvent, ui, view ), now receives a single object { event, jsEvent, view }.

Where previously received ordered arguments ( event, jsEvent, ui, view ), now receives a single object { event, jsEvent, view }.

Previously accepted ordered arguments ( event, delta, revertFunc, jsEvent, ui, view ). Now accepts an object:

var calendar = new Calendar(calendarEl, {
  eventDrop: function(info) {
    console.log(info.event);
    console.log(info.oldEvent); // data before the drop
    console.log(info.delta); // how far it was moved
    console.log(info.jsEvent);
    console.log(info.newResource); // if using a resource view
    console.log(info.oldResource); // if using a resource view

    if (confirm('revert change?')) {
      info.revert();
    }
  }
})

The delta property is a Duration object, no longer a Moment Duration. The oldEvent property is a new feature that allows you to inspect the event’s values prior to the mutation.

Where previously received ordered arguments ( event, jsEvent, ui, view ), now receives a single object { event, jsEvent, view }.

Where previously received ordered arguments ( event, jsEvent, ui, view ), now receives a single object { event, jsEvent, view }.

Previously accepted ordered arguments ( event, delta, revertFunc, jsEvent, ui, view ). Now accepts an object:

var calendar = new Calendar(calendarEl, {
  eventResize: function(info) {
    console.log(info.event);
    console.log(info.prevEvent); // data before the drop
    console.log(info.startDelta); // how far start was moved
    console.log(info.endDelta); // how far end was moved
    console.log(info.jsEvent);

    if (confirm('revert change?')) {
      info.revert();
    }
  }
})

The startDelta is for resizing from start edge (with eventResizableFromStart). endDelta is for resizing from ending edge. Both are Duration objects, no longer Moment Durations. The prevEvent property is a new feature that allows you to inspect the event’s values prior to the mutation. Issue 4148

Whether the event can be resized from its starting edge. Defaults to false. Issue 374

How many pixels the user’s mouse/touch must move before an event drag or resize activates.

Determines how an event’s duration should be mutated when it is dragged from a timed section to an all-day section and vice versa. Issue 2764

Does auto-scrolling not just for event dragging, but also for event resizing, external element dragging, and date selecting. Issue 242

Removed. Use the following CSS instead:

.fc-event.fc-dragging:not(.fc-selected) {
  opacity: .75;
}

You can tweak this CSS to get different opacity values for different scenarios.

Can no longer specify a single string event ID, but rather a single string groupId that will match Event objects.

The recurring properties dow/start/end have been renamed to daysOfWeek/startTime/endTime.

Can accept an array of objects. Useful if you want to specify multiple date ranges.

You no longer need jQuery UI to be able to drag elements into a calendar. You can use the built-in Draggable API. More information. Issue 3902

If you’d like to use a third-party library for dragging such as Dragula, you can use the ThirdPartyDraggable API. More information. Will work for any other third party library.

It’s possible to drag events between two separate Calendar instances. More information. Issue 820

When associating event data with an element, you can no longer specify properties as separate HTML attributes. Instead, bundle them all together under one JSON string in the data-event attribute. Or better yet, just use the Draggable JS API.

You would previously specify a data-event="1" HTML attribute if you wanted to create an event upon drop, but did not have any other event-creation data to specify. This is now unnecessary because event creation happens by default.

External events that are dropped on all-day areas can be given a default time. This was previously done with the time/start properties. The proprty has been rename to startTime to be more consistent with naming elsewhere in the API. See External Event Dragging for more info.

Event creation upon drop and firing of the eventReceive callback will happen by default. To prevent this from happening, specify { create: false } in your event data. More information.

The eventReceive callback previously received a single Event object argument. It now receives an object { event, draggedEl, view }. Also, it will now also be called when an event from another calendar has been dropped.

Instead of ordered arguments ( date, jsEvent, ui, resourceId ) it will receive a single object { draggedEl, date, resource, allDay, jsEvent, view }. The date property is a Date object not a Moment. allDay is a boolean. resource is a Resource object if applicable.

If dropped on an all-day slot, the date property will always have a 00:00:00 time, regardless of the startTime in the event data, whereas previously the startTime would have been added.

Renamed to weekLabel. Will now affect week text in date formatting.

Does not accept date-formatting string by default. Use a date-formatting object.

When specifying a function, accepts a Date object not a Moment.

Does not accept date-formatting string by default. Use a date-formatting object.

Determines the separator text when formatting the date range in the toolbar title. Default to an elongated dash.

This previously-deprecated setting has been removed. Use themeSystem instead.

Now, simply specify 'bootstrap'. Also, initializing a Bootstrap 4 theme requires additional steps.

Removed. Consequently, the bootstrapGlyphicons option has been removed. Bootstrap 4 support remains however. Going forward, FullCalendar will only support the newest officially released version of Boostrap.

Removed. Consequently, the themeButtonIcons option has been removed.

Renamed to timeGridEventMinHeight

Renamed to TimeGridView. Use this for programmatically extending functionality via a subclass.

Does not accept date-formatting string by default. Use a date-formatting object.

Does not accept date-formatting string by default. Use a date-formatting object.

The render function’s first argument is always a Resource object. Previously, it would vary depending on whether there was a field specified or not.

The user is able to resize the resourceAreaWidth as well as the columns created by resourceColumns. Previously it “just worked,” but now you’ll need to load the interaction plugin.

Removed. Was never officially supported.

Removed. Use getParent instead.

Removed. Use getChildren instead.

Where all non-standard properties are stored. Previously, non-standard properties would be stored in the top-level object.

Removed. Use eventDataTransform instead.

The scrollTo argument is now true by default.

Now retrieves all resources, including nested child resources, in one flat array.

Retrieves only top-level resource (resources that don’t have a specified parent).

Removed. Use the Resource getEvents method instead.

Removed. Use the Resource remove method instead.

Used to accept ordered arguments ( resourceObj, labelTds, bodyTds ). Now accepts a single renderInfo object. The labelTds elements are now present in the renderInfo.el property as a single <td> element. If multiple elements are available for a single resource, resourceRender will be fired multiple times.

There is currently no way to retrieve the element(s) that were previously available in bodyTds. Issue 481

Previously rerendered all resources AND events. Now only renders the areas of the view where explicit resource data is displayed, such as the left cells in Timeline View and the top header in Vertical Resource View.

Support has been dropped.

Support has been dropped. More info.