General Calendar Cards Color Date & Time Event Calendar Forms Grid Layout Image Listview Measurement Navigation Number Numpad Option List Page Popup Range Scroller Scrollview Select Timer Timespan Treelist Tools Accessibility

Calendar

The Mobiscroll Calendar is the Date & Time Scroller on Steroids. It is a blend of a regular Calendar and the flexible Date & Time Scroller. The Calendar gives the user an overview of the day in week and the month. This makes it easy to spot weekends, holidays and invalid days.

Starting from version 4.2.0 it is also possible to pass ISO 8601 date strings or moment objects as well, instead of just javascript date objects, for every setting where dates are used.
The format of the returned value(s) can be specified using the returnFormat setting.

Basic usage

Create a calendar with default functionality:

Components

Simple examples with ngModel
<mbsc-calendar [(ngModel)]="birthday">My Birthday</mbsc-calendar>
<!-- setting theme -->
<mbsc-calendar [(ngModel)]="birthday" theme="ios">My Birthday</mbsc-calendar>
<!-- setting display -->
<mbsc-calendar [(ngModel)]="birthday" display="bottom">My Birthday</mbsc-calendar>
Using inline opions to customize the calendar
<mbsc-calendar [(ngModel)]="holidays" select="multiple" [invalid]="['w0', 'w6']">My Holidays</mbsc-calendar>
<!-- week selection -->
<mbsc-calendar [(ngModel)]="holidays" selectType="week">My Holidays</mbsc-calendar>
<!-- using a options object -->
<mbsc-calendar [(ngModel)]="birthday" [options]="myCalendarOptions" display="bottom">My Birthday</mbsc-calendar>
import { MbscCalendarOptions } from '../lib/mobiscroll/js/mobiscroll.angular.min.js';

export class MyExampleClass {
    myCalendarOptions: MbscCalendarOptions = {
        display: 'top',
        theme: 'ios',
        select: 'single'
    };

    birthday: Date;
    holidays: Array<Date> = [];
}

Passing events

All events can be used inline with the component. When passing event handlers inline, the instance of the component becomes the inst property of the event object.

Passing inline event handlers
<mbsc-calendar [(ngModel)]="birthday" (onSet)="birthdaySet()">My Birthday</mbsc-calendar>
<!-- with default parameters -->
<mbsc-calendar [(ngModel)]="birthday" (onSet)="withDefaultEvent($event)">My Birthday</mbsc-calendar>
<!-- with additional parameters -->
<mbsc-calendar [(ngModel)]="birthday" (onSet)="withAdditionalEvent($event, 'myAddition')">My Birthday</mbsc-calendar>
export class MyExampleClass {
    birthday: Date;
    // simple handler without any parameters
    birthdaySet() {
        console.log('simple handler'); // prints 'simple handler'
    }

    // event handler with the default event parameter
    withDefaultEvent(event: any) {
        console.log(event, event.inst); // prints the event object and the mobiscroll calendar control instance
    }

    // event handler with additional parameters
    withAdditionalEvent(event: any, addition: string) {
        console.log(addition); // prints 'myAddition'
    }
}

If you need more customization options on the element, you can use the directives as follows

Directives

Here is an example for the calendar directive with ngModel
@Component({
    selector: 'my-example',
    template: `<input [(ngModel)]="birthday" mbsc-calendar />`
})
export class MyExampleComponent {
    birthday: Date = new Date();
}
Example for the calendar directive without ngModel
@Component({
    selector: 'my-example',
    template: `<input [(mbsc-calendar)]="birthday" />`
})
export class MyExampleComponent {
    birthday: Date = new Date();
}
Example for the calendar directive with additional settings
import { MbscCalendarOptions } from '../lib/mobiscroll/js/mobiscroll.angular.min.js';
@Component({
    selector: 'my-example',
    template: `<input [(ngModel)]="birthday" mbsc-calendar [mbsc-options]="myBirthdaySettings" />`
})
export class MyExampleComponent {
    birthday: Date = new Date();
    myBirthdaySettings: MbscCalendarOptions = {
        theme: 'ios',
        display: 'bottom'
    };
}

With Ionic

Using with Ionic
<ion-item>
    <ion-label>My Birthday</ion-label>
    <ion-input [(ngModel)]="birthday" mbsc-calendar ></ion-input>
</ion-item>
<ion-item>
    <ion-label>My Birthday</ion-label>
    <ion-input [(ngModel)]="birthday" mbsc-calendar [mbsc-options]="myBirthdaySettings"></ion-input>
</ion-item>

Calendar with week selection

Create a calendar with week selection. Week selection will start on Saturday and end on next Friday (defined by the firstSelectDaysetting). Note that all the days of the week are passed.

