The calendar supports single, multiple & range selection with mobile & desktop optimized rendering and interaction model.
Easily switch between dropdown and calendar view or single and range selection. Enhance the calendar with marked days or labels.
The capabilities like built-in validation, minimum, maximum values, disabled dates are supported by both the scroller and calendar.
Use the calendar for both mobile and desktop or set it up responsively.
The main difference between the two rendering modes is how the picker is laid out. Set the touchUi option to false and the component shows up suitable for larger screens and pointer interaction while setting it to true renders it suitable for touch screens.
Use the date picker on an existing form field, custom input or use it on Mobiscroll form fields. You can also embed it directly into your page.
When linked to an input, the component will be shown on focus or when someone clicks on the field. Alternatively, you can leave the input editable and show the component only on a button click.
The date & time has a liquid layout, which means it nicely adapts to its surroundings. There are times however when you would like to set up the component responsively.
Use the responsive option to configure the picker and change the options based on the viewport width. 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
use custom for setting a custom breakpoint
It is a good idea to change the display or controls option to taiilor the UX. This way you can have a bottom positioned calendar on mobile, a popover anchored to the input on tablet and desktop display on large sceens.
Change the viewport
Calendar - Understanding display modes
Understanding display modes
The date picker has five built-in display modes that can be controlled through the display option:
top - modal that slides down from the top
bottom - modal that slides up from the bottom
center - modal that shows up in the middle with a pop animation
anchored - modal that shows up anchored to an input or any dom element
inline - embeddable picker that is rendered into the markup without its own modal
Use the touchUi option to switch between touch optimized mobile renderign and pointer optimized desktop renderign. It can be dynamically switched with the help of the responsive oprion.
The defaults change on a theme to theme basis. The ios theme comes with bottom on mobile and anchored on desktop while the material and windows themes have center on mobile and anchored on desktop.
The date picker ships with four built-in variations for rendering the UI. The controls option supports the following:
date - renders a date-only scroller or dropdown control
time - renders a time-only scroller or dropdown control
datetime - renders a date & time scroller or dropdown
calendar - renders a calendar view for date picking
Use controls: ['datetime'] for rendering a date & time picker within the same control, tied to the same input, or use them separately for two inputs - controls: ['date'] and controls: ['time']. It will render a scrollers for touchUi: true and a dropdowns for touchUi: false.
Show a week calendar instead of a monthly calendar view to save space. By setting the calendarType to 'week' and passing the count in the weeks option you can simply enable a week view.
You can dynamically change the number of weeks or switch between month and week view without the need for recycling the whole component.
Calendar - Multi month view
Multi month view
Showing multiple months helps when people need to be looking at longer stretches of times. When the calendarType is set to 'month' the month count can be set through the pages option.
By setting pages: 1, pages: 2, the calendar will render the exact number of months regardless of the width of the parent container. Passing pages: 'auto' renders as many months as can be fitted in the parent container.
You can dynamically change the number of months or switch between month and week view without the need for recycling the whole component.
You can highlight days, mark them with colored dots, add labels or completely color the background of the days using the marked, colors and labels options.
This offers means to add more information to the calendar that could be valuable to users. While you can use the colors along with marked and labels, the latter two are mutually exclusive because they get rendered in the same place on the UI.
The selectMin and selectMax options control how many values have to be and can be selected. Setting both works as a fixed selection count, which means the control can only be sumbitted if that count is met.
To customize the header you can pass a headerText or turn selectCounter on to display a localized text with the number of dates selected.
Dynamically switching between single, multiple or range select can be done with option changes.
Calendar - Range selection
To enable range selection set the select option to range.
The microcopy for rangeStartLabel and rangeEndLabel can be easily overriden. For flight booking "Outbound" and "Return" makes sense while for accomodation booking "Check in" and "Check out" might be more appropriate.
The range start/end labels can also be hidden in some cases if needed. Use the showRangeLabels option for that.
Furthermore, you have the option to toggle the range highlight with the rangeHighlight option, if needed.
The date & time picker works with different date types:
JS date object - a common way of passing a date is through a Date object: new Date(1995, 11, 17, 15, 24) (make sure to not simply pass a date string to new Date())
ISO date string - standardized way of passing dates: '2008-09-15T15:53:00' (make sure to pass it as a string)
Moment.js object - a great solution that solves common date management difficulties: moment([2018, 3, 27, 12, 15]) (make sure to have moment.js loaded)
When passing dates to the component - eg. min/max, invalids - you can do it in either format and the picker will automatically know what to do with it. If you want to specify how the picker should return values, you can do it in the returnFormat option.
Calendar - Formatting values
Use the dateFomat, timeFormat options to customize how the values show up in the inputs after selection. If the formats are not expicitly set, they are inherited from the localization settings.
Besides customizing the date and time formats you can reorder the time picker wheels and change its formats with the timeWheels options.
Configuring minimum and maximum selectable values is great for reducing mistakes. Help people by limiting the selections for the task at hand. Use the min and max options to restrict the selection.
Setting the values will disable dates/times earlier than min and dates/times that come after max.
Enforcing validation is essential to a great UX. First make sure to have the min & max values right and then work your way through disabled values.
Dates can be disabled through the invalid option.
Another tool for setting disabled values are valid overrides. This means that you can make certain values valid from the invalid set. Eg. Invalidate all Tuesdays, but make Aug. 04, 2020 valid.
The look and feel of the date picker can be deeply customized. There are four levels of customization:
Base themes: Choose between iOS, Material and Windows.
Light or dark: Every theme has a light and dark variant. Setting the themeVariant to 'auto' will switch based on system settings.
Custom themes: Use the theme builder to customize the colors and make it match your brand.
Custom CSS: If you need further customization, the sky is the limit with CSS overrides.
You can also see how every example looks by changing the theme from the header.
Calendar - Customizing the header
Customizing the header
You can customize how the header of calendar looks and how the components are arranged. Besides that you can also add custom functionality, like a segmented control that lets people switch between week and month view.
Use the renderHeader option for passing a custom header layout. There are predefined components - shorthands if you will - that can be used to assemble the header:
But sometimes that is not enough. Luckily you can use the cellCssClass property of the colors option to pass a CSS class that will be added to the day cell and apply any custom styling you write in CSS. These days can be recurring days, ranges or individual days.
You can use the cellCssClass in combination with custom cell background to highlight a range of days and show the ends as check-in and check-out days.
Calendar - Lifecycle events
The date picker ships with different event hooks for deep customization. Events are triggered through the lifecycle of the component where you can tie in custom functionality and code.
While users interact with the UI events like onChange, onSet, onInit ... will be triggered.