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. You can create compact calendar with class compact.


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

Also you can use wide calendar. To create wide calendar, use attributes data-wide="true" - persistent or data-wide-point="..." where point is one of the Metro UI media point (fs, sm, md, lg, xl, xxl).


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

Week start

Metro UI 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 UI 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.

Input dates format

New in 4.2.20

You can define your input format for dates with attribute data-input-format. To define date parts use next identifiers:

day dd, %d
month mm, %m
year yyyy, yy, %Y
hours hh, %h
minutes ii, %i
seconds ss, %s

Example: if you input date is 21/12/1972, you must define format as %d/%m/%Y or dd/mm/yyyy for valid convert string value to date.

If your input date format different from ECMAScript date format, you must define input format for these dates with attribute data-input-format="...".

Exclude dates

You can exclude any dates from user selection. To exclude dates add data-exclude="..." attribute and specify comma separated dates who can be excluded.


                    <div
                         data-role="calendar"
                         data-input-format="dd-mm-yyyy"
                         data-show="15-10-2017"
                         data-exclude="
                            10-10-2017,
                            11-10-2017,
                            12-10-2017,
                            13-10-2017,
                            14-10-2017,
                            15-10-2017
                         "
                    ></div>
                

Preset dates

You can preselect dates. To preselect dates use data-preset="..." attribute and specify dates who can be preselect.


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

Special dates

You can set a special dates. If you set a special dates, others dates marked as disabled. To set special dates use data-special="..." attribute and specify dates who can be sets.


                    <div
                        data-role="calendar"
                        data-show="2017/10/15"
                        data-special="
                            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.


                    <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 calendar to specific date. To switch calendar use attribute data-show="...".


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

Multi select

You can enable multi select feature with attribute data-multi-select and data-week-day-click.


                    <div id="calendar_multiselect" class="mx-auto"
                         data-role="calendar"
                         data-week-day-click="true"
                         data-multi-select="true"
                    ></div>
                

Internationalisation

You can use attribute data-locale="..." to setup language for calendar. The default locale is en-US. More about Metro UI 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
showHeader data-show-header true If true, header is visible
showFooter data-show-footer true If true, footer is visible

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 = Metro.getPlugin(element, '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>