Example for the calendar week selection
import { MbscCalendarOptions } from '../lib/mobiscroll/js/mobiscroll.angular.min.js';
@Component({
    selector: 'my-example',
    template: `<input [(ngModel)]="holiday" mbsc-calendar [mbsc-options]="holidaySettings" />`
})
export class MyExampleComponent {
    holiday: Array<Date> = [
        new Date(2013, 2, 23), 
        new Date(2013, 2, 24), 
        new Date(2013, 2, 25), 
        new Date(2013, 2, 26),
        new Date(2013, 2, 27),
        new Date(2013, 2, 28),
        new Date(2013, 2, 29)
    ];
    holidaySettings: MbscCalendarOptions = {
        display: 'inline',
        controls: ['calendar'],
        selectType: 'week',
        firstSelectDay: 6, // Weeks will be selected from Saturday to next Friday
    };
}

Calendar with marked days

Create a calendar with marked days loaded dynamically in the onPageChange event. Previous and next months are always preloaded, so marked days must be loaded for the previous and next months as well.

Example for the calendar with marked days and multiselection
@Component({
    selector: 'my-example',
    template: `<mbsc-calendar 
        [(ngModel)]="holiday" 
        [marked]="markedDays"
        select="multiple"
        (onPageChange)="changeMonth($event)">Holiday</mbsc-calendar>`
})
export class MyExampleComponent {
    holiday: Array<Date> = [new Date(2013, 2, 29)];

    markedDays: Array<any> = [ // Initially marked days
        new Date(2013, 5, 6),
        new Date(2013, 5, 10)
    ];
        
    changeMonth(event: any) {
        var year = event.year,
            month = event.month;
            
        // Load marked days for (year, month), (year, month - 1), (year, month + 1)
       
        // Update marked array
        this.markedDays = [ 
            new Date(year, month - 1, 15), 
            new Date(year, month, 15), 
            new Date(year, month + 1, 15),
            '5/1', 
            '12/24', 
            '12/25'
        ];
    }
}
Example with marked days loaded dynamically by AJAX
import { Http } from '@angular/http'; // NOTE: don't forget to add the HttpModule to imports in app.module.ts
import { ViewChild, Component, AfterViewInit } from '@angular/core';

@Component({
    selector: 'my-example',
    template: `<mbsc-calendar [marked]="marks" [(ngModel)]="meetingDate">Meeting Date</mbsc-calendar>`
})
export class MyExampleComponent implements AfterViewInit {
    meetingDate: Date;

    constructor(private http: Http) { }

    marks: Array<any> = [];

    ngAfterViewInit() {
        this.http
            .get('meetingmarks.json')
            .subscribe(resp => {
                // parse the response and update the array
                this.marks = JSON.parse(resp._body); // marked days will work with ISO 8601 date strings from version 4.2.1
            });
    }
}

Modules

The MbscCalendarModule can be used to import all the directives and components from below.

Directives

Directive Data type Description
[(mbsc-calendar)] Date or Array<Date> Directve for the calendar
[mbsc-options] MbscCalendarOptions Directive used to pass the calendar options

Components

Component Data type Description
<mbsc-calendar> Date or Array<Date> Component for the calendar

The following options can be used as attributes to customize the calendar component.

Options

Name Type Default value Description
anchor String or HTMLElement undefined Specifies the anchor element for positioning, if display is set to 'bubble'. If undefined, it defaults to the element on which the component was initialized.
animate String or Boolean undefined Animation to use for show/hide (if display is not inline). Possible values:
  • 'fade'
  • 'flip'
  • 'pop'
  • 'swing'
  • 'slidevertical'
  • 'slidehorizontal'
  • 'slidedown'
  • 'slideup'
If false, turns the animation off.
buttons Array ['set', 'cancel'] Buttons to display. Each item in the array will be a button. A button can be specified as a string, or as a button object.

When the passed array does not contain the predefined 'set' button, the auto-selection will be turned on. Selecting a value on the UI this way, will be set to the input immediately.
In single select mode, when an empty array is passed, the calendar will close on the first selection. Otherwise it can be closed with an overlay tap.

If a string, it must be one of the predefined buttons:
  • 'set' - Sets the value.
  • 'clear' - Clears the value.
  • 'cancel' - Dismisses the popup.
  • 'now' - Sets the current date and time.
To modify the text of the predefined buttons, you can use the setText, clearText , cancelText , nowText settings.

If an object, it may have the following properties:
  • text String - Text of the button.
  • handler String, Function - The function which will run when the button is pressed. If a string, it must be one of the predefined button handlers:
    • 'set' - Sets the value.
    • 'clear' - Clears the value.
    • 'cancel' - Dismisses the popup.
    • 'now' - Sets the current date and time.
  • icon String (Optional) - Icon of the button.
  • cssClass String (Optional) - Css class of the button.
Predefined and custom buttons example
buttons: [ 
    'set',
    { 
        text: 'Custom',
        icon: 'checkmark',
        cssClass: 'my-btn', 
        handler: (event, inst) => {
            alert('Custom button clicked!'); 
        } 
    },
    'cancel'
]
Predefined button handler example
buttons: [
    'set',
    { 
        text: 'Hide',
        handler: 'cancel',
        icon: 'close',
        cssClass: 'my-btn'
    }
]
calendarHeight Integer undefined Set the height of the calendar.
calendarScroll String 'horizontal' Possible values:
  • 'horizontal' - Horizontal scroll.
  • 'vertical' - Vertical scroll.
