Datepicker

The Datepicker component is the ultimate tool for selecting a single date and/or time, multiple dates or a date range.

Basic usage

The following example will create a datepicker with the default options.

By default the datepicker will be set up to single date selection with the calendar control.

$(function () {
    $("#date").mobiscroll().datepicker();
});

<input id="date"/>

For many more examples - simple and complex use-cases - check out the date picker demos for jquery.

Value Selection

The datepicker can be used for three major dates and time selection tasks:

1. Single value selection - a date, time or date-time - use the date & time or calendar
2. Multiple value selection - one or more dates - use the date picker or calendar
3. Range selection - a pair of start/end date, time or date-times - use the range picker

Single Value Selection

This is the default behavior, and it can also be initialized with the select: 'date' option. Depending on the controls option, we can use the datepicker this way to select either a single date or a single time or both (a single datetime).

$('#datepicker').mobiscroll().datepicker({
    select: 'date',
});

Multiple Value Selection

The selectMultiple option will enable us to select multiple dates on the calendar. The selected value in this case will be an array of dates instead of just a single date.

$('#datepicker').mobiscroll().datepicker({
    selectMultiple: true,
});

Range Selection

The datepicker can be used to select a date or a time range. The range selection feature can be activated with the select: 'range' option. The selected value in this case will be an array of dates with two values: the start and the end.

The controls option will tell the datepicker what kind of range do we want to select, a date range or a time range.

$('#datepicker').mobiscroll().datepicker({
    select: 'range',
});

Return values

The default type of return values is the JavaScript Date object, but Mobiscroll supports more types as well. The Datepicker will choose the type depending on the returnFormat option.

Here's a list on supported formats and some hints on where are they really usefull:

• 'jsdate'

  - Javascript date object - Ex. if you need to manipulate programmatically the selected value further, the Date object is a good starting point, since it has most of the functions for date ∧ time manipulation

• 'iso8601'

  - ISO 8601 date string - Ex. if you need to send the selected value to a server, or need to serialize it, the ISO8601 string is the way to go.

• 'locale'

  - Formatted date string based on the lang setting, or the dateFormat and timeFormat settings, if they are specified. It gives the most flexible formatting options.

• 'moment'

  - moment object - The Moment.js library helps in manipulating the date ∧ time values. It has many functions the built in JavaScript Date object doesn't. It is very convenient when working a lot with dates.

When working with 'moment', you need to ensure that your project includes the Moment.js library and also you will need to pass the moment libary reference to the Datepicker. Here's an example how:

var inst = $('#my-selector').mobiscroll().datepicker({ 
    moment: moment,
    returnFormat: 'moment',
}).mobiscroll('getInst');

// ... 
            
inst.getVal(); // will return a Moment object
        

Controls

The datepicker component can render different kinds of controls on the screen. These controls are referred to as the Calendar view, the Date picker, the Time picker and the Datetime picker. Each of these controls are suitable in different scenarios, depending on the use-case.

For example, the Date picker can be used for selecting a single date, as well as the Calendar view. But only the Calendar view can be used for selecting multiple dates.

$('#myBirthday').mobiscroll().datepicker({
    controls: ['date']
});
$('#kidsBirthday').mobiscroll().datepicker({
    controls: ['calendar'],
    selectMultiple: true,
});

• The Calendar view can be used for single or multiple date selection as well as date range selection. It is represented by the 'calendar' string. It is the default of the controls option.

• The Date picker can be used for single date selection or date range selection. It is represented by the 'date' string.

• The Time picker can be used for single time selection or time range selection. It can also be combined with other controls. It is represented by the 'time' string.

• The Datetime picker can be used for single date & time selection as well as date & time range selection. It is represented by the 'datetime' string.

Control combinations

Some controls can't be used in all situations. To have a better user experience, controls can be combined. The controls options takes an array of strings, with predefined values.

The Time picker control can be combined with either the Calendar view or the Date picker for extending the selection precision.

$('#myAppointment').mobiscroll().datepicker({
    controls: ['date', 'time'],
});
$('#myAppointment').mobiscroll().datepicker({
    controls: ['calendar', 'time'],
});

Customizing the Input

The datepicker, as explained below, can be used with one, two or no inputs.

Using without inputs

The first choice of input customization is to have no inputs at all. In this case rendering the component in inline display mode will leave out the use of inputs.

<div id="myAppointment"></div>

$('#myAppointment').mobiscroll().datepicker({
    display: 'inline',
});

Using with one input

The input element, you initialize the datepicker on, will be the element the formatted value will be filled in. This input element can be customized in any ways you want. You can provide css classes, or html attributes that will be taken into account, when initializing the picker.

<input id="myAppointment" class="any-class-you-want" placeholder="Click to select..." />

$('#myAppointment').mobiscroll().datepicker({
    theme: 'ios',
});

Using with two inputs

