Event Calendar

Basic usage

The following example will render an event calendar with default settings.

Example
$('#eventcalendar').mobiscroll().eventcalendar();

Data binding

The event calendar accepts an array of event objects through the data option of the component. The event array can be either a local static array, or populated on demand with remote requests.

Local data

To bind local data to the event calendar, you can simply assign a JavaScript array of objects to the data option of the component.

Example
$('#eventcalendar').mobiscroll().eventcalendar({
  data: [{
    start: new Date(2020, 2, 18, 8, 0),
    end: new Date(2020, 2, 18, 17, 0),
    title: 'My First Event'
  }, {
    start: new Date(2020, 2, 18, 9, 0),
    end: new Date(2020, 2, 20, 13, 0),
    title: 'My Second Event'
  }]
});

Remote data

You can load the data through an external request and use the setEvents method to pass the data to the component.

Example
$('#eventcalendar').mobiscroll().eventcalendar();

var inst = $('#eventcalendar').mobiscroll('getInst');

$.getJSON('https://example.com/events/', function (events) {
  inst.setEvents(events);
});

Load on demand

Use the onPageLoading event to load the data relevant to the currently active view. The event fires every time the date range of the view changes, for example when someone navigates the event calendar. Getting the events in real time as the user interacts with the UI improves load performance and always serves the most recent data.

You can pass the view variables - like month and year - in the URL and handle the filtering inside the API implmentation.

Example
$('#eventcalendar').mobiscroll().eventcalendar({
  data: [],
  onPageLoading: function (event, inst) {
    var year = event.firstDay.getFullYear();
    var month = event.firstDay.getMonth();

    $.getJSON('https://example.com/events?year=' + year + '&month=' + month), function (events) {
      inst.setEvents(events);
    });
  }
});

Recurrence

For the data, colors, labels, marked, invalid and valid options it's possible to specify recurrence rules. The rule can be an object or a string in RRULE format.

Supported properties:

In string format the specified properties are separated by the ';' character.

Examples:

As object
recurring: {
  repeat: 'daily',
  count: 5,
  interval: 2
}
As string
recurring: 'FREQ=DAILY;COUNT=5;INTERVAL=2'

Recurring events

You can create recurring events as well, by specifying the recurring property of the event. This can be an object, or a string in RRULE format. Yearly, monthly, weekly and daily repeats are supported.

Example
$('#eventcalendar').mobiscroll().eventcalendar({
  data: [{
    start: new Date(2020, 2, 18, 9, 0),
    end: new Date(2020, 2, 18, 17, 0),
    title: 'Repeat every 2 days 5 times',
    recurring: {
      repeat: 'daily',
      count: 5,
      interval: 2
    }
  }, {
    start: new Date(2020, 2, 17, 20, 0),
    end: new Date(2020, 2, 17, 22, 0),
    title: 'Football training every Monday and Wednesday',
    recurring: 'FREQ=WEEKLY;UNTIL=2020-06-17;BYDAY=MO,WE'
  }]
});

For more details on the supported recurrence rules see the recurrence section.

CRUD actions

You can use the addEvent, removeEvent and updateEvent methods for CRUD operations.

Here's an example for adding, removing, and updating an event.

Example
var guid = 3;
var events = [{
  id: 1,
  start: new Date(2020, 2, 18, 8, 0),
  end: new Date(2020, 2, 18, 17, 0),
  title: 'My First Event'
}, {
  id: 2,
  start: new Date(2020, 2, 18, 9, 0),
  end: new Date(2020, 2, 20, 13, 0),
  title: 'My Second Event'
}];

$('#eventcalendar').mobiscroll().eventcalendar({
  data: events;
});

var inst = $('#eventcalendar').mobiscroll('getInst');

// Add an event
inst.addEvent({
  id: guid++,
  start: new Date(2020, 2, 18, 9, 0),
  end: new Date(2020, 2, 20, 13, 0),
  title: 'My New Event
});

// Remove an event
inst.removeEvent(2);

// Update an event
var eventToUpdate = events[0];
eventToUpdate.title = 'Updated title';

inst.updateEvent(eventToUpdate);

Views

The event calendar supports three different kind of views, with various configuration options.

Calendar

The calendar view displays a calendar month, or one or more weeks. It can display labels or marks on the day cells, and list its events in a popover, when clicked.

Desktop calendar view

Desktop calendar with labels and popover, iOS light theme

Mobile calendar view

Mobile calendar with labels and popover, iOS dark theme

Agenda

The agenda view displays a list of events for a given period of time (year, month, week or day).

Desktop agenda view

Desktop agenda, Material light theme

Mobile agenda view

Mobile agenda, Material dark theme

Schedule

The schedule view displays a time grid with its related events. Can display a single day, or a week.

Desktop schedule view

Desktop weekly schedule, Windows light theme

Mobile schedule view

Mobile daily schedule, Windows dark theme

A view can be used standalone or combined with another view, e.g. a week view calendar combined with a daily agenda, listing the events for the selected day.

For the available configuration options see the view setting.

Daily agenda example

Weekly calendar view with daily agenda

Example
$('#eventcalendar').mobiscroll().eventcalendar({
  data: [/*...*/],
  view: {
    calendar: { type: 'week' },
    agenda: { type: 'day' }
  }
});

Changing the day

To set the initial date of the event calendar, you can use the selectedDate option. If not specified, it will default to today's date.

To change the selected date later, use the navigate method.

Example
$('#eventcalendar').mobiscroll().eventcalendar({
  data: [/*...*/],
  selectedDate: new Date(2020, 2, 18)
});