calendarSystem String 'gregorian' Defines the basic structure of the calendar. Possible values:
  • 'gregorian'
  • 'jalali' - Default system of the Persian calendar. Farsi language need to be included to the package.
  • 'hijri' - Arabic language need to be included to the package.
calendarWidth Integer undefined Set the width of the calendar (when layout is fixed).
circular Boolean or Array undefined If true, the scroll wheels are circular. If an array, it can be specified as a per wheel configuration, e.g. for 3 wheels: [true, false, false] - sets the first wheel circular. If not specified, if a wheel has more values than the number of displayed rows, the scroll wheel becomes circular.
closeOnOverlayTap Boolean true If true, the popup is closed on overlay tap/click.
colors Object null Change the color of certain dates on the calendar. There are four ways to specify days:
  • exact dates, both start and end dates - javascript Date objects , ISO 8601 strings, or moment objects for multi-day colors:
    { start: new Date(2014, 5, 5), end: new Date(2014, 5, 7), background: 'red' }
  • exact dates - javascript Date objects , ISO 8601 strings, or moment objects .
    { d: new Date(2014, 5, 5), background: 'red' }
  • days of week - number of week day (0 - 6) prefixed with 'w', e.g. 'w0', 'w6'.
  • days of month - number (e.g. every month's 2nd day) or a string in 'x/y' format (e.g. 12/24 means every year's 24th December).
Colored days can be changed dynamically by setting the inst.settings.colors object (e.g. in the onPageChange event).
Previous and next months are always preloaded, so if colored days are loaded at runtime, they must be loaded for the previous and next months as well.
The colors can be combined with the labels or marked settings.
A sample configuration
colors: [
    { d: new Date(2012,5,4), background: 'pink' },
    { d: new Date(2012,5,13), background: 'green' },
    { d: 'w0', background: 'yellow' },
    { d: 'w6', background: 'yellow' },
    { d: '5/1', background: 'red' },
    { d: '12/24', background: '#ff0000' },
    { d: '12/25', background: 'red' }
]
context String or HTMLElement 'body' Context in which mobiscroll is appended and positioned (if not inline). Can be a selector string or a DOM element.
controls Array ['calendar'] List of controls to show. Possible values:
  • ['time', 'calendar']
  • ['date', 'calendar']
  • ['calendar']
counter Boolean false If true and multiple selection is enabled, the number of selected items will be displayed in the header.
cssClass String undefined Applies custom css class to highest level element.
defaultValue Date
String
moment
Array
undefined Initial value of the calendar. If not specified, it always defaults to the current date and time.

If multiple selection is enabled, must be an array containing the initially selected dates.
disabled Boolean false Initial disabled state of the component.
display String 'center' Controls the positioning of the component. Possible options:
  • 'center' - The component appears as a popup at the center of the viewport.
  • 'inline' - If called on div element, the component is placed inside the div (overwriting existing content), otherwise is placed after the original element.
  • 'bubble' - The component appears as a bubble positioned to the element defined by the 'anchor' setting. By default the anchor is the original element.
  • 'top' - The component appears docked to the top of the viewport.
  • 'bottom' - The component appears docked to the bottom of the viewport.
firstSelectDay Integer 0 Set the first day of the selected week, if selectType option is set to 'week': Sunday is 0, Monday is 1, etc.
focusOnClose Boolean, String or jQuery Object true Element to focus after the popup is closed. If undefined, the original element will be focused. If false, no focusing will occur.
focusTrap Boolean true If not in inline mode, focus won't be allowed to leave the popup.
headerText Mixed false Specifies a custom string which appears in the popup header.
If the string contains the '{value}' substring, it is replaced with the formatted value of the calendar.
If it's set to false, the header is hidden.
If a function is passed, it receives the formatted value as parameter and the returned value appears in the header.
The default value depends on the theme:

Mobiscroll: false
Android Holo: {value}
Bootstrap: {value}
iOS: false
jQuery Mobile: {value}
Material: false
Windows Phone: false
height Number 40 Height in pixels of one item on the wheel. The default value depends on the theme:

Mobiscroll: 40
Android Holo: 36
Bootstrap: 40
iOS: 34
jQuery Mobile: 40
Material: 40
Windows Phone: 76
invalid Array null Can be used to set dates and/or times unselectable. It must be an array which can contain the following elements:
  • exact dates - javascript Date objects , ISO 8601 strings, or moment objects .
  • days of week - number of week day (0 - 6) prefixed with 'w', e.g. 'w0', 'w6'.
  • days of month - number (e.g. every month's 2nd day) or a string in 'x/y' format (e.g. 12/24 means every year's 24th December).
  • date range - { start: new Date(2014, 0, 27), end: new Date(2014, 2, 15) }
  • time range - { start: '12:00', end: '15:00' }
Invalid time ranges can be specified by passing objects containing start and end times (in 24 hours format), and an optional 'd' property which specifies on which day(s) should the invalid range apply (the format is same as above for the invalid days). If 'd' is not specified, the invalid range is applied on every day, except the days with specific rules.

You can override an invalid date or time with the valid option. For example if you set the Sundays invalid but you want a specific Sunday to be valid, you can use this setting.