When selecting a range, you have basically two values to display: the start of the range and the end of the range. These can be shown in different inputs using the startInput and the endInput options.

<input id="start-input" placeholder="Start date" />
<input id="end-input" placeholder="End date" />
<div id="picker"></div>

$('#picker').mobiscroll().datepicker({
    select: 'range',
    startInput: '#start-input',
    endInput: '#end-input'
});

Display modes

The datepicker component can operate in two ways from the display option's point of view:

• Modal display modes
• "Live" selection

Modal display

Here comes the center, top, bottom displays, and also the anchored display when the touchUi option is true.

In these display modes, the picker shows up as a modal picker. When open, the selected value is stored as a temporary value until the set button is pressed. At that point the picker is closed and the value is commited to the input.

The above mentioned temporary value, when required, can be manipulated using the getTempVal() and setTempVal() instance methods. Whe the temporary value changes the onTempChange event is raised.

To get or change the selected value, that's set to the input, the getVal and setVal instance methods are available to use.

"Live" selection

Here come the inline display (which displays as an embedded control) and the anchored display when the touchUi options is false (on desktop devices).

In this case by default there is no set button to commit the value, so there's no temporary value like when the modal displays are used. What is shown on the picker, that is set directly to the input

To get or change the selected value, that's set to the input, the getVal and setVal instance methods are available to use.

Recurrence

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

Supported properties:

• repeatString - The frequency of the recurrence. String equivalent: FREQ.
  • 'daily' - Daily repeat
  • 'weekly' - Weekly repeat
  • 'monthly' - Monthly repeat
  • 'yearly' - Yearly repeat
• dayNumber - The day of the month in case of monthly and yearly repeat. String equivalent: BYMONTHDAY.
  Negative numbers are calculated from the end of the month, -1 meaning the last day of the month.
  Specifying multiple days for the rule is currently not supported.
  Rules like every first/second/third/fourth week day of month are currently not supported.
• monthNumber - Specify the month in case of yearly repeat. String equivalent: BYMONTH.
  Specifying multiple months for the rule is currently not supported.
• weekDaysString - Comma separated list of the week days ('SU', 'MO', 'TU', 'WE', 'TH', 'FR', 'SA') for the occurrences. String equivalent: BYDAY.
• countNumber - The number of occurrences. String equivalent: COUNT.
• fromDate, String, Object - The start date of the occurrences. String equivalent: DTSTART.
• until:Date, String, Object - The end date of the occurrences. String equivalent: UNTIL.
• intervalNumber - The time interval for the rule, e.g. every 3 days, or every 2 weeks. This depends on the repeat property. String equivalent: INTERVAL.

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

recurring: {
  repeat: 'daily',
  count: 5,
  interval: 2
}

recurring: 'FREQ=DAILY;COUNT=5;INTERVAL=2'

Examples

$('#datepicker').mobiscroll().datepicker({
    invalid: [{
        start: '00:00',
        end: '08:59',
        recurring: {
            repeat: 'daily'
        }
    }, {
        start: new Date(2020, 2, 18, 9, 0),
        end: new Date(2020, 2, 18, 17, 0),
        recurring: {
            repeat: 'daily',
            count: 5,
            interval: 2
        }
    }, {
        start: new Date(2020, 2, 17, 20, 0),
        end: new Date(2020, 2, 17, 22, 0),
        recurring: 'FREQ=WEEKLY;UNTIL=2020-06-17;BYDAY=MO,WE'
    }]
});

Customizing the calendar 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 renderCalendarHeader option.

$('#datepicker').mobiscroll().datepicker({
    renderCalendarHeader: 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:

• <button mbsc-calendar-prev></button> - Previous button component, that navigates to the previous month.
• <button mbsc-calendar-next></button> - Next button component, that navigates to the next month.
• <button mbsc-calendar-today></button> - Today button component, that navigates to the current date.
• <div mbsc-calendar-nav></div> - The title navigation component, that opens the year/month navigation.

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).

var myTitle = 'My Awesome title';
$('#datepicker).mobiscroll().datepicker({
    renderCalendarHeader: 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 Datepicker:

Options

buttons: [
    'set',
    {
        text: 'Custom',
        icon: 'checkmark',
        cssClass: 'my-btn', 
        handler: function (event) {
            alert('Custom button clicked!');
        }
    },
    'cancel'
]

buttons: [
    'set',
    {
        text: 'Hide',
        handler: 'cancel',
        icon: 'close',
        cssClass: 'my-btn'
    }
]

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' } }
]

invalid: [
    // Passing exact dates and times
    new Date(2021, 1, 7), // Date object
    '2021-10-15T12:00', // ISO 8601 string
    moment("2020-12-25"), // moment object

    // Passing invalid ranges
    { 
      // ISO 8601 strings
      start: '2021-10-15T12:00',
      end: '2021-10-18T13:00', 
      title: 'Company 10th anniversary',
    },
    {
      // Date objects
      allDay: true,
      start: new Date(2021, 2, 7),
      end: new Date(2021, 2, 9),
      title: 'Conference for the whole team',
    },
    {
      // Time range with recurrence
      start: '13:00',
      end: '12:00',
      recurring: { repeat: 'weekly', weekDays: 'MO,TU,WE,TH,FR' },
      title: 'Lunch break',
    },
    {
      // Disable weekends
      recurring: {
          repeat: 'weekly',
          weekDays: 'SA,SU'
      }
    }
];

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: [
  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 }
  }
]

