Datepicker
Basic usage
The following example will create a datepicker with the default options.
$(function () {
$("#date").mobiscroll().datepicker();
});
<input id="date"/>
For many more examples - simple and complex use-cases - check out the date picker demos for jquery.
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:
-
repeat
String - The frequency of the recurrence. String equivalent:FREQ
.-
'daily'
- Daily repeat -
'weekly'
- Weekly repeat -
'monthly'
- Monthly repeat -
'yearly'
- Yearly repeat
-
-
day
Number - 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. -
month
Number - Specify the month in case of yearly repeat. String equivalent:BYMONTH
.Specifying multiple months for the rule is currently not supported. -
weekDays
String - Comma separated list of the week days ('SU', 'MO', 'TU', 'WE', 'TH', 'FR', 'SA') for the occurrences. String equivalent:BYDAY
. -
count
Number - The number of occurrences. String equivalent:COUNT
. -
from
Date, String, Object - The start date of the occurrences. String equivalent:DTSTART
. -
until
:Date, String, Object - The end date of the occurrences. String equivalent:UNTIL
. -
interval
Number - The time interval for the rule, e.g. every 3 days, or every 2 weeks. This depends on therepeat
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:
Type | Description |
---|---|
Datepicker | Type of the Datepicker instance |
MbscDatepickerOptions | Type of the settings object that is used to initialize the component |
Options
Name | Type | Default value | Description |
---|---|---|---|
anchor | 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.
|
animation | String, Boolean | undefined |
Animation to use for opening/closing of the control (if display is not inline). Possible values:
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.
If there are more than one wheels shown, the control will close on overlay tap. Otherwise tapping a value on the wheel will also close the control.
If a string, it must be one of the predefined buttons:
If an object, it may have the following properties:
Predefined and custom buttons example
Predefined button handler example
|
calendarScroll | String | 'horizontal' |
Controls the direction the calendar can be navigated. You can navigate by scrolling, swiping or by clicking the arrow buttons in the header.
When navigation is |
calendarSystem | Object | undefined |
Specify the calendar system to be used.
|
calendarType | String | 'month' |
Sets the calendar type. Possible values: In case of In case of |
circular | Boolean, 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.
|
closeOnEsc | Boolean | true |
If true, the popup is closed on ESC keypress. |
closeOnOverlayClick | Boolean | true |
If true, the popup is closed on overlay tap/click. |
colors | Array | undefined |
Change the color of certain dates on the calendar. Must be an array of objects with the following properties:
The dates can be specified as Javascript Date objects, ISO 8601 strings, or moment objects.
Example
|
context | String, HTMLElement | 'body' |
The DOM element in which the component 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:
|
cssClass | String | undefined |
Applies custom css class to the top level element. |
defaultSelection | Date, String, moment, Array, null | undefined |
Default selection which appears on the picker. The provided value will not be set as picker value, it's only a pre-selection. If not provided, the default selection will be the current date and/or time.
If |
disabled | Boolean | false |
Initial disabled state of the component. This will take no effect in inline display mode. |
display | String | undefined |
Controls the positioning of the component. Possible options:
The default display mode depends on the theme,
it defaults to
In desktop mode (when the touchUi option is set to |
endInput | String or HTMLElement | undefined |
Sets the Input for the end date. When using the datepicker to select a range, it can be used with one, two or no inputs. When an endInput is passed to the datepicker, it will put the range end part of the selection to that input. Similarly the input for the begin part can be specified by the startInput option. |
focusOnClose | Boolean, String, HTMLElement |
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 | Boolean, String | 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 datepicker.If it's set to false , the header is hidden. |
height | Number, String | undefined |
Sets the height of the component. |
inputStyle | String | 'underline' |
Defines the input rendering mode. By default the input has the underline styling. Possible values:
|
invalid | Array | undefined |
An array containing the invalid values.
Can contain dates (Javascript Date objects, ISO 8601 strings, or moment objects), or objects with the following properties:
Example
|
itemHeight | Number | 40 |
Height in pixels of one item on the wheel.
The default value depends on the theme: iOS: 34 Material: 40 Windows: 44 |
labels | Array | undefined |
Specify labels for calendar days. A label object can have the following properties:
The dates can be specified as Javascript Date objects, ISO 8601 strings, or moment objects.
Example
|
labelStyle | String | undefined |
Defines the position of the label. The default label style depends on the theme option.
With the 'ios' theme the inputs have inline labels, with 'mobiscroll', 'material' and 'windows' themes
the default label position is stacked . Possible values:
|
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:
The dates can be specified as Javascript Date objects, ISO 8601 strings, or moment objects.
Example
|
max | Date, String, Object | undefined |
Maximum value that can be selected. |
maxRange | Integer | undefined |
Maximum range that can be selected specified in milliseconds. |
maxWheelWidth | Number, Array | undefined |
Maximum width of the scroller wheels in pixels. If number, it is applied to all wheels, if an array, it is applied to each wheel separately. |
min | Date, String, Object | undefined |
Minimum value that can be selected. |
minRange | Integer | undefined |
Minimum range that can be selected specified in milliseconds. |
minWheelWidth | Number, Array | 80 |
Minimum width of the scroller 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: iOS: 55 Material: 80 Windows Phone: 88 |
moment | object | undefined |
Reference to the Moment.js library. When using Moment objects as return values, this setting should be passed the reference to the Moment.js library. Check out our example on how to pass moment to the datepicker ! |
pages | Number, String | 1 |
Number of calendar pages (month or week) to display. If 'auto' , the displayed number of pages will be decided based on the viewport size. |
renderCalendarHeader | Function | undefined |
Use this option to customize the header of the Datepicker. 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
|
responsive | Object | undefined |
Specify different settings for different container 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.
The available width is queried from the container element of the component and not the browsers viewport like in css media queries
There are five predefined breakpoints:
breakpoint
property specifying the min-width in pixels.
Example:
|
returnFormat | String | 'jsdate' |
Specifies the format in which the selected date(s) should be returned by the getVal method
Possible values:
When using Moment.js, the reference to the moment library must be passed to the component
via the moment option. Check out our example on how to pass moment to the datepicker !
|
rows | Number | 3 |
Number of visible rows on the wheel.
The default value depends on the theme: iOS: 5 Material: 3 Windows: 6 |
scrollLock | Boolean | true |
Disables page scrolling on touchmove (if not in inline mode, and popup height is less than window height). |
selectCounter | Boolean | false |
If true and multiple selection is enabled, the number of selected items will be displayed in the header. |
selectMax | Number | undefined |
The maximum number of selected items in case of multiple selection. |
selectMultiple | Boolean | false |
If true , multiple selection will be enabled. |
separator | String | ' ' |
Sepearator between date and time (if the 'time' controls is also visible) |
showArrow | Boolean | true |
Show or hide the popup arrow, when display mode is 'anchored' .
|
showInput | Boolean | true |
Display an input field which is populated with the selected value of the datepicker. |
showOnClick | Boolean | true |
Opens the component on element click/tap. |
showOnFocus | Boolean |
false - on desktop
true - on mobile
|
Pops up the component on element focus. |
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.
Outer days are automatically hidden if calendarScroll is set to |
showOverlay | Boolean | true |
Show or hide overlay. |
showWeekNumbers | Boolean | false |
Show week numbers on the calendar view. Enumeration starts with the first week of the year. |
startInput | String or HTMLElement | undefined |
Sets the Input for the start date. When using the datepicker to select a range, it can be used with one, two or no inputs. When a startInput is passed to the datepicker, it will put the range beginning part of the selection to that input. Similarly the input for the end part can be specified by the endInput option. |
stepHour | Number | 1 |
Step for the hours scroll wheel. |
stepMinute | Number | 1 |
Step for the minutes scroll wheel. |
stepSecond | Number | 1 |
Step for the seconds scroll wheel. |
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
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:
To use the option with custom themes, make sure to create two custom themes,
where the dark version has the same name as the light one, suffixed with |
touchUi | Boolean | true |
Use Can be used with the responsive option to change the user interface based on viewport width. |
weeks | Number |
1
|
Number of weeks to display if calendarType is set to 'week' .
|
wheelWidth | Number, Array | undefined |
Width of the scroller 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. |
width | Number, String | undefined |
Sets the width of the popup container. This will take no effect in inline display mode. |
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
Name | Description | |
---|---|---|
onCancel(event, inst) |
Allows you to define your own event when cancel is pressed.
Parameters
Example
|
|
onCellClick(event, inst) |
Triggered when a cell is clicked on the calendar
.
Parameters
Example
|
|
onCellHoverIn(event, inst) |
Triggered when the mouse pointer hovers a day on the calendar.
Parameters
Example
|
|
onCellHoverOut(event, inst) |
Triggered when the mouse pointer leaves a day on the calendar.
Parameters
Example
|
|
onChange(event, inst) |
Triggered when the value is changed.
Parameters
Example
|
|
onClose(event, inst) |
Triggered when the component is closed.
Parameters
Example
|
|
onDestroy(event, inst) |
Triggered when the component is destroyed.
Parameters
Example
|
|
onInit(event, inst) |
Triggered when the component is initialized.
Parameters
Example
|
|
onLabelClick(event, inst) |
Triggered when a label on the calendar is clicked.
Parameters
Example
|
|
onOpen(event, inst) |
Triggered when the component is opened.
Parameters
Example
|
|
onPageChange(event, inst) |
Triggered when the calendar page is changed (month or week, with buttons or swipe).
Parameters
Example
|
|
onPageLoaded(event, inst) |
Triggered when the calendar page is changed (month or week, with buttons or swipe) and the animation has finished.
Parameters
Example
|
|
onPageLoading(event, inst) |
Triggered before the markup of a calendar page (month or week) is starting to render.
Parameters
Example
|
|
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
Example
|
Methods
Name | Description | |
---|---|---|
close() |
Closes the component.
ExampleMethods can be called on an instance. For more details see calling methods
|
|
destroy() |
Destroys the component. This will return the element back to its pre-init state.
Returns: Object
ExampleMethods can be called on an instance. For more details see calling methods
|
|
getInst() |
Returns the object instance.
Returns: Object
ExampleMethods can be called on an instance. For more details see calling methods
|
|
getVal() |
Returns the selected value of the picker, that has been set to the input as well.
Depending on how the picker is displayed, the selection might be in a temporary state that hasn't been set yet.
This temporary value can be aquired calling the Returns: String, Date, Moment.js Object or Array of String, Date or Moment.js ObjectThe return value type depends on the returnFormat and the select option. |
|
isVisible() |
Returns a boolean indicating whether the component is visible or not.
Returns: Boolean
ExampleMethods can be called on an instance. For more details see calling methods
|
|
navigate(date) |
Display a specific month on the calendar without setting the date.
Parameters
ExampleMethods can be called on an instance. For more details see calling methods
|
|
open() |
Opens the component.
ExampleMethods can be called on an instance. For more details see calling methods
|
|
position() |
Recalculates the position of the component (if not inline).
ExampleMethods can be called on an instance. For more details see calling methods
|
|
setActiveDate(active) | Sets which date is currently selected (start or end). If the picker is visible, it will also highlight the respective date.
Parameters
ExampleMethods can be called on an instance. For more details see calling methods
|
|
setOptions(options) |
Update options for the component.
Parameters
ExampleMethods can be called on an instance. For more details see calling methods
|
|
setVal(value) |
Sets the picker value and also writes it to the input.
Depending on how the picker is displayed, the selection shown might be just a temporary value until the users hit the "Set" button to commit the selection.
This temporary value can be adjusted calling the
To get the current selected value, check out the Parameters
The value type should be choosen depending on the returnFormat and the select option. |
Localization
Name | Type | Default value | Description |
---|---|---|---|
amText | String | 'am' |
Text for AM. |
cancelText | String | 'Cancel' |
Text for Cancel button. |
dateFormat | String |
'MM/DD/YYYY'
|
The format for parsed and displayed dates.
|
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:
|
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. |
firstDay | Number | 0 |
Set the first day of the week: Sunday is 0, Monday is 1, etc. |
headerText | Boolean, String | '{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 datepicker. If it's set to false , the header is hidden. |
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:
In some cases it's more convenient to set the locale using the language code string.
You can do that by using the
The
locale object is not tree-shakeable, meaning that all translations present in the object
will end up in the application bundle, whether it's being used or not.
|
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. |
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. |
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:mm A'
|
The format for parsed and displayed dates
|
timeWheels | String |
undefined
|
Display order and formating of the time wheels on the datepicker.
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:
|
yearSuffix | String | undefined |
Additional string to display after the year on the wheel. |
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:
- Theme specific variables (ex.
$mbsc-material-background
,$mbsc-ios-dark-text
) are applied to all components in a theme. Complete list of variables here. - Component specific global variables (ex.
$mbsc-card-background-light
,$mbsc-listview-text-dark
) are applied to all themes for a specific component. - 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.