Calendar

Calendar is a component for a user to select a specific date, list of dates or a range of dates.

Create calendar

The calendar component is designed to organize the user's choice of a date or a list of dates. To create calendar add data-role="calendar" attribute to element.


                    <div data-role="calendar"></div>

Also you can use wide calendar. To create wide calendar add class .calendar-wide to element or use media variants: .calendar-wide-md, .calendar-wide-lg, .calendar-wide-xl, .calendar-wide-xxl.


                    <div class="calendar-wide-sm" data-role="calendar"></div>

Week start

Metro 4 calendar support two modes for week start:

from sunday (default)
from monday

To set week start use data-week-start attribute. When value is 0 (default), calendar started from sunday, when value is 1, calendar started from monday.


                    <div data-role="calendar" data-week-start="0"></div>
                    <div data-role="calendar" data-week-start="1"></div>

Selection

You can use two variants of date selecting: one date mode (default) or multi dates mode. To set selection mode use attribute data-multi-select with values true or false.

If you set data-multi-select="true", you also select column of dates by click on week day.


                    <div data-role="calendar" data-multi-select="true"></div>
                    <div data-role="calendar" data-multi-select="false"></div>

Picker mode

You can set calendar to picker mode with attribute data-picker-mode="true". In this mode user can select only one date and selected date marked as today.


                    <div data-role="calendar" data-picker-mode="true"></div>

Buttons

Metro 4 calendar contains predefined four buttons to behavior with component: cancel, today, clear and done.

To define buttons use data-buttons attribute with string value with enumeration of buttons. By default a all buttons are present. If this attribute value is a false, all buttons will be hide.


                    <div data-role="calendar" data-buttons="today, clear"></div>
                    <div data-role="calendar" data-buttons="false"></div>

For all buttons defined callbacks:

Button	Event	Data-*
cancel	onCancel(el)	data-on-cancel
today	onToday(today, el)	data-on-today
clear	onClear(el)	data-on-clear
done	onDone(selection, el)	data-on-done

Buttons today and clear has specific predefined functions. Button today - set today for calendar. Button clear - clear selection for calendar. Callbacks for this buttons executed after predefined functions.

Exclude dates

You can exclude any dates from user selection. To exclude dates add data-exclude="..." attribute and specify dates who can be excluded. Values for this attributes can be valid string date: YYYY-MM-DDTHH:mm:ss.sssZ.


                    <div
                        data-role="calendar"
                        data-exclude="
                            2017/10/10,
                            2017/10/11,
                            2017/10/12,
                            2017/10/13,
                            2017/10/14,
                            2017/10/15,
                            2017/10/16"
                    ></div>

Preset dates

You can preselect dates. To preselect dates use data-preset="..." attribute and specify dates who can be preselect. Values for this attributes can be valid string date: YYYY-MM-DDTHH:mm:ss.sssZ.


                    <div
                        data-role="calendar"
                        data-show="2017/10/15"
                        data-preset="
                            2017/10/10,
                            2017/10/11,
                            2017/10/12,
                            2017/10/13,
                            2017/10/14,
                            2017/10/15,
                            2017/10/16"
                    ></div>

Min & max dates

You can limit the set of dates for user selection. To set limit use data-min-date="..." and data-max-date="..." attributes. Values for this attributes can be valid string date: YYYY-MM-DDTHH:mm:ss.sssZ.


                    <div
                         data-role="calendar"
                         data-show="2017/10/15"
                         data-min-date="2017/10/08"
                         data-max-date="2017/10/25"
                    ></div>

Show specific date

You can switch calndar to specific date. To switch calendar use attribute data-show="...". Values for this attribute can be valid string date: YYYY-MM-DDTHH:mm:ss.sssZ.


                    <div
                         data-role="calendar"
                         data-show="1972/12/21"
                    ></div>

Select month, year

You can quick change month or year. To change month, click on current month name and select required month from months panel. To change year, click on current year name and select required year from year panel.

Internationalisation

You can use attribute data-locale="..." to setup language for calendar. The default locale is en-US. More about Metro 4 locales you can read in this article.


                    <div data-role="calendar" data-locale="de-DE"></div>
                    <div data-role="calendar" data-locale="uk-UA"></div>

You can change locale in runtime. To change locale, update value for attribute data-locale.


                    <div class="d-flex flex-justify-center mb-4">
                        <button class="button m-1" onclick="$('#cal_locale').attr('data-locale', $(this).text())">en-US</button>
                        <button class="button m-1" onclick="$('#cal_locale').attr('data-locale', $(this).text())">de-DE</button>
                        <button class="button m-1" onclick="$('#cal_locale').attr('data-locale', $(this).text())">hu-HU</button>
                        <button class="button m-1" onclick="$('#cal_locale').attr('data-locale', $(this).text())">uk-UA</button>
                        <button class="button m-1" onclick="$('#cal_locale').attr('data-locale', $(this).text())">ru-RU</button>
                    </div>

                    <div data-role="calendar" data-locale="en-US" class="mx-auto" id="cal_locale"></div>

Options

You can use calendar options to setup it behavior.