Sample configuration
invalid: [
    '1/1', // 1st of January disabled
    '12/24', // Christmas disabled
    '12/25', // Christmas disabled
    'w0', // Sundays disabled
    { start: '00:00', end: '08:00' }, // Every day
    { start: '16:00', end: '23:59' }, // Every day
    { d: 'w6', start: '00:00', end: '08:59' }, // Saturday
    { d: 'w6', start: '17:00', end: '23:59' }, // Saturday
    new Date(2015,10,3), // exact date
    new Date(2016,6,11) // exact date
]
labels Object undefined Specify labels for calendar days.
  • exact dates, both start and end dates - javascript Date objects , ISO 8601 strings, or moment objects for multi-day labels:
    { start: new Date(2014, 5, 5), end: new Date(2014, 5, 7), text: 'My event' }
  • exact dates - javascript Date objects , ISO 8601 strings, or moment objects .
    { d: new Date(2014, 5, 5), text: 'My event' }
  • days of week - number of week day (0 - 6) prefixed with 'w':
    { d: 'w6', text: 'My event' }
  • days of month - number (e.g. every month's 2nd day) or a string in 'x/y' format (e.g. 12/24 means every year's 24th December):
    { d: 2, text: '2nd of the month' }
The labels can be combined with the colors setting.
A sample configuration
labels: [
    {
        start: new Date(2012,4,4),
        end: new Date(2012,4,5),
        text: 'Conference',
        color: 'red'
    },
    {
        d: '12/25',
        text: 'Christmas'
    }
]
layout String undefined Sets the layout of the component. Possible values:
  • 'liquid' - The calendar view expand to the maximum available width
    In 'top' or 'bottom' display mode this is the default behavior.
    In 'center'display mode it will also expand the height to the height of the viewport.
  • 'fixed' or undefined - The width and height of the calendar is controlled by the calendarWidth and calendarHeight options.
marked Object null Mark certain dates on the calendar. There are four ways to specify marked days:
  • exact dates, both start and end dates - javascript Date objects , ISO 8601 strings, or moment objects for multi-day marks:
    { start: new Date(2014, 5, 5), end: new Date(2014, 5, 7) }
  • exact dates - javascript Date objects , ISO 8601 strings, or moment objects .
  • days of week - number of week day (0 - 6) prefixed with 'w', e.g. 'w0', 'w6'.
  • days of month - number (e.g. every month's 2nd day) or a string in 'x/y' format (e.g. 12/24 means every year's 24th December).
Marked days can be changed dynamically by setting the inst.settings.marked object (e.g. in the onPageChange event).
Previous and next months are always preloaded, so if marked days are loaded at runtime, they must be loaded for the previous and next months as well.
The marked can be combined with the colors setting.
A sample configuration
marked: [
    new Date(2012,5,4),
    new Date(2012,5,13),
    'w0',
    'w6',
    { d: '5/1', color: 'red' },
    { d: '12/24', color: '#ff0000' },
    { d: '12/25', color: 'red' }
]
To display text and/or icons instead of the marks use the labels option.
max Date
String
moment
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)
});
maxWidth Number or Array undefined Maximum width of the wheels. If number, it is applied to all wheels, if an array, it is applied to each wheel separately.
min Date
String
moment
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)
});
minWidth Number or Array 80 Minimum width of the wheels in pixels. If number, it is applied to all wheels, if an array, it is applied to each wheel separately. The default value depends on the theme:

Mobiscroll: 80
Android Holo: 76
Bootstrap: 80
iOS: 55
jQuery Mobile: 80
Material: 80
Windows Phone: 76
months Number
String
1 Number of months to display. Set to 'auto' to decide on runtime how many months can be displayed.
mousewheel Boolean false Enables mousewheel / touchpad scroll.
multiline Number 1 If greater than 1, the wheel item's content will be wrapped into the specified number of lines. If the content is shorter, it will remain vertically centered.
outerMonthChange Boolean true Slide to previous or next month if days from previous or next months are selected.
readonly Boolean or Array false If true, the component is displayed, but the values are not selectable. If an array, it can be specified as a per wheel configuration, e.g. for 3 wheels: [true, false, false] - sets the first wheel readonly.
responsive Object null 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: {
    small: {
        display: 'bottom'
    },
    custom: { // Custom breakpoint
        breakpoint: 600,
        display: 'center'
    },
    large: {
        display: 'bubble'
    }
}
returnFormat String 'jsdate' Specifies the format in which the selected date(s) should be returned by the getVal method
Possible values:
  • 'jsdate' - Javascript date object
  • 'iso8601' - ISO 8601 date string.
  • 'locale' - Formatted date string based on the lang setting, or the dateFormat and timeFormat settings, if they are specified.
  • 'moment' - moment object. Ensure that moment.js is loaded.
rows Number 3 Number of visible rows on the wheel. The default value depends on the theme:

Mobiscroll: 5
Android Holo: 5
Bootstrap: 3
iOS: 5
jQuery Mobile: 3
Material: 3
Windows Phone: 3
scrollLock Boolean true Disables page scrolling on touchmove (if not in inline mode, and popup height is less than window height).
select String or Number 'single' Defines the selection of dates. Possible values:
  • 'single' - Only one date can be selected at once.
  • 'multiple' - Multiple dates can be selected.
  • Numeric value - The maximum number of dates that can be selected.
selectType String 'day'
  • 'day' - Only the day is selected
  • 'week' - A whole week is selected on day click
setOnDayTap Boolean false Set date and close the calendar when a day is selected.
showLabel Boolean true Show/hide labels above wheels. You can specify your labels with the labels option.
showOnFocus Boolean false - on desktop true - on mobile Pops up the component on element focus.
showOnTap Boolean true Pops up the component on element tap.
showOuterDays Boolean true Show or hide days from previous and next months.
Hiding outer days only works in case of month view, and not supported for week view.
showOverlay Boolean true Show or hide overlay.
showScrollArrows Boolean false Display scroll arrows for the wheels.
steps Object undefined Specifies steps for hours, minutes and seconds. Properties:
  • hour - steps between hours, 1 if not specified.
  • minute - steps between minutes, 1 if not specified.
  • second - steps between seconds, 1 if not specified.
  • zeroBased - if true, values start from 0, otherwise from values taken from minDate, false if not specified
Example
steps: { 
    minute: 15,
    second: 5,
    zeroBased: true
}
tabs Boolean undefined Show / hide tabs for calendar, date and time controls. If undefined, it is automatically decided to show or hide tabs based on available space. If only one control is passed, tabs are always hidden.
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. If the theme for the specific platform is not present, it will revert to the Mobiscroll theme.

Supplied themes:
  • 'bootstrap' - Bootstrap themes
  • 'ios' - new iOS 7, 8, 9 theme
  • 'material' - Material theme (Android 5.x)
  • 'material-dark' - Material dark theme (Android 5.x)
  • 'mobiscroll' - Mobiscroll theme
  • 'mobiscroll-dark' - Mobiscroll Dark theme
  • 'windows' - Windows theme
  • 'windows-dark' - Windows theme (dark version)
It's possible to modify theme colors or create custom themes.
Make sure that the theme you set is included in the downloaded package.
touchUi Boolean true Use true to render a touch optimized user interface, or false for a user interface optimized for pointer devices (mouse, touchpad). Can be used with the responsive setting to change the user interface based on viewport width.
valid Object null Can be used to override invalid dates and times. E.g. if every Thursday is set to invalid by 'w4', 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.
weekCounter String undefined
  • 'year' - Display week number in the year
  • 'month' - Display week number in the month
weekDays String 'short' Control the format of week days in the calendar header. Can be `full`, `short` or `min`.
weeks Number 6 Number of weeks to display.
width Number or Array 70 Exact width of the wheels, in pixels. Wheel content will be truncated, if it exceeds the width. If number, it is applied to all wheels, if an array, it is applied to each wheel separately.
yearChange Boolean true If true, the calendar can be navigated by year and by month separately from the header controls, otherwise only on a month by month basis.

Setting options runtime (changing options dynamically)

There are two ways to modify options after initalization

  1. Using the option method.

    The option method always triggers reinitialization. Most of the settings can be updated only this way, updating without initialization has no effect, because the markup is already generated. If the scroller was visible, the reinitialization hides it and it's not shown again automatically (except in inline display mode).

    Here is an example for the dynamic option change
    import { ViewChild } from '@angular/core';
    @Component({
        selector: 'my-example',
        template: `
            <input mbsc-calendar #myVariable="mobiscroll" [(ngModel)]="myExample"/>
            <button (click)="changeOptions()">Change theme and language</button>
        `
    })
    export class MyExample {
        @ViewChild('myVariable') 
        myRef: any;
    
        // Modify options
        changeOptions() {
            this.myRef.instance.option({
                theme: 'mobiscroll',
                lang: 'de'
            });
        }
    }
  2. Modify directly the settings object.

    Useful when changing dynamic settings, which do not need redraw (e.g. readonly, calendar marked days).

    Example
    import { ViewChild } from '@angular/core';
    @Component({
        selector: 'my-example',
        template: `
            <input mbsc-calendar #myVariable="mobiscroll" [mbsc-options]="myOptions"/>
            <button (click)="changeOptions()">Change readonly</button>
        `
    })
    export class MyExample {
        @ViewChild('myVariable') 
        myRef: any;
    
        // get instance and modify a setting
        changeOptions() {
            this.myRef.instance.settings.readonly = true;
        }
        
        // Modify settings in an event
        myOptions: any = {
            onBeforeShow: (event, inst) => {
                inst.settings.readonly = true;
            }
        }
    }

Events

Using arrow functions is recommended so you have access to your outer component instance inside event handlers through this reference.
When using the events inline (see here) the inst parameter is passed as a property to the event.
Name Description
onBeforeClose(event, inst) Triggered before the component closes. Close can be prevented by returning false from the handler function.

Parameters

  • event: Object - The event object has the following properties:
    • valueText: String - The selected value as text.
    • button: String - The name of the button which triggered the component to close ('set', or 'cancel').
  • inst: Object - The instance object of the calendar.