var inst = $('#eventcalendar').mobiscroll('getInst);

inst.navigate(new Date(2020, 3, 19));

Customizing the events

You can customize the events using rendering functions. If you want to show custom fields or you have custom data that you want to show or format (for example participants to an event) or if you want to show custom components or markup (for example an avatar) you have two choises. You can customize the full event, or only customize the event content.

Customize the full event

The first choice works like this: wherever there is an event (in the agenda, scheduler, labels or popover) your template will be rendered instead of the default. The eventcalendar will position your component to the right place, but anything else you want to show is up to you. For example is up to you to show a title, a description or color the background or to show any other content like custom fields.

You can use the renderEvent option to pass a custom rendering function for the agenda and the popover events.
You can use the renderLabel option to pass a custom rendering function for the labels on the calendar.
You can use the renderScheduleEvent option to pass a custom rendering function for the scheduler events.

Customize the event content

In most cases you only want to customize the content section of the event. This is the second choice we mentioned earlier. In this case your rendering function will be used as the content of the event. The eventcalendar will position the event to the right place and will render essential information to it like the color of the event, the time and if it's an all day event or not. The title, description and any other fields you want to show (like participants, an avatar, etc...), you will need to put into your function to be rendered.

You can use the renderEventContent option to pass a custom rendering function for the angenda and the popover.
You can use the renderLabelContent option to pass a custom rendering function for the labels on the calendar.
You can use the renderScheduleEventContent option to pass a custom rendering function to the scheduler events.

Examples

Custom Event
$('#eventcalendar').mobiscroll().eventcalendar({
    data: [/*...*/],
    renderEvent: function (data) {
        return '' +
          '<div class="my-start">' + data.start + '</div>' +
          '<div class="my-end">' + data.end + '</div>' +
          '<div class="my-title">' + data.title + '</div>' +
          '<div class="my-custom-field">' + data.original.description + '</div>' +
          '<div class="my-custom-field">' + data.original.location + '</div>';
    }
});
Custom Event Content
$('#eventcalendar').mobiscroll().eventcalendar({
    data: [/*...*/],
    renderEventContent: function (data) {
        return '' +
          '<div class="my-title">' + data.title + '</div>' +
          '<div class="my-custom-field">' + data.original.description + '</div>' +
          '<div class="my-custom-field">' + data.original.location + '</div>';
    }
});

Taking over the listing

When the agenda view is displayed, you can take full control of the rendering, using the renderAgenda option. The renderer function will receive the event data as parameter, grouped by days.

If you'd like to keep the scroll to day functionality, when clicking a day on the calendar, make sure to add mbsc-timestamp attribute on the element containing the events for a day, with the timestamp of the day as value.

Example
$('#eventcalendar').mobiscroll().eventcalendar({
  data: [/*...*/],
  renderAgenda: function (events) {
    let html = '<div class="custom-event-list">';
    events.forEach(function (day) {
      html += '<ul class="custom-event-group" mbsc-timestamp="' + day.timestamp + '">' +
        '<li class="custom-event-day">' + day.date + '</li>';
      day.events.forEach(function (event) {
        html += '<li class="custom-event">' + event.title + '</li>';
      });
      html += '</ul>';
    });
    html += '</div>';
    return html;
  }
});

Customizing the header

The header of the calendar can be fully customized to one's needs. This can be achieved by passing a function that returns the custom header markup to the renderHeader option.

Fully custom header
$('#eventcalendar').mobiscroll().eventcalendar({
    data: [/*...*/],
    renderHeader: function () {
        return '<div class="my-custom-title">My <strong>Awesome</strong> Title</div>';
    }
});

While fully customizing the header is very usefull, sometimes it's desireable to customize only parts of it. In this case you can take advantage of the default header's building blocks. These components let you put toghether the header you want, while you don't have to worry about the functionality behind them.
For example you can leave out parts from the default header, change the order the default buttons appearance or add custom markup between them.

The built in header components can be initialized with their respective attributes as follows:

The above built in components can be used inside of the custom header. The following example will render the prev and next buttons and then a custom title that is set from a custom variable (myTitle variable).

Custom header with default buttons
var myTitle = 'My Awesome title';
$('#eventcalendar).mobiscroll().eventcalendar({
    renderHeader: function () {
        return `<button mbsc-calendar-prev></button>
                <button mbsc-calendar-next></button>
                <div className="my-custom-title">${myTitle}</div>`;
    }
});

Typescript Types

When using with typescript, the following types are available for the Eventcalendar:

Type Description
Eventcalendar Type of the Eventcalendar instance
MbscEventcalendarOptions Type of the settings object that is used to initialize the component

Options

Name Type Default value Description
calendarSystem Object undefined Specify the calendar system to be used. Supported calendar systems:
  • Gregorian - This is the default calendar system, no setting needs to be passed.
  • Jalali - Default system of the Persian calendar. The Farsi language needs to be included to the package.
    $('#mycalendar').mobiscroll().eventcalendar({
      calendarSystem: mobiscroll.jalaliCalendar
    });
    
  • Hijri - Arabic language needs to be included to the package.
    $('#mycalendar').mobiscroll().eventcalendar({
      calendarSystem: mobiscroll.hijriCalendar
    });
    
colors Array undefined Change the color of certain dates on the calendar. Must be an array of objects with the following properties:
  • date Date, String, Object - Date of the calendar day which should be colored.
  • start Date, String, Object - Start date of the calendar days which should be colored.
  • end Date, String, Object - End date of the calendar days which should be colored.
  • background String - Color to be used, can be any valid CSS color ('red', '#ff0000', 'rgb(255,0,0)', etc.).
  • recurring String, Object - Recurrence rule for coloring recurring days.