Option	Data-*	Default	Desc
yearsBefore	`data-years-before`	100	Years before today
yearsAfter	`data-years-after`	100	Years after today
show	`data-show`	null	Show specific date
pickerMode	`data-picker-mode`	false	Set calendar to picker mode
locale	`data-locale`	METRO_LOCALE (default en-US)	Calendar language
weekStart	`data-week-start`	0	Start month from sunday or monday (0 - sunday, 1 - monday)
outside	`data-outside`	true	Show dates outside from month (prev or next month dates)
buttons	`data-buttons`	cancel, today, clear, done	Buttons can be showing in calendar
ripple	`data-ripple`	false	Add ripple effect to click
rippleColor	`data-ripple-color`	#cccccc	Ripple color
exclude	`data-exclude`	null	Dates can be excluded from selection
preset	`data-preset`	null	Dates can be preselect
minDate	`data-min-date`	null	Min date
maxDate	`data-max-date`	null	Max date
weekDayClick	`data-week-day-click`	false	If true, user can click on week day to select column of days, required multiSelect can be set to true
multiSelect	`data-week-day-click`	false	If true, user can select a few days

Events

When calendar works, it generated the numbers of events. You can use callback for this event to behavior with calendar or eny elements. Rules for working with events are described on this page.

Event	Data-*	Default	Desc
`onCancel(el)`	`data-on-cancel`	Metro.noop	Callback for cancel button
`onToday(today, el)`	`data-on-today`	Metro.noop	Callback for today button
`onClear(el)`	`data-on-clear`	Metro.noop	Callback for clear button
`onDone(sel, el)`	`data-on-done`	Metro.noop	Callback for done button
`onDayClick(sel, day, el)`	`data-on-day-click`	Metro.noop	Callback for day click
`onWeekDayClick(sel, day, el)`	`data-on-week-day-click`	Metro.noop	Callback for week day click
`onMonthChange(curr, el)`	`data-on-month-change`	Metro.noop	Callback for month change event
`onYearChange(curr, el)`	`data-on-year-change`	Metro.noop	Callback for year change event
`onCalendarCreate(el)`	`data-on-calendar-create`	Metro.noop	Callback fired when calendar is created


                    <div data-role="calendar" data-on-day-click="console.log(arguments)"></div>

                    <div data-role="calendar" data-on-day-click="myFunction"></div>

                    <script>
                        function myFunction(sel, day, el){
                            console.log(sel)
                            console.log(day)
                            console.log(el)
                        }
                    </script>

Methods

You can use calendar methods to interact with the calendar.

getPreset()
getSelected()
getExcluded()
getToday()
getCurrent()
setToday(today)
setExclude(exclude)
setPreset(preset)
setShow(show)
setMinDate(date)
setMaxDate(date)


                    var calendar = $(element).data('calendar');

                    console.log(calendar.getPreset());
                    console.log(calendar.getSelected());
                    console.log(calendar.getExcluded());
                    console.log(calendar.getToday());
                    console.log(calendar.getCurrent());

                    calendar.setExcluded("10/10/2017, 10/11/2017");
                    calendar.setPreset("10/14/2017, 10/15/2017, 10/16/2017");
                    calendar.setShow("01/01/2017");
                    calendar.setMinDate("05/01/2017");
                    calendar.setMaxDate("31/01/2017");

Observe

You can change attributes data-exclude, data-preset, data-show, data-min-date, data-max-date at runtime and calendar will be updated.

Customize

You can customize any calendar elements with nex options:

clsToday	`data-cls-today`	Additional class for today
clsSelected	`data-cls-selected`	Additional class for selected
clsExclude	`data-cls-exclude`	Additional class for excluded
clsCancelButton	`data-cls-cancel-button`	Additional class for cancel button
clsTodayButton	`data-cls-today-button`	Additional class for today button
clsClearButton	`data-cls-clear-button`	Additional class for clear button
clsDoneButton	`data-cls-done-button`	Additional class for done button
clsCalendar	`data-cls-calendar`	Additional class calendar
clsCalendarHeader	`data-cls-calendar-header`	Additional class for calendar header
clsCalendarContent	`data-cls-calendar-content`	Additional class for calendar content
clsCalendarFooter	`data-cls-calendar-footer`	Additional class for calendar footer
clsCalendarMonths	`data-cls-calendar-months`	Additional class for calendar months
clsCalendarYears	`data-cls-calendar-years`	Additional class for calendar years


                    <div class="mx-auto"
                         data-role="calendar"
                         data-show="2017/10/15"
                         data-exclude="2017/10/01, 2017/10/02, 2017/10/03"
                         data-preset="2017/10/15, 2017/10/16, 2017/10/17"
                         data-cls-selected="bg-cyan fg-white"
                         data-cls-excluded="bg-dark fg-white"
                         data-cls-today="bg-pink fg-white"
                         data-cls-today-button="success"
                         data-cls-clear-button="alert"
                         data-cls-done-button="primary"
                         data-cls-calendar-header="bg-green"
                         data-cls-calendar-content="bg-orange fg-white"
                         data-cls-calendar-footer="bg-teal"
                    ></div>

Table of contents