Example

export class MyExample {
    settings: any = {
        onBeforeClose: (event, inst) => {
        }
    }
}
onBeforeShow(event, inst) Triggered before the component is shown. It is useful if you want to modify the settings object before generating the markup. It can be used also to prevent the showing the control by returning false.

Parameters

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

Example

export class MyExample {
    settings: any = {
        onBeforeShow: (event, inst) => {
        }
    }
}
onCancel(event, inst) Allows you to define your own event when cancel is pressed.

Parameters

  • event: Object - The event object has the following properties:
    • valueText: String - The selected value as text.
  • inst: Object - The instance object of the calendar.

Example

export class MyExample {
    settings: any = {
        onCancel: (event, inst) => {
        }
    }
}
onChange(event, inst) Allows you to define your own event when a wheel value is changed.

Parameters

  • event: Object - The event object has the following properties:
    • valueText: String - The selected value as text.
  • inst: Object - The instance object of the calendar.

Example

export class MyExample {
    settings: any = {
        onChange: (event, inst) => {
        }
    }
}
onClear(event, inst) Triggered when the value is cleared.

Parameters

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

Example

export class MyExample {
    settings: any = {
        onClear: (event, inst) => {
        }
    }
}
onClose(event, inst) Triggered when the component is closed.

Parameters

  • event: Object - The event object has the following properties:
    • valueText: String - The selected value as text.
  • inst: Object - The instance object of the calendar.

Example

export class MyExample {
    settings: any = {
        onClose: (event, inst) => {
        }
    }
}
onDayChange(event, inst) Triggered when a day is selected on the calendar, but before the selection is actually done. Returning false from the handler function will prevent day selection.

Parameters

  • event: Object - The event object has the following properties:
    • date: The selected date as a Date object.
    • marked: If the day is marked, contains the marked object passed in the settings, otherwise false.
    • selected: Specifies if the day is currently selected or not (before the current selection).
    • target: The table cell HTML DOM element.
  • inst: Object - The instance object of the calendar.

Example

export class MyExample {
    settings: any = {
        onDayChange: (event, inst) => {
        }
    }
}
onDestroy(event, inst) Triggered when the component is destroyed.

Parameters

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

Example

export class MyExample {
    settings: any = {
        onDestroy: (event, inst) => {
        }
    }
}
onInit(event, inst) Triggered when the component is initialized.

Parameters

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

Example

export class MyExample {
    settings: any = {
        onInit: (event, inst) => {
        }
    }
}
onItemTap(event, inst) Triggered when the user taps an item on the wheel.

Parameters

  • event: Object - The event object has the following properties:
    • target: HTMLElement - The DOM element of the tapped item.
    • selected: Boolean - Selected state of the tapped item.
  • inst: Object - The instance object of the calendar.

Example

export class MyExample {
    settings: any = {
        onItemTap: (event, inst) => {
        }
    }
}
onLabelTap(event, inst) Triggered when the user taps/clicks on a label on the calendar.

Parameters

  • event: Object - The event object has the following properties:
    • date: Date - The date clicked.
    • domEvent: Event - The click/tap DOM event.
    • 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 calendar.

Example

