Calendar / Datepicker

    Calendar is a touch optimized component that provides an easy way to handle dates.

    Calendar could be used as inline component or as overlay. Overlay Calendar will be automatically converted to Popover on tablets (iPad).

    Calendar App Methods

    Let's look at related App methods to work with Calendar:

    app.calendar.create(parameters)- create Calendar instance

    • parameters - object. Object with calendar parameters

    Method returns created Calendar's instance

    app.calendar.destroy(el)- destroy Calendar instance

    • el - HTMLElement or string (with CSS Selector) or object. Calendar element or Calendar instance to destroy.

    app.calendar.get(el)- get Calendar instance by HTML element

    • el - HTMLElement or string (with CSS Selector). Calendar element.

    Method returns Calendar's instance

    app.calendar.close(el)- close Calendar

    • el - HTMLElement or string (with CSS Selector). Calendar element to close.

    Method returns Calendar's instance

    For example:

    var calendar = app.calendar.create({
        inputEl: '#calendar-input'
    });

    Calendar Parameters

    Let's look on list of all available Calendar parameters:

    Parameter Type Default Description
    calendarType string gregorian Calendar type, can be gregorian or jalali
    value array Array with initial selected dates. Each array item represents selected date
    disabled Date Range Additonal disabled dates. Parameter accepts so called Date Range (look below for details)
    events Date Range

    Dates with events. Will be marked with additonal "dot" on calendar day. Parameter accepts so called Date Range (look below for details).

    If you want to indicate that day has few different events, it is possible to indicate this with multiple different color dots. In this case, you need to pass date range as array where each object will have date and color properties, e.g.

    [
      {
        date: new Date(2018, 4, 11),
        color: '#2196f3',
      },
      // same date but different color, one more dot will be added to this day
      {
        date: new Date(2018, 4, 11),
        color: '#4caf50',
      },
    ]
    rangesClasses array Date ranges you want to add custom CSS class for additional styling. Look below for accepted format
    formatValue function (values) Function to format input value, should return new/formatted string value. values is array where each item represents selected date
    monthNames array
    ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August' , 'September' , 'October', 'November', 'December']
    Array with full month names
    monthNamesShort array
    ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
    Array with short month names
    dayNames array
    ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday']
    Array with week day names
    dayNamesShort array
    ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat']
    Array with week day short names
    firstDay number 1 First day of the week. By default 1 - Monday
    weekendDays array [0, 6] Array with index numeber of weekend days, by default it is Saturday and Sunday
    jalali object
    {
      monthNames: ['فروردین', 'اردیبهشت', 'خرداد', 'تیر', 'مرداد', 'شهریور', 'مهر', 'آبان', 'آذر', 'دی', 'بهمن', 'اسفند'],
      monthNamesShort: ['فَر', 'اُر', 'خُر', 'تیر', 'مُر', 'شَه', 'مهر', 'آب', 'آذر', 'دی', 'بَه', 'اِس'],
      dayNames: ['یک‌شنبه', 'دوشنبه', 'سه‌شنبه', 'چهارشنبه', 'پنج‌شنبه', 'جمعه', 'شنبه'],
      dayNamesShort: ['1ش', '۲ش', '۳ش', '۴ش', '۵ش', 'ج', 'ش'],
      firstDay: 6, // Saturday
      weekendDays: [5], // Friday
      ['فروردین', 'اردیبهشت', 'خرداد', 'تیر', 'مرداد', 'شهریور', 'مهر', 'آبان', 'آذر', 'دی', 'بهمن', 'اسفند']
    }
    Object with configuration for Jalali type calendar
    dateFormat string 'yyyy-mm-dd' Default date format, available expressions:
    • 'yyyy' - 4 digits year
    • 'yy' - 2 digits year
    • 'mm' - 2 digits month number, from 01 to 12
    • 'm' - month number, from 1 to 12
    • 'MM' - full month name
    • 'M' - short month name
    • 'dd' - 2 digits day number, from 01 to 31
    • 'd' - day number, from 1 to 31
    • 'DD' - full week day name
    • 'D' - short week day name
    multiple boolean false Enable to allows select multiple dates/values
    rangePicker boolean false Enable to enable range picker. Not compatible with multiple
    rangePickerMinDays number 1 Minimum days that need to be selected when rangePicker enabled
    rangePickerMaxDays number 0 Maximum days allowed to be selected when rangePicker enabled. 0 means no maximum
    direction string 'horizontal' Months layout direction, could be 'horizontal' or 'vertical'
    minDate Date null Minimum allowed date
    maxDate Date null Maximum allowed date
    touchMove boolean true If enabled then calendar months slides follow finger during touch move
    animate boolean true Enables transition between months
    closeOnSelect boolean false Enable and calendar will be closed when user pick a date
    weekHeader boolean true Enable week header with short name week days
    monthSelector boolean true Enable month selector in toolbar
    yearSelector boolean true Enable year picker in toolbar
    Container/opener-specific parameters
    containerEl string
    HTMLElement
    String with CSS selector or HTMLElement where to place generated Calendar HTML. Use only for inline calendar
    openIn string auto Can be auto, popover (to open calendar in popover), sheet (to open in sheet modal) or customModal (to open in custom Calendar modal overlay). In case of auto will open in sheet modal on small screens and in popover on large screens.
    inputEl string or HTMLElement String with CSS selector or HTMLElement with related input element
    scrollToInput boolean true Scroll viewport (page-content) to input when calendar opened
    inputReadOnly boolean true Sets "readonly" attribute on specified input
    cssClass string Additional CSS class name to be set on calendar element
    closeByOutsideClick boolean true If enabled, picker will be closed by clicking outside of picker or related input element
    toolbar boolean true Enables calendar toolbar
    toolbarCloseText string Done Text for Done/Close toolbar button
    header boolean false Enables calendar header
    headerPlaceholder string Select date Default calendar header placeholder text
    routableModals boolean true Will add opened calendar to router history which gives ability to close calendar by going back in router history and set current route to the calendar modal
    url string date/ Calendar modal URL that will be set as a current route
    view object View where to set routing when routableModals enabled. Defaults to parent view of inputEl or main view if not found parent view
    backdrop boolean Enables Calendar backdrop (dark semi transparent layer behind). By default only it is enabled when Calendar opened in Popover.
    closeByBackdropClick boolean true When enabled, Calendar will be closed on backdrop click
    Render Functions
    renderWeekHeader function Function to render week header. Must return week header HTML string
    renderMonths function(date) Function to render months wrapper. Must return months container full HTML string
    renderMonth function(date, offset) Function to render single month. Must return single month HTML string
    renderMonthSelector function Function to render month selector. Must return month selector HTML string
    renderYearSelector function Function to render year selector. Must return year selector HTML string
    renderHeader function Function to render calendar header. Must return calendar header HTML string
    renderToolbar function Function to render toolbar. Must return toolbar HTML string
    render function Function to render whole calendar. Must return calendar full HTML string
    Events
    on object Object with events handlers. For example:
    var calendar = app.calendar.create({
      ...
      on: {
        opened: function () {
          console.log('Calendar opened')
        }
      }
    })

    Note that all following parameters can be used in global app parameters under calendar property to set defaults for all calendars. For example:

    var app = new Framework7({
      calendar: {
        url: 'calendar/',
        dateFormat: 'dd.mm.yyyy',
      }
    });

    Date Range

    Some of Calendar parameters (disabled, events and rangesClasses) accept so called Date Range. It is a simple way to specify and cover all possible dates combination.

    It can be array with dates, for example:

    var calendar = app.calendar.create({
        ...
        // Disabled 10th November 2015 and 11th November 2015:
        disabled: [new Date(2015, 10, 10), new Date(2015, 10, 11)],
        ...
    });

    It can be custom function where you need to return true or false

    var calendar = app.calendar.create({
        ...
        //Disabled all dates in November 2015
        disabled: function (date) {
            if (date.getFullYear() === 2015 && date.getMonth() === 10) {
                return true;
            }
            else {
                return false;
            }
        },
        ...
    });

    Or object with from and to properties

    var calendar = app.calendar.create({
        ...
        //Disable all dates between 1st October 2015 and 31 December 2015
        disabled: {
            from: new Date(2015, 9, 1),
            to: new Date(2015, 11, 31)
        },
        ...
    });

    Or object with just from or to properties

    var calendar = app.calendar.create({
        ...
        //Disable everyting since December 2015
        disabled: {
            from: new Date(2015, 11, 1)
        },
        ...
    });

    Or object with date property:

    var calendar = app.calendar.create({
        ...
        // Disabled 1th December 2015
        disabled: {
            date: new Date(2015, 11, 1)
        },
        ...
    });

    Or array with mixed dates and objects:

    var calendar = app.calendar.create({
        ...
        events: [
            new Date(2015, 9, 1),
            new Date(2015, 9, 5),
            {
                from: new Date(2015, 9, 10),
                to: new Date(2015, 9, 15)
            },
            {
                from: new Date(2015, 9, 20),
                to: new Date(2015, 9, 31)
            },
            {
                date: new Date(2015, 11, 1),
                color: '#ff0000'
            },
            // same date but one more color dot will be added
            {
                date: new Date(2015, 11, 1),
                color: '#00ff00'
            },
        ],
        ...
    });

    rangesClasses

    rangesClasses parameter accepts array of objects with Date Range and class names for this range:

    var calendar = app.calendar.create({
        ...
        //Add classes for november and october
        rangesClasses: [
            //Add "day-october' class for all october dates
            {
                // string CSS class name for this range in "cssClass" property
                cssClass: 'day-october', //string CSS class
                // Date Range in "range" property
                range: function (date) {
                    return date.getMonth() === 9
                }
            },
            //Add "day-holiday" class for 1-10th January 2015
            {
                cssClass: 'day-holiday',
                range: {
                    from: new Date(2016, 0, 1),
                    to: new Date(2016, 0, 10)
                }
            }
        ],
        ...
    });

    Calendar Methods & Properties

    After we initialize Calendar we have its initialized instance in variable (like calendar variable in examples above) with helpful methods and properties:

    Properties
    calendar.app Link to global app instance
    calendar.containerEl Calendar wrapping container HTML element (when inline calendar is in use)
    calendar.$containerEl Dom7 instance with calendar wrapping container HTML element (when inline calendar is in use)
    calendar.el Calendar HTML element
    calendar.$el Dom7 instance with calendar HTML element
    calendar.inputEl Calendar input HTML element (passed in inputEl parameter)
    calendar.$inputEl Dom7 instance with calendar input HTML element (passed in inputEl parameter)
    calendar.value Array where each item represents selected date
    calendar.opened true if Calendar is currently opened
    calendar.inline true when inline calendar is in use
    calendar.cols Array with specified Calendar columns. Each column also has its own methods and properties (look below)
    calendar.url Calendar URL (that was passed in url parameter)
    calendar.view Calendar View (that was passed in view parameter) or found parent view
    calendar.params Object with initialization parameters
    Methods
    calendar.setValue(values) Set new selected dates. values is array where each item represents selected date
    calendar.getValue() Returns current calendar value
    calendar.addValue() Adds value to the values array. Useful in case if multiple selection is enabled (with multiple: true parameter)
    calendar.update() Rerenders calendar. Useful in case you added/changed values dynamically and need to update calendar layout
    calendar.nextMonth(duration) Calendar transition to next month for specified duration in ms
    calendar.prevMonth(duration) Calendar transition to previous month for specified duration in ms
    calendar.nextYear() Calendar transition to next year
    calendar.prevYear() Calendar transition to previous year
    calendar.setYearMonth(year, month, duration) Calendar transition to specified year, month for specified duration in ms
    calendar.open() Open Calendar
    calendar.close() Close Calendar
    calendar.destroy() Destroy Calendar instance and remove all events
    calendar.on(event, handler) Add event handler
    calendar.once(event, handler) Add event handler that will be removed after it was fired
    calendar.off(event, handler) Remove event handler
    calendar.off(event) Remove all handlers for specified event
    calendar.emit(event, ...args) Fire event on instance

    Calendar Events

    Calendar will fire the following DOM events on calendar element and events on app and calendar instance:

    DOM Events

    Event Target Description
    calendar:open Calendar Element<div class="calendar"> Event will be triggered when Calendar starts its opening animation
    calendar:opened Calendar Element<div class="calendar"> Event will be triggered after Calendar completes its opening animation
    calendar:close Calendar Element<div class="calendar"> Event will be triggered when Calendar starts its closing animation
    calendar:closed Calendar Element<div class="calendar"> Event will be triggered after Calendar completes its closing animation

    App and Calendar Instance Events

    Calendar instance emits events on both self instance and app instance. App instance events has same names prefixed with calendar.

    Event Target Arguments Description
    dayClick calendar (calendar, dayEl, year, month, day) Event will be triggered after click on calendar day element
    calendarDayClick app
    change calendar (calendar, value) Event will be triggered when calendar value changes
    calendarChange app
    monthAdd calendar (calendar, monthEl) Event will be triggered when new month HTML layout has been added. Useful if you need to postprocess added html elements
    calendarMonthAdd app
    monthYearChangeStart calendar (calendar, year, month) Event will be triggered in the begining of transition to next month
    calendarMonthYearChangeStart app
    monthYearChangeEnd calendar (calendar, year, month) Event will be triggered after transition to next month
    calendarMonthYearChangeEnd app
    init calendar (calendar) Event will be triggered when calendar initialized
    calendarInit app
    open calendar (calendar) Event will be triggered when Calendar starts its opening animation. As an argument event handler receives calendar instance
    calendarOpen app
    opened calendar (calendar) Event will be triggered after Calendar completes its opening animation. As an argument event handler receives calendar instance
    calendarOpened app
    close calendar (calendar) Event will be triggered when Calendar starts its closing animation. As an argument event handler receives calendar instance
    calendarClose app
    closed calendar (calendar) Event will be triggered after Calendar completes its closing animation. As an argument event handler receives calendar instance
    calendarClosed app
    beforeDestroy calendar (calendar) Event will be triggered right before Calendar instance will be destroyed. As an argument event handler receives calendar instance
    calendarBeforeDestroy app

    Examples

    Default Setup

    <div class="block-title">Default setup</div>
    <div class="list no-hairlines-md">
      <ul>
        <li>
          <div class="item-content item-input">
            <div class="item-inner">
              <div class="item-input-wrap">
                <input type="text" placeholder="Your birth date" readonly="readonly" id="demo-calendar-default"/>
              </div>
            </div>
          </div>
        </li>
      </ul>
    </div>
    var calendarDefault = app.calendar.create({
      inputEl: '#demo-calendar-default',
    });
    
    

    Custom Date Format

    <div class="block-title">Custom date format</div>
    <div class="list no-hairlines-md">
      <ul>
        <li>
          <div class="item-content item-input">
            <div class="item-inner">
              <div class="item-input-wrap">
                <input type="text" placeholder="Select date" readonly="readonly" id="demo-calendar-date-format"/>
              </div>
            </div>
          </div>
        </li>
      </ul>
    </div>
    var calendarDateFormat = app.calendar.create({
      inputEl: '#demo-calendar-date-format',
      dateFormat: 'DD, MM dd, yyyy'
    });
    
    

    Multiple Values

    <div class="block-title">Multiple Values</div>
    <div class="list no-hairlines-md">
      <ul>
        <li>
          <div class="item-content item-input">
            <div class="item-inner">
              <div class="item-input-wrap">
                <input type="text" placeholder="Select multiple dates" readonly="readonly" id="demo-calendar-multiple"/>
              </div>
            </div>
          </div>
        </li>
      </ul>
    </div>
    
    var calendarMultiple = app.calendar.create({
      inputEl: '#demo-calendar-multiple',
      dateFormat: 'M dd yyyy',
      multiple: true
    });
    

    Range Picker

    <div class="block-title">Range Picker</div>
    <div class="list no-hairlines-md">
      <ul>
        <li>
          <div class="item-content item-input">
            <div class="item-inner">
              <div class="item-input-wrap">
                <input type="text" placeholder="Select date range" readonly="readonly" id="demo-calendar-range"/>
              </div>
            </div>
          </div>
        </li>
      </ul>
    </div>
    var calendarRange = app.calendar.create({
      inputEl: '#demo-calendar-range',
      dateFormat: 'M dd yyyy',
      rangePicker: true
    });

    Open In Modal

    <div class="block-title">Open in Modal</div>
    <div class="list no-hairlines-md">
      <ul>
        <li>
          <div class="item-content item-input">
            <div class="item-inner">
              <div class="item-input-wrap">
                <input type="text" placeholder="Select date" readonly="readonly" id="demo-calendar-modal"/>
              </div>
            </div>
          </div>
        </li>
      </ul>
    </div>
    
    var calendarModal = app.calendar.create({
      inputEl: '#demo-calendar-modal',
      openIn: 'customModal',
      header: true,
      footer: true,
      dateFormat: 'MM dd yyyy',
    });
    

    With Events

    <div class="block-title">With Events</div>
    <div class="list no-hairlines-md">
      <ul>
        <li>
          <div class="item-content item-input">
            <div class="item-inner">
              <div class="item-input-wrap">
                <input type="text" placeholder="Select date" readonly="readonly" id="demo-calendar-events"/>
              </div>
            </div>
          </div>
        </li>
      </ul>
    </div>
    
    var now = new Date();
    var today = new Date(now.getFullYear(), now.getMonth(), now.getDate());
    var weekLater = new Date().setDate(today.getDate() + 7);
    var calendarEvents = app.calendar.create({
        inputEl: '#demo-calendar-events',
        dateFormat: 'M dd yyyy',
        events: [
          {
            from: today,
            to: weekLater
          },
          //- more events this day
          {
            date: today,
            color: '#ff0000'
          },
          {
            date: today,
            color: '#00ff00'
          },
        ]
    });
    

    Disabled Dates

    <div class="block-title">Disabled Dates</div>
    <div class="list no-hairlines-md">
      <ul>
        <li>
          <div class="item-content item-input">
            <div class="item-inner">
              <div class="item-input-wrap">
                <input type="text" placeholder="Select date" readonly="readonly" id="demo-calendar-disabled"/>
              </div>
            </div>
          </div>
        </li>
      </ul>
    </div>
    
    var today = new Date();
    var weekLater = new Date().setDate(today.getDate() + 7);
    var calendarDisabled = app.calendar.create({
        inputEl: '#demo-calendar-disabled',
        dateFormat: 'M dd yyyy',
        disabled: {
          from: today,
          to: weekLater
        }
    });
    
    

    Inline With Custom Toolbar

    <div class="block-title">Inline with custom toolbar</div>
    <div class="block block-strong no-padding">
      <div id="demo-calendar-inline-container"></div>
    </div>
    
    var $$ = Dom7;
    var monthNames = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August' , 'September' , 'October', 'November', 'December'];
    var calendarInline = app.calendar.create({
      containerEl: '#demo-calendar-inline-container',
      value: [new Date()],
      weekHeader: false,
      renderToolbar: function () {
        return '<div class="toolbar calendar-custom-toolbar no-shadow">' +
          '<div class="toolbar-inner">' +
            '<div class="left">' +
              '<a href="#" class="link icon-only"><i class="icon icon-back ' + (app.theme === 'md' ? 'color-black' : '') + '"></i></a>' +
            '</div>' +
            '<div class="center"></div>' +
            '<div class="right">' +
              '<a href="#" class="link icon-only"><i class="icon icon-forward ' + (app.theme === 'md' ? 'color-black' : '') + '"></i></a>' +
            '</div>' +
          '</div>' +
        '</div>';
      },
      on: {
        init: function (c) {
          $$('.calendar-custom-toolbar .center').text(monthNames[c.currentMonth] +', ' + c.currentYear);
          $$('.calendar-custom-toolbar .left .link').on('click', function () {
            calendarInline.prevMonth();
          });
          $$('.calendar-custom-toolbar .right .link').on('click', function () {
            calendarInline.nextMonth();
          });
        },
        monthYearChangeStart: function (c) {
          $$('.calendar-custom-toolbar .center').text(monthNames[c.currentMonth] +', ' + c.currentYear);
        }
      }
    });