function myCustomHeader() {
    return `<button mbsc-calendar-prev></button>
            <button mbsc-calendar-next></button>
            <div mbsc-calendar-nav></div>`;
}

responsive: {
    small: {
        display: 'bottom'
    },
    custom: { // Custom breakpoint
        breakpoint: 600,
        display: 'center'
    },
    large: {
        display: 'anchored'
    }
}

Setting options dynamically

To change one or more options on the component after initialization, use the setOptions method. This will update the component without losing it's internal state.

$('#elm').mobiscroll().datepicker({
  theme: 'ios'
});
// Changes the theme to Material
$('#elm').mobiscroll('setOptions', { theme: 'material' });

Events

$('#mobiscroll').mobiscroll().datepicker({
    onCancel: function (event, inst) {
    }
});

$('#mobiscroll').mobiscroll().datepicker({
    onCellClick: function (event, inst) {
    }
});

$('#mobiscroll').mobiscroll().datepicker({
    onCellHoverIn: function (event, inst) {
    }
});

$('#mobiscroll').mobiscroll().datepicker({
    onCellHoverOut: function (event, inst) {
    }
});

$('#mobiscroll').mobiscroll().datepicker({
    onChange: function (event, inst) {
    }
});

$('#mobiscroll').mobiscroll().datepicker({
    onClose: function (event, inst) {
    }
});

$('#mobiscroll').mobiscroll().datepicker({
    onDestroy: function (event, inst) {
    }
});

$('#mobiscroll').mobiscroll().datepicker({
    onInit: function (event, inst) {
    }
});

$('#mobiscroll').mobiscroll().datepicker({
    onLabelClick: function (event, inst) {
    }
});

$('#mobiscroll').mobiscroll().datepicker({
    onOpen: function (event, inst) {
    }
});

$('#mobiscroll').mobiscroll().datepicker({
    onPageChange: function (event, inst) {
    }
});

$('#mobiscroll').mobiscroll().datepicker({
    onPageLoaded: function (event, inst) {
    }
});

$('#mobiscroll').mobiscroll().datepicker({
    onPageLoading: function (event, inst) {
    }
});

$('#mobiscroll').mobiscroll().datepicker({
    onPosition: function (event, inst) {
    }
});

Methods

// With selector
$('#mobiscroll').mobiscroll('close');

// With instance
mobiscrollInstance.close();

// With selector
$('#mobiscroll').mobiscroll('destroy');

// With instance
mobiscrollInstance.destroy();

// With selector
$('#mobiscroll').mobiscroll('getInst');

// With instance
mobiscrollInstance.getInst();

// With selector
$('#mobiscroll').mobiscroll('isVisible');

// With instance
mobiscrollInstance.isVisible();

// With selector
$('#mobiscroll').mobiscroll('navigate', new Date(2016, 1, 1));

// With instance
mobiscrollInstance.navigate(new Date(2016, 1, 1));

// With selector
$('#mobiscroll').mobiscroll('open');

// With instance
mobiscrollInstance.open();

// With selector
$('#mobiscroll').mobiscroll('position');

// With instance
mobiscrollInstance.position();

// With selector
$('#mobiscroll').mobiscroll('setActiveDate', 'start');

// With instance
mobiscrollInstance.setActiveDate('start');

// With selector
$('#mobiscroll').mobiscroll('setOptions', {
    display: 'bottom'
});

// With instancee
mobiscrollInstance.setOptions({
    display: 'bottom'
});

Localization

dateWheels: '|D M d|' // Will produce 'Sun Sep 9'
            

$('#myexample').mobiscroll().datepicker({
  locale: mobiscroll.localeDe
});

$('#myexample').mobiscroll().datepicker({
  locale: mobiscroll.locale['de']
});

timeWheels: '|h:mm A|' // Will produce '9:12 AM' 

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:

• Create custom themes using the theme builder - the custom themes can be also built using out theme builder, on a graphical user interface, without any coding, or the need for Sass support in your project.
• Create custom themes using Sass - use this, if you need multiple themes with different color variatons, in case you have pages with different colors, or you'd like to users to customize the colors of your app.
• Override the Sass color variables - the straightforward way to change the colors in one place throughout the application.

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"

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.