export class MyExample {
    settings: any = {
        onLabelTap: (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 calendar.

Example

export class MyExample {
    settings: any = {
        onMarkupReady: (event, inst) => {
        }
    }
}
onPageChange(event, inst) Triggered when the user changes the calendar page (month or week, with buttons or swipe).

Parameters

  • event: Object - The event object has the following property:
    • firstDay: Date - The first day as Date object.
  • inst: Object - The instance object of the calendar.

Example

export class MyExample {
    settings: any = {
        onPageChange: (event, inst) => {
        }
    }
}
onPageLoaded(event, inst) Triggered when the user changes the calendar page (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 as Date object.
  • inst: Object - The instance object of the calendar.

Example

export class MyExample {
    settings: any = {
        onPageLoaded: (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 as Date object.
  • inst: Object - The instance object of the calendar.

Example

export class MyExample {
    settings: any = {
        onPageLoading: (event, inst) => {
        }
    }
}
onPosition(event, inst) Triggered when the component is positioned (on initial show and resize / orientation change).
Useful if dimensions needs to be modified before the positioning happens, e.g. set a custom width or height. Custom positioning can also be implemented here, in this case, returning false from the handler function will prevent the built in positioning.

Parameters

  • event: Object - The event object has the following properties:
    • target: Object - The DOM element containing the generated html.
    • windowWidth: Number - The window width.
    • windowHeight: Number - The window height.
  • inst: Object - The instance object of the calendar.

Example

export class MyExample {
    settings: any = {
        onPosition: (event, inst) => {
        }
    }
}
onSet(event, inst) Triggered when a value is set.

Parameters

  • event: Object - The event object has the following properties:
    • valueText: String - The selected value as text (if any).
  • inst: Object - The instance object of the calendar.

Example

export class MyExample {
    settings: any = {
        onSet: (event, inst) => {
        }
    }
}
onSetDate(event, inst) Gets called every time a date or time is selected (from wheels or from calendar, or programatically). It also runs on initial show.

Parameters

  • event: Object - The event object has the following properties:
    • date: The selected date as a Date object
    • control: The control on which the date was selected: calendar, date or time. It will be undefined on initial show, or if date was set programmatically.
  • inst: Object - The instance object of the calendar.

Example

export class MyExample {
    settings: any = {
        onSetDate: (event, inst) => {
        }
    }
}
onShow(event, inst) Triggered when the component is shown.

Parameters

  • event: Object - The event object has the following properties:
    • target: Object - The DOM element containing the generated html.
    • valueText: String - The selected value as text.
  • inst: Object - The instance object of the calendar.

Example

export class MyExample {
    settings: any = {
        onShow: (event, inst) => {
        }
    }
}
onTabChange(event, inst) This event is triggered when the tab is changed.

Parameters

  • event: Object - The event object has the following properties:
    • tab: String - Can be 'calendar', 'date' or 'time'.
  • inst: Object - The instance object of the calendar.

Example

export class MyExample {
    settings: any = {
        onTabChange: (event, inst) => {
        }
    }
}

Methods

Name Description
cancel() Hides the calendar and also invokes the onCancel event.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.cancel();
changeTab(tab) Changes the view to the specified tab, if tabs are present.

Parameters

  • tab: String - Can be 'calendar', 'date' or 'time'.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.changeTab('calendar');
clear() Clears the calendar value.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.clear();
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
mobiscrollInstance.destroy();
disable() Disables the calendar.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.disable();
enable() Enables the calendar.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.enable();
getInst() Returns the object instance.

Returns: Object

  • The object instance.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.getInst();
getVal([temp]) Returns the selected date.

Parameters

  • temp (Optional): Boolean - If true, temporary selected date is returned (prior clicking the Set button).

Returns: Array or Object

  • The selected date.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.getVal();
hide([ prevAnim ] [, btn ]) Hides the component.

Parameters

  • prevAnim (Optional): Boolean - If true, hide will not be animated.
  • btn (Optional): String - Specifies which button caused the component to hide, and it's passed to the onBeforeClose event.

Example

Methods can be called on an instance. For more details see calling methods
    mobiscrollInstance.hide();
    
isVisible() Returns a boolean indicating whether the component is visible or not.

Returns: Boolean

  • True if the component is visible, false if it's not.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.isVisible();
navigate(date [, animate ]) Display a specific month on the calendar without setting the date.

Parameters

  • date: Date - The specific month on the calendar.
  • animate (Optional): Boolean - If true, navigate will be animated.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.navigate(new Date(2016, 1, 1));
option(options) Sets one or more options for the component.

Parameters

  • options: Object - A map of option-value pairs to set.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.option({
    display: 'bottom',
    lang: 'de'
});
position([check]) Recalculates the position of the component (if not inline).

Parameters

  • check (Optional): Boolean - If true, the function checks if viewport size changed after last position call, if false or ommitted, position is recalculated anyway.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.position();
redraw() Redraws the calendar view, without reloading the data (the onPageLoading event will not trigger).

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.redraw();
refresh() Refreshes the calendar view.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.refresh();
select() Hides the calendar and also invokes the onSet event.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.select();
setVal(value [, fill ] [, change ] [, temp ]) Sets the calendar value.

Parameters

  • value: Array or Object - In case of a multiple select value must be an array with the selected values as Date objects.
  • fill (Optional): Boolean - If true, the associated input element is also updated with the new value.
  • change (Optional): Boolean - If false, change event won't be triggered on the input element.
  • temp (Optional): Boolean - If true, only temporary values are set.
If week selection is enabled, all the days of the selected weeks must be included in the list, when using the setValues method.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.setVal(new Date(2016, 1, 1));
show([ prevAnim ] [, prevFocus ]) Shows the component.

Parameters

  • prevAnim (Optional): Boolean - If true, show will not be animated.
  • prevFocus (Optional): Boolean - If true, the popup will not be focused right after show.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.show();
tap(el, handler) Attaches the handler function to the tap event of element el.

Parameters

  • el: Object - The element with tap event.
  • handler: Function - If the action was initiated with touch event, handler is called on touchend, otherwise on click.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.tap('#element', function () { alert("It's a tap!"); });

Localization

Name Type Default value Description
ampmText String '' Label for AM/PM wheel
amText String 'am' Text for AM
calendarText String 'Calendar' Text for Calendar tab
cancelText String 'Cancel' Text for Cancel button.
clearText String 'Clear' Text for Clear button.
dateFormat String 'mm/dd/yy' The format for parsed and displayed dates
  • m - month of year (no leading zero)
  • mm - month of year (two digit)
  • M - month name short
  • MM - month name long
  • d - day of month (no leading zero)
  • dd - day of month (two digit)
  • D - day of week (short)
  • DD - day of week (long)
  • y - year (two digit)
  • yy - year (four digit)
  • '...' - literal text
  • '' - single quote
  • anything else - literal text
dateText String 'Date' Text for Date tab
dateWheels String undefined Display order and formating for month/day/year wheels. Characters have the same meaning as in the dateFormat option. The options also controls if a specific wheel should appear or not, e.g. use 'mmyy' to display month and year wheels only, 'mmD ddy' to display both day of week and date on the day wheel.

If not specified, the order of the wheels will be taken from the dateFormat option, and the formating will be defined by the theme

Starting for 3.0.0-beta5 an experimental feature was introduced to display the whole date on one wheel. To activate this mode, the format of the date should be specified between | charchters:

dateWheels: '|D M d|' // Will produce 'Sun Sep 9'
            
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
daySuffix String undefined Additional string to display after the day on the wheel.
dayText String 'Day' Label for day wheel
firstDay Integer 0 Set the first day of the week: Sunday is 0, Monday is 1, etc.
headerText Mixed '{value}' Specifies a custom string which appears in the popup header. If the string contains '{value}' substring, it is replaced with the formatted value of the calendar. If it's set to false, the header is hidden. If a function is passed, it receives the formatted value as parameter and the returned value appears in the header
hourText String 'Hours' Label for hours wheel
lang String 'en-US' Language of the component. Based on the language string the component loads the language based default settings from the language modules.
Supported languages:
  • Arabic: 'ar'
  • Bulgarian: 'bg'
  • Catalan: 'ca'
  • Czech: 'cs'
  • Chinese: 'zh'
  • Croatian: 'hr'
  • Danish: 'da'
  • Dutch: 'nl'
  • English: 'en' or 'en-US' or undefined
  • English (UK): 'en-UK' or 'en-GB'
  • Farsi: 'fa'
  • German: 'de'
  • Greek: 'el'
  • Spanish: 'es'
  • Finnish: 'fi'
  • French: 'fr'
  • Hebrew: 'he'
  • Hindi: 'hi'
  • Croatian: 'hr'
  • Hungarian: 'hu'
  • Italian: 'it'
  • Japanese: 'ja'
  • Korean: 'ko'
  • Lithuanian: 'lt'
  • Norwegian: 'no'
  • Polish: 'pl'
  • Portuguese (Brazilian): 'pt-BR'
  • Portuguese (European): 'pt-PT'
  • Romanian: 'ro'
  • Russian: 'ru'
  • Russian (UA): 'ru-UA'
  • Slovak: 'sk'
  • Serbian: 'sr'
  • Thai: 'th'
  • Swedish: 'sv'
  • Turkish: 'tr'
  • Ukrainian: 'ua'
  • Vietnamese: 'vi'
minuteText String 'Minutes' Label for minutes wheel
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
monthSuffix String undefined Additional string to display after the month on the wheel.
monthText String 'Month' Label for month wheel
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.
nowText String 'Now' Label for the 'Now' button
pmText String 'pm' Text for PM
rtl Boolean false Right to left display.
secText String 'Seconds' Label for seconds wheel
selectedPluralText String '{count} selected' Specifies the plural form of the amount of selected items according to the rules of particular language. The '{count}' substring will be replaced with the number of selected items.
selectedText String '{count} selected' Specifies the amount of selected items according to the rules of particular language. The '{count}' substring will be replaced with the number of selected items.
setText String 'Set' Text for Set button.
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)
  • i - minutes (no leading zero)
  • ii - 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
timeText String 'Time' Text for Time tab
timeWheels String undefined Display order and formating of the time wheels on the calendar. Characters have the same meaning as in the timeFormat option.

If not specified, the order of the wheels will be taken from the timeFormat option, and the formating will be defined by the theme

Starting for 3.0.0-beta5 an experimental feature was introduced to display the whole time on one wheel. To activate this mode, the format of the time should be specified between | charchters:

timeWheels: '|h:ii A|' // Will produce '9:12 AM'
            
yearSuffix String undefined Additional string to display after the year on the wheel.
yearText String 'Year' Label for year wheel

Conversion functions

Name Parameters Description
formatValue function (data) Receives selected wheel values as an array and must return a string which will be set as the value of the associated input element.

By default it formats date based on the dateFormat and/or timeFormat settings.

If the default format function is overwritten, a matching parseValue function should also be defined. Example:
function myFormatValue(data) {
    // In case of 'mm/dd/yy' wheel format, an example data array: [8, 31, 2016]
    // Returns '2016-09-31'
    return data[2] + '-' + (data[0] < 9 ? '0' : '') + (data[0] + 1) + '-' + (data[1] < 10 ? '0' : '') + data[1];
}

<mbsc-calendar [formatValue]="myFormatValue">My calendar</mbsc-calendar>
parseValue function (valueText) Receives a string as parameter and must return an array containing the selected wheel values.

By default it parses the string into a date object based on the dateFormat and/or timeFormat settings and returns the parts of the date as an array.

If the default parse function is overwritten, a matching formatValue function should also be defined. Example:
function myParseValue(str) {
    var d = new Date(); // Default value
    if (str) {
        // Example string: '2016-09-31'
        str = str.split('-');
        d = new Date(str[0], str[1] - 1, str[2]);
    }
    return [d.getMonth(), d.getDate(), d.getFullYear()];
}

<mbsc-calendar [parseValue]="myParseValue">My calendar</mbsc-calendar>