The dates can be specified as Javascript Date objects, ISO 8601 strings, or moment objects.
The colors can be combined with the labels or marked options.
Example
colors: [
    { date: new Date(2020,2,23), background: 'pink' },
    { date: new Date(2020,2,24), background: 'green' },
    { background: '#ff0000', recurring: { repeat: 'weekly', weekDays: 'SU' },
    { background: 'yellow', recurring: { repeat: 'weekly', weekDays: 'SA' } }
]
context String, HTMLElement 'body' The DOM element in which the popups (event popover, year and month picker) are rendered. Can be a selector string or a DOM element.
data Array undefined Events for the calendar, as an array of event objects. The event object supports the following properties:
  • idString, Number - A unique id for the event. If not specifed, the event will get a generated id.
  • startDate, String, Object - Specifies the start of the event.
  • endDate, String, Object - Specifies the end of the event.
  • titleString - The title of the event.
  • colorString - The color of the event.
  • allDayBoolean - Specifies if the event is all day or not.
  • recurring: String, Object - Recurrence rule for the event.
The dates can be specified as Javascript Date objects, ISO 8601 strings, or moment objects.
The event objects may have additional custom properties as well. The custom properties are not used by the eventcalendar, but they are kept and will be available anywhere the event objects are used. E.g. the onEventClick event will receive the event object as argument, containing the custom properties as well.
Example
data: [{
  start: new Date(2020, 2, 23),
  end: new Date(2012, 2, 23),
  title: 'Conference',
  allDay: true,
  color: 'red'
}, {
  title: 'Christmas',
  recurring: { repeat: 'yearly', month: 12, day: 24 }
}]
height Number, String undefined Sets the height of the calendar. The height of the calendar view impacts the number of labels that fit into a table cell. A show more label will be displayed for events that don't fit.
invalid Array undefined An array containing the invalid values. Must be an array containing dates (Javascript Date objects, ISO 8601 strings, or moment objects), or objects with the following properties:
  • start: Date, String, Object - Start date of the calendar days which should be invalid.
  • end: Date, String, Object - End date of the calendar days which should be invalid.
  • recurring: String, Object - Recurrence rule for recurring invalid days.
labels Array undefined Specify labels for calendar days. A label object can have the following properties:
  • date Date, String, Object - Date of the calendar label.
  • start Date, String, Object - Start date of the calendar label.
  • end Date, String, Object - End date of the calendar label.
  • color String - The color of the label, can be any valid CSS color ('red', '#ff0000', 'rgb(255,0,0)', etc.).
  • text String - The text of the label.
  • recurring: String, Object - Recurrence rule for recurring labels.
The dates can be specified as Javascript Date objects, ISO 8601 strings, or moment objects.
The labels can be combined with the colors option.
Example
labels: [{
  start: new Date(2020, 2, 23),
  end: new Date(2020, 2, 24),
  text: 'Conference',
  color: 'red'
}, {
  text: 'Christmas',
  recurring: { repeat: 'yearly', month: 12, day: 24 }
}]
marked Array undefined Mark certain dates on the calendar. Must be an array containing dates (Javascript Date objects, ISO 8601 strings, or moment objects), or objects with the following properties:
  • date Date, String, Object - Date of the day to be marked.
  • start Date, String, Object - Start date of the days to be marked.
  • end Date, String, Object - End date of the days to be marked.
  • color String - The color of the mark, can be any valid CSS color ('red', '#ff0000', 'rgb(255,0,0)', etc.).
  • recurring: String, Object - Recurrence rule for recurring marked days.
The dates can be specified as Javascript Date objects, ISO 8601 strings, or moment objects.
The marked option can be combined with the colors option.
Example
marked: [
  new Date(2020, 2, 15),
  new Date(2020, 2, 22),
  {
    start: new Date(2020, 2, 23),
    end: new Date(2020, 2, 24),
    color: 'red'
  },
  {
    color: 'green',
    recurring: { repeat: 'yearly', month: 12, day: 24 }
  }
]
max Date, String, Object undefined Maximum date and time that can be selected.
Date
$('#mydate').mobiscroll().calendar({
    max: new Date(2015, 7, 14)
});
Date and time
$('#mydatetime').mobiscroll().calendar({
    controls: ['calendar', 'time'],
    max: new Date(2015, 7, 14, 16, 57)
});
min Date, String, Object undefined Minimum date and time that can be selected.
Date
$('#mydate').mobiscroll().calendar({
    min: new Date(2015, 7, 14)
});
Date and time
$('#mydatetime').mobiscroll().calendar({
    controls: ['calendar', 'time'],
    min: new Date(2015, 7, 14, 16, 57)
});
renderAgenda Function undefined A render function to customize the agenda template. Should return the markup of an event list, to be used in the agenda listing. It receives the the following parameters:
  • events: Array - The events of the current view, grouped by day. A day object has the following properties:
    • date: String - The formatted date of the day.
    • events: Array - The list of events for the day. An event object has the following properties:
      • allDay: String - The localized all-day text in case of all day events.
      • end: String - The formatted end time, if the event is not all day.
      • id: String - The id of the event.
      • isMultiDay: Boolean - True if the event spans across multiple days.
      • lastDay: Boolean - True if it's rendered on the last day of a multiple event.
      • original: Object - The original event object.
      • start: String - The formatted start time, if the event is not all day.
      • title: String - The title of the event.
    • timestamp: Number - The timestamp of the day
  • options: Object - The current settings of the component.
renderEvent Function undefined

You can use the renderEvent option to customize the events that appear on the agenda and the popover. It should return the markup of the event. The Eventcalendar will take care of the positioning, but everything else (like background color, hover effect, etc.) is left to you.

If you are looking to customize only the content (ex. add custom elements) and don't want to bother with the styling of the event, you can use the renderEventContent option.

For customizing the events on other part of the Eventcalendar check out the customizing the events section

The render function will receive an event object as parameter. This data can be used to show event specific things on the agenda and popover. The object passed to the function has computed properties, as well as a reference to the original event it comes from:

  • allDay: String - The localized all-day text in case of all day events.
  • end: String - The formatted end time, if the event is not all day.
  • id: String - The id of the event.
  • isMultiDay: Boolean - True if the event spans across multiple days.
  • lastDay: Boolean - True if it's rendered on the last day of a multiple event.
  • original: Object - The original event object.
  • start: String - The formatted start time, if the event is not all day.
  • title: String - The title of the event.
renderEventContent Function undefined

You can use the renderEventContent option to customize the event content that appears on the agenda and the popover. It should return the markup that is added to the event. The Eventcalendar will take care of styling and you can focus on what you show inside of the event a.k.a the content.

If you are looking to fully customize the event (ex. add custom hover effects) you will need to use the renderEvent option. In that case you will only get the positioning done by the Eventcalendar and everything else is up to you.

For customizing the events on other part of the Eventcalendar check out the customizing the events section.

The render function will receive an event object as parameter. This data can be used to show event specific things on the agenda and popover. The object passed to the function has computed properties, as well as a reference to the original event it comes from:

  • allDay: String - The localized all-day text in case of all day events.
  • end: String - The formatted end time, if the event is not all day.
  • id: String - The id of the event.
  • isMultiDay: Boolean - True if the event spans across multiple days.
  • lastDay: Boolean - True if it's rendered on the last day of a multiple event.
  • original: Object - The original event object.
  • start: String - The formatted start time, if the event is not all day.
  • title: String - The title of the event.
renderHeader Function undefined

Use this option to customize the header of the Eventcalendar. It takes a function that should return the desired markup. In the returned markup, you can use custom html as well as the built in header components of the calendar.

Check out the customizing the header section for a more detailed description on built in components.

Example with built in components
function myCustomHeader() {
    return `<button mbsc-calendar-prev></button>
            <button mbsc-calendar-next></button>
            <div mbsc-calendar-nav></div>`;
}
renderLabel Function undefined

You can use the renderLabel option to fully customize the labels that appear on the calendar. It should return the markup of the event. The Eventcalendar will take care of the positioning, but everything else (like background color, hover effect, etc.) is left to you.

If you are looking to customize only the content (ex. add custom elements) and don't want to bother with the styling of the label, you can use the renderLabelContent option.

For customizing the events on other part of the Eventcalendar check out the customizing the events section

The render function will receive an event object as parameter. This data can be used to show event specific things on the calendar. The object passed to the function has computed properties, as well as a reference to the original event it comes from:

  • end: String - Computed property. It holds the formatted end time, if the event is not all day.
  • id: String - It holds the id of the event. If there's no id on the event object, this property is generated.
  • isMultiDay: Boolean - Computed property. It's true if the event spans across multiple days.
  • original: Object - Reference to the original event object. Any custom property on the event can be access through this property.
  • start: String - Computed property. It holds the formatted start time, if the event is not all day.
renderLabelContent Function undefined

You can use the renderLabelContent option to customize the label contents, that appears on the calendar. It should return the markup that is added to the label. The Eventcalendar will take care of styling and you can focus on what you show inside of the label a.k.a the content.

If you are looking to fully customize the label (ex. add custom hover effects) you will need to use the renderLabel option. In that case you will only get the positioning done by the Eventcalendar and everything else is up to you.

For customizing the events on other part of the Eventcalendar check out the customizing the events section

The render function will receive an event object as parameter. This data can be used to show event specific things on the calendar. The object passed to the function has computed properties, as well as a reference to the original event it comes from:

  • end: String - Computed property. It holds the formatted end time, if the event is not all day.
  • id: String - It holds the id of the event. If there's no id on the event object, this property is generated.
  • isMultiDay: Boolean - Computed property. It's true if the event spans across multiple days.
  • original: Object - Reference to the original event object. Any custom property on the event can be access through this property.
  • start: String - Computed property. It holds the formatted start time, if the event is not all day.
renderScheduleEvent Function undefined

You can use the renderScheduleEvent option to customize the events that appear on the scheduler. It should return the markup of the event. The Eventcalendar will take care of the positioning, but everything else (like background color, hover effect, etc.) is left to you.

If you are looking to customize only the content (ex. add custom elements) and don't want to bother with the styling of the event, you can use the renderScheduleEventContent option.

For customizing the events on other part of the Eventcalendar check out the customizing the events section

The render function will receive an event object as parameter. This data can be used to show event specific things on the scheduler. The object passed to the function has computed properties, as well as a reference to the original event it comes from:

  • allDay: String - The localized all-day text in case of all day events.
  • end: String - The formatted end time, if the event is not all day.
  • id: String - The id of the event.
  • isMultiDay: Boolean - True if the event spans across multiple days.
  • lastDay: Boolean - True if it's rendered on the last day of a multiple event.
  • original: Object - The original event object.
  • start: String - The formatted start time, if the event is not all day.
  • title: String - The title of the event.
renderScheduleEventContent Function undefined

You can use the renderScheduleEventContent option to customize the event content that appears on the scheduler. It should return the markup that is added to the event. The Eventcalendar will take care of styling and you can focus on what you show inside of the event a.k.a the content.

If you are looking to fully customize the event (ex. add custom hover effects) you will need to use the renderScheduleEvent option. In that case you will only get the positioning done by the Eventcalendar and everything else is up to you.

For customizing the events on other part of the Eventcalendar check out the customizing the events section

The render function will receive an event object as parameter. This data can be used to show event specific things on the scheduler. The object passed to the function has computed properties, as well as a reference to the original event it comes from:

  • allDay: String - The localized all-day text in case of all day events.
  • end: String - The formatted end time, if the event is not all day.
  • id: String - The id of the event.
  • isMultiDay: Boolean - True if the event spans across multiple days.
  • lastDay: Boolean - True if it's rendered on the last day of a multiple event.
  • original: Object - The original event object.
  • start: String - The formatted start time, if the event is not all day.
  • title: String - The title of the event.
responsive Object undefined Specify different settings for different viewport widths, in a form of an object, where the keys are the name of the breakpoints, and the values are objects containing the settings for the given breakpoint.

There are five predefined breakpoints:
  • xsmall - min-width: 0px
  • small - min-width: 576px
  • medium - min-width: 768px
  • large - min-width: 992px
  • xlarge - min-width: 1200px
Custom breakpoints can be defined by passing an object containing the breakpoint property specifying the min-width in pixels. Example:
responsive: {
    xsmall: {
        view: {
            calendar: {
                type: 'week'
            },
            agenda: {
                type: 'day'
            }
        }
    },
    custom: { // Custom breakpoint
        breakpoint: 600,
        view: {
            calendar: {
                labels: true
            }
        }
    }
}
selectedDate Date, String, Object undefined Specifies the selected date on the calendar.
showControls Boolean true Shows or hides the calendar header controls: the previous and next buttons, and the current view button together with the year and month picker.
theme String undefined Sets the visual appearance of the component.

If it is 'auto' or undefined, the theme will automatically be chosen based on the platform.

Supplied themes:
  • 'ios' - iOS theme
  • 'material' - Material theme
  • 'windows' - Windows theme
It's possible to modify theme colors or create custom themes.
Make sure that the theme you set is included in the downloaded package.
themeVariant String undefined Controls which variant of the theme will be used (light or dark).

Possible values:
  • 'light' - Use the light variant of the theme.
  • 'dark' - Use the dark variant of the theme.
  • 'auto' or undefined - Detect the preferred system theme on devices where this is supported.

To use the setting with custom themes, make sure to create two custom themes, where the dark version has the same name as the light one, suffixed with '-dark', e.g.: 'my-theme' and 'my-theme-dark'.
valid Object null Can be used to override invalid dates and times. E.g. if every Thursday is set to invalid, but you want May 15th, 2014 to be valid, you can do it using the valid option. The syntax is the same as for the invalid option.
It's important if you want to use the valid setting together with invalid make sure to set: invalid day with valid day, invalid time with valid time or both invalid date and time with valid date and time. So in case you use an invalid day and a valid time, this will not override the invalid setting.
A sample configuration
invalid: [
    { start: '00:00', end: '23:59' }, // Invalid time
    { start: new Date(2018, 11, 21), end: new Date(2018, 11, 31) } // Invalid date
],
valid: [
    { start: '09:00', end: '20:00' }, // Valid time
    { start: new Date(2018, 11, 26), end: new Date(2018, 11, 30) } // Valid date
]
view Object { calendar: { type: 'month', popover: true } } Configures the event calendar view elements.

Properties

  • calendar: Object - Configures the calendar view. If omitted, no calendar will be displayed.
    Properties:
    • type: String (default 'month') - Sets the calendar type. Possible values: 'month', 'week'.
    • size: Number - Specifies the number of displayed months or weeks (depending on the specified type).
    • count: Boolean (default false) - If true, it will display the number of events on days with events.
    • outerDays: Boolean (default false) - Show or hide days from previous and next months. Hiding only works for type: 'month'.
    • labels: Boolean (default false) - Enable displaying events as labels on calendar days. To display multiple events on a day, set the calendar height to an appropriate value, using the calendarHeight setting, The events will be displayed in the available space. If there are more events for a day, than the available space, a label with "x more" text will be displayed, which opens the popover showing all the events for the given day.
    • popover: Boolean (default undefined) - Enable popover for event listing on days containing events. If not explicitly defined, the popover will not show up if event listing is used. If event labels are used, popover will only show up for days where all labels do not fit on the calendar, and a "more" label is present.
    • popoverClass: String (default undefined) - A CSS class that's added to the popover element. Can be used to customize the styling of the popover on a calendar basis.
    • scroll: String (default 'horizontal') - Specifies the direction of the calendar scroll. Can be 'horizontal' or 'vertical'.
    • weekNumbers: Boolean (default false) - Show or hide week numbers.
  • agenda: Object - Configures the event list. If omitted, no event list will be displayed.
    Properties:
    • type: String (default undefined) - Sets the list type. Possible values: 'year', 'month', 'week', 'day'.
      If calendar is also displayed, only month, week and day values are supported.
      In case of month and week, the type and size should match the calendar type and size.
      In case of day type events on the selected calendar day will be displayed, so size will always be 1.
    • size: Number (default 1) - Specifies the number of years, months, weeks or days included in the list (depending on the specified type).
    • scrollable: Boolean (default false) - Setting this to true makes the event listing independently scrollable. There are two prerequisites for making this work:

      1 - The calendar needs to be to placed inside a container which has a height. This can be either a fixed height, a height in percentage, or a flex height. When the calendar is placed directly in a container with a fixed height, it will work out of the box.
      If the height of the container is specified in percentage, e.g. you'd like to fill the full page height, you need to make sure that all parent elements also have height: 100% specified, up until the body and html elements, or until the closest parent which has a fixed height.
      If the container is inside a parent with flex layout, it will also work out of the box.

      2 - The event list has a minimum calculated height of 200px - the result of the container height minus the height of the calendar header minus the height of the displayed calendar rows. If the calculated height is less then 200px, the event list will not be scrollable.
  • schedule: Object - Configures the schedule view. If omitted, no schedule will be displayed.
    Properties:
    • type: String (default 'week') - Sets the schedule type. Possible values: 'day', 'week'.
    • days: Boolean (default true) - Show or hide week days above the schedule grid.

Example

view: {
  calendar: {
    type: 'week',
    size: 2
  },
  agenda: {
    type: 'week',
    size: 2
  }
}
width Number, String undefined Sets the width of the calendar.

Events

Name Description
onCellClick(event, inst) Triggered when a cell is clicked on the calendar or on the schedule grid.

Parameters

  • event: Object - The event object has the following properties:
    • date: Date - The date of the clicked cell.
    • domEvent: Event The DOM event of the click.
    • events: Array - The events for the clicked date.
    • selected: Boolean - Specifies if the day is currently selected or not (before it was clicked).
    • target: HTMLElement - The DOM element of the clicked cell.
  • inst: Object - The instance object of the eventcalendar.

Example

$('#mobiscroll').mobiscroll().eventcalendar({
    onCellClick: function (event, inst) {
    }
});
onDestroy(event, inst) Triggered when the component is destroyed.

Parameters

  • event: Object - The event object.
  • inst: Object - The instance object of the eventcalendar.

Example

$('#mobiscroll').mobiscroll().eventcalendar({
    onDestroy: function (event, inst) {
    }
});
onEventClick(event, inst) Triggered when an event is clicked.

Parameters

  • event: Object - The event object has the following properties:
    • date: Date - The date of the day on which the event was clicked.
    • domEvent: Event - The DOM event of the click.
    • event: Object - The clicked calendar event.
  • inst: Object - The instance object of the eventcalendar.

Example

$('#mobiscroll').mobiscroll().eventcalendar({
    onEventClick: function (event, inst) {
    }
});
onInit(event, inst) Triggered when the component is initialized.

Parameters

  • event: Object - The event object.
  • inst: Object - The instance object of the eventcalendar.

Example

$('#mobiscroll').mobiscroll().eventcalendar({
    onInit: function (event, inst) {
    }
});
onLabelClick(event, inst) Triggered when a label on the calendar is clicked.

Parameters

  • event: Object - The event object has the following properties:
    • date: Date - The date of the day on which the label was clicked.
    • domEvent: Event - The DOM event of the click.
    • label: Object - The original object of the label which was clicked, undefined in case of the "more" label.
    • labels: Array - An array containing each label object for the given day.
    • target: HTMLElement - The DOM element of the label.
  • inst: Object - The instance object of the eventcalendar.

Example

$('#mobiscroll').mobiscroll().eventcalendar({
    onLabelClick: function (event, inst) {
    }
});
onMarkupReady(event, inst) Triggered when the html markup of the component is generated, but it is not yet shown. It is useful, if you want to make modifications to the markup (e.g. add custom elements), before the positioning runs.

Parameters

  • event: Object - The event object has the following properties:
    • target: Object - The DOM element containing the generated html.
  • inst: Object - The instance object of the eventcalendar.

Example

$('#mobiscroll').mobiscroll().eventcalendar({
    onMarkupReady: function (event, inst) {
    }
});
onPageChange(event, inst) Triggered when the calendar page is changed (month or week, with buttons or swipe).

Parameters

  • event: Object - The event object has the following property:
    • firstDay: Date - The first day of the displayed page.
    • lastDay: Date - The last day of the displayed page.
  • inst: Object - The instance object of the eventcalendar.

Example

$('#mobiscroll').mobiscroll().eventcalendar({
    onPageChange: function (event, inst) {
    }
});
onPageLoaded(event, inst) Triggered when the calendar page is changed (month or week, with buttons or swipe) and the animation has finished.

Parameters

  • event: Object - The event object has the following property:
    • firstDay: Date - The first day of the displayed page.
    • lastDay: Date - The last day of the displayed page.
  • inst: Object - The instance object of the eventcalendar.

Example

$('#mobiscroll').mobiscroll().eventcalendar({
    onPageLoaded: function (event, inst) {
    }
});
onPageLoading(event, inst) Triggered before the markup of a calendar page (month or week) is starting to render.

Parameters

  • event: Object - The event object has the following property:
    • firstDay: Date - The first day of the displayed page.
    • lastDay: Date - The last day of the displayed page.
  • inst: Object - The instance object of the eventcalendar.

Example

$('#mobiscroll').mobiscroll().eventcalendar({
    onPageLoading: function (event, inst) {
    }
});
onSelectedDateChange(event, inst) Triggered when the selected date is changed.

Parameters

  • event: Object - The event object has the following properties:
    • date: Date - The selected date.
  • inst: Object - The instance object of the eventcalendar.

Example

$('#mobiscroll').mobiscroll().eventcalendar({
    onSelectedDateChange: function (event, inst) {
    }
});

Methods

Name Description
addEvent(events) Adds one or more events to the event list.

Parameters

  • events: Object or Array - The javascript event object(s) to add.

Returns: Array

  • An array containing the list of IDs generated for the events.

Example

Methods can be called on an instance. For more details see calling methods
// With selector
$('#mobiscroll').mobiscroll('addEvent', {
    start: new Date(2016, 1, 1),
    end: new Date(2016, 1, 2),
    title: 'Conference',
    color: 'red'
});

// With instance
mobiscrollInstance.addEvent({
    start: new Date(2016, 1, 1),
    end: new Date(2016, 1, 2),
    title: 'Conference',
    color: 'red'
});
destroy() Destroys the component. This will return the element back to its pre-init state.

Returns: Object

  • Returns the element back to its pre-init state.

Example

Methods can be called on an instance. For more details see calling methods
// With selector
$('#mobiscroll').mobiscroll('destroy');

// With instance
mobiscrollInstance.destroy();
getEvents() Returns the list of events.

Returns: Array

  • An array containing the event objects.

Example

Methods can be called on an instance. For more details see calling methods
// With selector
$('#mobiscroll').mobiscroll('getEvents');

// With instance
mobiscrollInstance.getEvents();
getInst() Returns the object instance.

Returns: Object

  • The object instance.

Example

Methods can be called on an instance. For more details see calling methods
// With selector
$('#mobiscroll').mobiscroll('getInst');

// With instance
mobiscrollInstance.getInst();
navigate(date) Navigates to the specified date on the calendar and optionally opens the event popover (only if popover is enabled and events exists for the specified date).

Parameters

  • date: Date, String, Object - Date to navigate to. Can be a Date object, ISO8601 date string, or moment object.

Example

Methods can be called on an instance. For more details see calling methods
// With selector
$('#mobiscroll').mobiscroll('navigate', new Date(2016, 1, 1));

// With instance
mobiscrollInstance.navigate(new Date(2016, 1, 1));
removeEvent(eventIDs) Removes one or more events from the event list based on IDs. For events without IDs, the IDs are generated internally. The generated ids are returned by the addEvent or getEvents methods.

Parameters

  • eventIDs: Array - An array containing the ID of one or more list events.

Example

Methods can be called on an instance. For more details see calling methods
// With selector
$('#mobiscroll').mobiscroll('removeEvent', [1, 3]);

// With instance
mobiscrollInstance.removeEvent([1, 3]);
setEvents(events) Set the events for the calendar. The actual list is overwritten. Returns the list of IDs generated for the events.

Parameters

  • events: Array - An array containing the events.

Returns: Array

  • An array containing the event IDs.

Example

Methods can be called on an instance. For more details see calling methods
// With selector
$('#mobiscroll').mobiscroll('setEvents', [{
    start: new Date(2016, 1, 1),
    end: new Date(2016, 1, 2),
    title: 'Conference',
    color: 'red'
}]);

// With instance
mobiscrollInstance.setEvents([{
    start: new Date(2016, 1, 1),
    end: new Date(2016, 1, 2),
    title: 'Conference',
    color: 'red'
}]);
updateEvent(event) Updates an event from the event list.

Parameters

  • event: Object - The event object to update.

Example

Methods can be called on an instance. For more details see calling methods
// With selector
$('#mobiscroll').mobiscroll('updateEvent', updatedEvent);

// With instance
mobiscrollInstance.updateEvent(updatedEvent);

Localization

Name Type Default value Description
allDayText String 'All-day' Text for all day events.
amText String 'am' Text for AM.
dateFormat String 'MM/DD/YYYY' The format for parsed and displayed dates.
  • M - month of year (no leading zero)
  • MM - month of year (two digit)
  • MMM - month name short
  • MMMM - month name long
  • D - day of month (no leading zero)
  • DD - day of month (two digit)
  • DDD - day of week (short)
  • DDDD - day of week (long)
  • YY - year (two digit)
  • YYYY - year (four digit)
  • '...' - literal text
  • '' - single quote
  • anything else - literal text
dayNames Array ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'] The list of long day names, starting from Sunday, for use as requested via the dateFormat setting.
dayNamesMin Array ['S', 'M', 'T', 'W', 'T', 'F', 'S'] The list of minimal day names, starting from Sunday, for use as requested via the dateFormat setting.
dayNamesShort Array ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'] The list of abbreviated day names, starting from Sunday, for use as requested via the dateFormat setting.
eventsText String 'events' Text for the events word (plural).
eventText String 'event' Text for the event word.
firstDay Integer 0 Set the first day of the week: Sunday is 0, Monday is 1, etc.
locale Object undefined Sets the language of the component. The locale option is an object containing all the translations for a given language. Mobiscroll supports a number of languages listed below. If a language is missing from the list, it can also be provided by the user. Here's a guide on how to write language modules.
Supported languages:
  • Arabic: localeAr
  • Bulgarian: localeBg
  • Catalan: localeCa
  • Czech: localeCs
  • Chinese: localeZh
  • Croatian: localeHr
  • Danish: localeDa
  • Dutch: localeNl
  • English: localeEn or undefined
  • English (UK): localeEnGB
  • Farsi: localeFa
  • German: localeDe
  • Greek: localeEl
  • Spanish: localeEs
  • Finnish: localeFi
  • French: localeFr
  • Hebrew: localeHe
  • Hindi: localeHi
  • Hungarian: localeHu
  • Italian: localeIt
  • Japanese: localeJa
  • Korean: localeKo
  • Lithuanian: localeLt
  • Norwegian: localeNo
  • Polish: localePl
  • Portuguese (Brazilian): localePtBR
  • Portuguese (European): localePtPT
  • Romanian: localeRo
  • Russian: localeRu
  • Russian (UA): localeRuUA
  • Slovak: localeSk
  • Serbian: localeSr
  • Thai: localeTh
  • Swedish:localeSv
  • Turkish: localeTr
  • Ukrainian: localeUa
  • Vietnamese: localeVi
$('#myexample').mobiscroll().eventcalendar({
  locale: mobiscroll.localeDe
});
monthNames Array ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'] The list of full month names, for use as requested via the dateFormat setting.
monthNamesShort Array ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'] The list of abbreviated month names, for use as requested via the dateFormat setting.
moreEventsPluralText String undefined Text for the "more" label on the calendar, when there's not enough space to display all the labels for the day, and there are more than one extra labels. The {count} inside the string will be replaced with the number of extra labels. When not specified, the moreEventsText setting is used for both plural and singular form.
moreEventsText String '{count}' more Text for the "more" label on the calendar, when there's not enough space to display all the labels for the day. The {count} inside the string will be replaced with the number of extra labels. Use the moreEventsPluralText as well, if the plural form is different.
noEventsText String 'No events' Text for empty event list.
pmText String 'pm' Text for PM.
rtl Boolean false Right to left display.
timeFormat String 'hh:ii A' The format for parsed and displayed dates
  • h - 12 hour format (no leading zero)
  • hh - 12 hour format (leading zero)
  • H - 24 hour format (no leading zero)
  • HH - 24 hour format (leading zero)
  • m - minutes (no leading zero)
  • mm - minutes (leading zero)
  • s - seconds (no leading zero)
  • ss - seconds (leading zero)
  • a - lowercase am/pm
  • A - uppercase AM/PM
  • '...' - literal text
  • '' - single quote
  • anything else - literal text

Customizing the appearance

While the provided pre-built themes are enough in many use cases, most of the times on top of adapting to a specific platform, you'd also like to match a brand or color scheme. Mobiscroll provides various ways to achieve this:

Override the Sass Color Variables

A convenient way to customize the colors of the Mobiscroll components is to override the Sass color variables.

Let's say your branding uses a nice red accent color, and you'd like that color to appear on the Mobiscroll components as well, while still using platform specific themes (e.g. ios on iOS devices, material on Android devices, and mobiscroll on desktop). You can override the accent color for every theme:

$mbsc-ios-accent: #e61d2a;
$mbsc-material-accent: #e61d2a;
$mbsc-mobiscroll-accent: #e61d2a;

@import "~@mobiscroll/JQuery/dist/css/mobiscroll.jquery.scss"
It's important that you override the variables BEFORE the scss file import, otherwise it won't make any difference.
Here's a complete guide on how to set up Mobiscroll with SASS support

You can also customize the colors on many levels:

  1. Theme specific variables (ex. $mbsc-material-background, $mbsc-ios-dark-text) are applied to all components in a theme. Complete list of variables here.
  2. Component specific global variables (ex. $mbsc-card-background-light, $mbsc-listview-text-dark) are applied to all themes for a specific component.
  3. Component and theme specific variables (ex. $mbsc-ios-dark-form-background, $mbsc-material-input-text) are applied to a specific theme and a specific component.

Hereinafter you will see all the variables that are specific to the Eventcalendar component or affect its look:

Global variables

These variables are applied to all base themes: iOS, material, windows and mobiscroll.
They all come in pairs. One for the light and one for the dark variant in each theme.

Variable name Description
$mbsc-calendar-background-light Sets the background color of the Eventcalendar
$mbsc-calendar-background-dark
$mbsc-calendar-text-light Sets the text color of the Eventcalendar
$mbsc-calendar-text-dark
$mbsc-calendar-accent-light Sets the accent color of the Eventcalendar
$mbsc-calendar-accent-dark
$mbsc-calendar-border-light Sets the color of the border
$mbsc-calendar-border-dark
$mbsc-calendar-mark-light Sets the default color of the mark on marked days
$mbsc-calendar-mark-dark

If you really want to get sophisticated or if a color doesn't look good on a specific theme and you want to overwrite it, you can fine tune all of the above variables individually for each theme. Below are the complete list of variables broken down to themes:

iOS theme

Variable name Default value Description
$mbsc-ios-calendar-background
#f7f7f7
The Eventcalendar background color
$mbsc-ios-calendar-text
#000000
The Eventcalendar text color
$mbsc-ios-calendar-accent
#007bff
The Eventcalendar accent color
$mbsc-ios-calendar-border
#cccccc
Sets the color of the border
$mbsc-ios-calendar-mark
#cccccc
Sets the default color of the mark on marked days

iOS Dark theme

$mbsc-ios-dark-calendar-background
##000000
The Eventcalendar background color
$mbsc-ios-dark-calendar-text
#ffffff
The Eventcalendar text color
$mbsc-ios-dark-calendar-accent
#ff8400
The Eventcalendar accent color
$mbsc-ios-dark-calendar-border
#333333
Sets the color of the border
$mbsc-ios-dark-calendar-mark
#333333
Sets the default color of the mark on marked days

Calendar view

Indication on what the color variables affect

Agenda view

Indication on what the color variables affect

Schedule view

Indication on what the color variables affect

Windows theme

Variable name Default value Description
$mbsc-windows-calendar-background
#ffffff
The Eventcalendar background color
$mbsc-windows-calendar-text
#333333
The Eventcalendar text color
$mbsc-windows-calendar-accent
#0078d7
The Eventcalendar accent color
$mbsc-windows-calendar-border
#e6e6e6
Sets the color of the border
$mbsc-windows-calendar-mark
rgba(51, 51, 51, 0.5);
Sets the default color of the mark on marked days

Windows Dark theme

Variable name Default value Description
$mbsc-windows-dark-calendar-background
#1a1a1a
The Eventcalendar background color
$mbsc-windows-dark-calendar-text
#ffffff
The Eventcalendar text color
$mbsc-windows-dark-calendar-accent
#0078d7
The Eventcalendar accent color
$mbsc-windows-dark-calendar-border
#343434
Sets the color of the border
$mbsc-windows-dark-calendar-mark
rgba(255, 255, 255, 0.5);
Sets the default color of the mark on marked days

Calendar view

Indication on what the color variables affect

Agenda view

Indication on what the color variables affect

Schedule view

Indication on what the color variables affect

Material theme

Variable name Default value Description
$mbsc-material-calendar-background
#ffffff
The Eventcalendar background color
$mbsc-material-calendar-text
#303030
The Eventcalendar text color
$mbsc-material-calendar-accent
#1a73e8
The Eventcalendar accent color
$mbsc-material-calendar-border
#cfcfcf
Sets the color of the border
$mbsc-material-calendar-mark
##1a73e8
Sets the default color of the mark on marked days

Material Dark theme

Variable name Default value Description
$mbsc-material-dark-calendar-background
#000000
The Eventcalendar background color
$mbsc-material-dark-calendar-text
#ffffff
The Eventcalendar text color
$mbsc-material-dark-calendar-accent
#87b0f3
The Eventcalendar accent color
$mbsc-material-dark-calendar-border
#2b2b2b
Sets the color of the border
$mbsc-material-dark-calendar-mark
#87b0f3
Sets the default color of the mark on marked days

Calendar view

Indication on what the color variables affect

Agenda view

Indication on what the color variables affect

Schedule view

Indication on what the color variables affect