Datepicker

The Datepicker component is the ultimate tool for selecting a single date and/or time, multiple dates or a date range.

Basic usage

The following example will create a datepicker with the default options.

By default the datepicker will be set up to single date selection with the calendar control.

JSX
import { Datepicker } from '@mobiscroll/react';

const App = () => {
  return <Datepicker />;
}

For many more examples - simple and complex use-cases - check out the date picker demos for react.

Value Selection

The datepicker can be used for three major dates and time selection tasks:

  1. Single value selection - a date, time or date-time - use the date & time or calendar
  2. Multiple value selection - one or more dates - use the date picker or calendar
  3. Range selection - a pair of start/end date, time or date-times - use the range picker
The select and selectMultiple options control how the selection works.

Single Value Selection

This is the default behavior, and it can also be initialized with the select: 'date' option. Depending on the controls option, we can use the datepicker this way to select either a single date or a single time or both (a single datetime).

Date picker
const App = () => {
    const [myBirthday, setMyBirthday] = React.useState(null);
    const pickerChange = (ev) => {
        setMyBirthday(ev.value);
    }
    return <Datepicker select="date" value={myBirthday} onChange={pickerChange} />;
}

Multiple Value Selection

The selectMultiple option will enable us to select multiple dates on the calendar. The selected value in this case will be an array of dates instead of just a single date.

Multiple date picker
const App = () => {
    const [myCleaningDays, setMyCleaningDays] = React.useState(null);
    const pickerChange = (ev) => {
        setMyCleaningDays(ev.value);
    }
    return <Datepicker selectMultiple={true} value={myCleaningDays} onChange={pickerChange} />;
}

Range Selection

The datepicker can be used to select a date or a time range. The range selection feature can be activated with the select: 'range' option. The selected value in this case will be an array of dates with two values: the start and the end.

The controls option will tell the datepicker what kind of range do we want to select, a date range or a time range.

Date Range Picker
const App = () => {
    const [myHoliday, setMyHoliday] = React.useState(null);
    const pickerChange = (ev) => {
        setMyHoliday(ev.value);
    }
    return <Datepicker select="range" value={myHoliday} onChange={pickerChange} />;
}

Return values

The default type of return values is the JavaScript Date object, but Mobiscroll supports more types as well. The Datepicker will choose the type depending on the returnFormat option.

Here's a list on supported formats and some hints on where are they really usefull:

When working with 'moment', you need to ensure that your project includes the Moment.js library and also you will need to pass the moment libary reference to the Datepicker. Here's an example how:

Passing the reference of the moment to the Datepicker
import * as moment from 'moment';

function App() {
    const [myValue, setMyValue] = React.useState(moment());
    const myChange = (ev) => {
        setMyValue(ev.value); // ev.value is a Moment object
    }
    return <Datepicker moment={moment} returnFormat="moment" onChange={myChange} value={myValue} />
}

Controls

The datepicker component can render different kinds of controls on the screen. These controls are referred to as the Calendar view, the Date picker, the Time picker and the Datetime picker. Each of these controls are suitable in different scenarios, depending on the use-case.

For example, the Date picker can be used for selecting a single date, as well as the Calendar view. But only the Calendar view can be used for selecting multiple dates.

Single vs. Multiple Date selection
const App = () => {
    const [myBirthday, setMyBirthday] = React.useState(null);
    const myPickerChange = (ev) => {
        setMyBirthday(ev.value);
    }
    const [kidsBirthday, setKidsBirthday] = React.useState(null);
    const kidsPickerChange = (ev) => {
        setMyBirthday(ev.value);
    }
    return <>
        <Datepicker controls={['date']} value={myBirthday} onChange={myPickerChange} />
        <Datepicker controls={['calendar']} selectMultiple={true} value={kidsBirthday} onChange={kidsPickerChange} />
    </>;
}

Control combinations

Some controls can't be used in all situations. To have a better user experience, controls can be combined. The controls options takes an array of strings, with predefined values.

The Time picker control can be combined with either the Calendar view or the Date picker for extending the selection precision.

Combined controls
const App = () => {
    const [myAppointment, setMyAppointment] = React.useState(null);
    const myPickerChange = (ev) => {
        setMyAppointment(ev.value);
    }
    return <>
        <!-- Date & Time picker -->
        <Datepicker controls={['date', 'time']} value={myAppointment} onChange={myPickerChange} />
        <!-- Calendar view & Time picker -->
        <Datepicker controls={['calendar', 'time']} value={myAppointment} onChange={myPickerChange} />
    </>;
}

Customizing the Input

The datepicker, as explained below, can be used with one, two or no inputs.

Using without inputs

The first choice of input customization is to have no inputs at all. In this case rendering the component in inline display mode will leave out the use of inputs.

Inline picker
const App = () => {
    const [myAppointment, setMyAppointment] = React.useState(null);
    const myPickerChange = (ev) => {
        setMyAppointment(ev.value);
    }
    return <Datepicker display="inline" value={myAppointment} onChange={myPickerChange} />;
}

Using with one input

The datepicker component will render a Mobiscroll Input by default. This input will hold the formatted value after selection.

Using a custom input can be done with the inputComponent prop. In this case the datepicker will render the component provided and pass the formatted value to it.

To pass props to the custom component, you can use the inputProps prop.

Using IonInput as a Custom Input
import { IonInput, IonItem } from '@ionic/react';

const app = () => {
  const ionInputProps = {
    placeholder: 'Click to select',
    readOnly: true,
  };

  return <IonItem>
       <Datepicker inputComponent={IonInput} inputProps={ionInputProps} />
    </IonItem>;
}

Using with two inputs

When selecting a range, you have basically two values to display: the start of the range and the end of the range. These can be shown in different inputs using the startInput and the endInput options.

Two inputs for range selection
import { Input, Datepicker } from '@mobiscroll/react';

const app = () => {
  const [start, setStartInput] = React.useState(null);
  const [end, setEndInput] = React.useState(null);

  return <>
      <Input ref={setStartInput} label="Start date" />
      <Input ref={setEndInput} label="End date" />
      <Datepicker select="range" startInput={start} endInput={end} />
    </>;
}

When the startInput and the endInput options are provided, the datepicker will not render any other inputs. It will open when these inputs are focused/clicked instead.

Display modes

The datepicker component can operate in two ways from the display option's point of view:

Here comes the center, top, bottom displays, and also the anchored display when the touchUi option is true.

In these display modes, the picker shows up as a modal picker. When open, the selected value is stored as a temporary value until the set button is pressed. At that point the picker is closed and the value is commited to the state.

The above mentioned temporary value, when required, can be manipulated using the getTempVal() and setTempVal() instance methods. Whe the temporary value changes the onTempChange event is raised.

"Live" selection

Here come the inline display (which displays as an embedded control) and the anchored display when the touchUi options is false (on desktop devices).

In this case by default there is no set button to commit the value, so there's no temporary value like when the modal displays are used. What is shown on the picker, that is set directly to the state

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:

In string format the specified properties are separated by the ';' character.

As object
recurring: {
  repeat: 'daily',
  count: 5,
  interval: 2
}
As string
recurring: 'FREQ=DAILY;COUNT=5;INTERVAL=2'

Examples

JSX
import { Datepicker } from '@mobiscroll/react';

const App = () => {
    const myInvalids = useMemo(() => [{
        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'
    }], []);
    return <Datepicker invalid={myInvalids} />;
}

Recurring exceptions

In case you would like to skip some dates from your rule, that's when the recurring exception come in handy. You can either set specific dates and/or a recurring rule as an exception, using the recurringException and the recurringExceptionRule properties.

JSX
import { Datepicker } from '@mobiscroll/react';

const App = () => {
    const myInvalids = useMemo(() => [{
        start: '2021-06-01',
        end: '2021-06-01'
        recurring: {
            repeat: 'daily',
            until: '2021-12-31'
        },
        // exact dates as exceptions
        recurringException: ['2021-07-10', '2021-07-11'],
        // recurring rule as an exception
        recurringExceptionRule: {
            repeat: 'monthly',
            day: 15
        }
    }, {
        start: '08:30',
        end: '10:00',
        // Every Monday and Friday, except every second month\'s 3rd',
        recurring: 'FREQ=WEEKLY;UNTIL=2021-06-01;BYDAY=MO,FR',
        recurringExceptionRule: 'FREQ=MONTHLY;BYMONTHDAY=3;INTERVAL=2'
    }], []);
    return <Datepicker invalid={myInvalids} />;
}

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 to the renderCalendarHeader option.

Fully custom header
const customTemplate = () => {
    return <>
        <p>Any <strong>Title</strong> you want here or</p>
        <YourCustomComponent yourProp="yourPropValue" />
    </>
}
<Datepicker renderCalendarHeader={customTemplate} />

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 components between them.

Here's the list of the built in components of the default header:

The above 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).

Custom header with default buttons
const myTitle = 'My Awesome title';
const customWithNavButtons = () => {
    return <>
        <CalendarPrev />
        <CalendarNext />
        <div className="my-custom-title">{myTitle}</div>
    </>;
}

<Datepicker renderCalendarHeader={customWithNavButtons} />

Options

Name Type Default value Description
anchor HTMLElement undefined Specifies the anchor element for positioning, if display is set to 'anchored' . 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:
  • 'pop'
  • 'slide-down'
  • 'slide-up'
If 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:
  • 'set' - Sets the value.
  • 'cancel' - Dismisses the popup.
To modify the text of the predefined buttons, you can use the setText, , cancelText options.

If an object, it may have the following properties:
  • text String - Text of the button.
  • handler String, Function - The function which will run when the button is pressed. If a string, it must be one of the predefined button handlers:
    • 'set' - Sets the value.
    • 'cancel' - Dismisses the popup.
  • icon String (Optional) - Icon of the button.
  • cssClass String (Optional) - Css class of the button.
  • keyCode Number, String, Array (Optional) - The key code associated with the button to activate it from keyboard. Can be a single value or multiple value passed as an array. Predifine string values are: 'enter', 'esc' and 'space'.
Predefined and custom buttons example
buttons: [
    'set',
    {
        text: 'Custom',
        icon: 'checkmark',
        cssClass: 'my-btn', 
        handler: function (event) {
            alert('Custom button clicked!');
        }
    },
    'cancel'
]
Predefined button handler example
buttons: [
    'set',
    {
        text: 'Hide',
        handler: 'cancel',
        icon: 'close',
        cssClass: 'my-btn'
    }
]
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.

  • 'horizontal' - navigating the view horizontally.
  • 'vertical' - navigationg the view vertically.

When navigation is 'vertical' the outer days (days from previous and next months) are hidden. You can explicitly override it with the showOuterDays option.

calendarSystem Object undefined Specify the calendar system to be used. Supported calendar systems:
  • Gregorian - This is the default calendar system, no setting needs to be passed.
  • Jalali - Default system of the Persian calendar. The Farsi language needs to be included to the package.
    import { Eventcalendar, jalaliCalendar } from '@mobiscroll/react';
    
    export function MyComponent() {
      return <Eventcalendar calendarSystem={jalaliCalendar} />;
    }
    
  • Hijri - Arabic language needs to be included to the package.
    import { Eventcalendar, hijriCalendar } from '@mobiscroll/react';
    
    export function MyComponent() {
      return <Eventcalendar calendarSystem={hijriCalendar} />;
    }
    
calendarType String 'month'

Sets the calendar type. Possible values: 'month', 'week'.

In case of 'month' set the number of displayed months using the pages option.

In case of 'week' set the number of displayed weeks using the weeks option.

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:
  • allDay Boolean - Specifies whether the date you want to color is all day or not.
  • date Date, String, Object - Date of the calendar day which should be colored.
  • start Date, String, Object - Start date/time of the calendar days/cells which should be colored.
  • end Date, String, Object - End date/time of the calendar days/cells which should be colored.
  • background: String - Background color of the cell, can be any valid CSS color ('red', '#ff0000', 'rgb(255,0,0)', etc.).
  • highlight: String - Highlight color of the day, can be any valid CSS color ('red', '#ff0000', 'rgb(255,0,0)', etc.).
  • recurring String, Object - Recurrence rule for coloring recurring days.
  • recurringException: String, Object, Array - Recurrence exception for recurring colors.
  • recurringExceptionRule: String, Object - Recurrence exception rule for recurring colors.
  • cellCssClass: String - CSS class for the day cell.
  • resource: String, Number, Array of String | Number - specify resource ids for the color. The color will display only in the specified resource group. If there is no resource id defined the color will be displayed at every resource group.
The colored range will be considered all-day if:
  • allDay is explicitly set.
  • start/end is not specified, only the date.
The dates can be specified as Javascript Date objects, ISO 8601 strings, or moment objects.
The colors can be combined with the labels or marked options.
Example
colors: [
    { date: new Date(2020,2,23), background: 'pink' },
    { date: new Date(2020,2,24), background: 'green' },
    { background: '#ff0000', recurring: { repeat: 'weekly', weekDays: 'SU' },
    { background: 'yellow', recurring: { repeat: 'weekly', weekDays: 'SA' } }
]
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:
  • ['calendar']
  • ['calendar', 'time']
  • ['date']
  • ['datetime']
  • ['date', 'time']
  • ['time']
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 null is passed, in case of the calendar control there will be no selected value, in case of scroller controls the current date and time will still be displayed on the selected line, as an empty value cannot be displayed on the scroller.

defaultValue Date, String, moment, Array undefined Default value of the component in case of uncontrolled usage. For specifying a default selection, without the value being set, use the defaultSelection option.
disabled Boolean false Initial disabled state of the component.
display String undefined Controls the positioning of the component. Possible options:
  • 'center' - The component appears as a popup at the center of the viewport.
  • 'inline' - If called on div element, the component is placed inside the div (overwriting existing content), otherwise is placed after the original element.
  • 'anchored' - The component appears positioned to the element defined by the anchor option. By default the anchor is the original element.
  • 'top' - The component appears docked to the top of the viewport.
  • 'bottom' - The component appears docked to the bottom of the viewport.

The default display mode depends on the theme, it defaults to 'bottom' for the iOS theme and to 'center' for all other themes.

In desktop mode (when the touchUi option is set to false) the default display mode is 'anchored'.

endInput String, HTMLElement, Mobiscroll Input or IonInput 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.
inputComponent Function, String undefined

The input component to render if the picker is modal (the display option is not set to 'inline').

The following values are supported:

  • 'input' - renders a standard HTML input.
  • IonInput - renders an IonInput in case of Ionic React.

If not specified, a mobiscroll Input will be rendered.

Props can be specified using the inputProps option.

inputProps Object undefined Props for the rendered input, specified by the inputComponent option.
inRangeInvalid Boolean false

In case of range selection, determines if the invalid dates are allowed between the start and the end date.

When inRangeInvalid is set to false, the end selection will be limited to the next invalid date from the selected start date.

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:
  • start: Date, String, Object - Start of the invalid range.
  • end: Date, String, Object - End of the invalid range.
  • recurring: String, Object - Recurrence rule for recurring invalid ranges.
  • recurringException: String, Object, Array - Recurrence exception for recurring invalids.
  • recurringExceptionRule: String, Object - Recurrence exception rule for recurring invalids.
Example
invalid: [
    /* Passing exact dates will block out the entire day */
    new Date(2021, 1, 7), // Date object
    '2021-10-15T12:00', // string
    moment("2020-12-25"), // moment object

    /* Passing invalids as an object and defining start/end ranges */
    { 
      // specify invalid date ranges using ISO 8601 strings
      start: '2021-10-15T12:00',
      end: '2021-10-18T13:00', 
      title: 'Company 10th anniversary',
    },
    {
      // specify invalid date ranges using Date objects
      allDay: true,
      start: new Date(2021, 2, 7),
      end: new Date(2021, 2, 9),
      title: 'Conference for the whole team',
    },
    {
      // specify invalid time ranges only
      start: '13:00',
      end: '12:00',
      recurring: { repeat: 'weekly', weekDays: 'MO,TU,WE,TH,FR' },
      title: 'Lunch break',
    },
    {
      // disable weekends
      recurring: {
          repeat: 'weekly',
          weekDays: 'SA,SU'
      }
    }
];
isOpen Boolean undefined Specifies wether the popup is opened or not. Use it together with the onClose event, by setting it to false when the popup closes.
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:
  • date Date, String, Object - Date of the calendar label.
  • start Date, String, Object - Start date of the calendar label.
  • end Date, String, Object - End date of the calendar label.
  • color String - The color of the label, can be any valid CSS color ('red', '#ff0000', 'rgb(255,0,0)', etc.).
  • text String - The text of the label.
  • recurring: String, Object - Recurrence rule for recurring labels.
  • recurringException: String, Object, Array - Recurrence exception for recurring labels.
  • recurringExceptionRule: String, Object - Recurrence exception rule for recurring labels.
  • cellCssClass: String - CSS class for the day cell.
The dates can be specified as Javascript Date objects, ISO 8601 strings, or moment objects.
The labels can be combined with the colors option.
Example
labels: [{
  start: new Date(2020, 2, 23),
  end: new Date(2020, 2, 24),
  text: 'Conference',
  color: 'red'
}, {
  text: 'Christmas',
  recurring: { repeat: 'yearly', month: 12, day: 24 }
}]
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:
  • date Date, String, Object - Date of the day to be marked.
  • start Date, String, Object - Start date of the days to be marked.
  • end Date, String, Object - End date of the days to be marked.
  • color String - The color of the mark, can be any valid CSS color ('red', '#ff0000', 'rgb(255,0,0)', etc.).
  • recurring: String, Object - Recurrence rule for recurring marked days.
  • recurringException: String, Object, Array - Recurrence exception for marked days.
  • recurringExceptionRule: String, Object - Recurrence exception rule for marked days.
  • cellCssClass: String - CSS class for the day cell.
  • markCssClass: String - CSS class for the mark.
The dates can be specified as Javascript Date objects, ISO 8601 strings, or moment objects.
The marked option can be combined with the colors option.
Example
marked: [
  new Date(2020, 2, 15),
  new Date(2020, 2, 22),
  {
    start: new Date(2020, 2, 23),
    end: new Date(2020, 2, 24),
    color: 'red'
  },
  {
    color: 'green',
    recurring: { repeat: 'yearly', month: 12, day: 24 }
  }
]
max Number 100 Maximum value.
maxRange Number undefined

It sets the maximum range that can be selected. When selecting a date without the time part, it sets the maximum number of days the selected range can contain. When there is a time part in the selection, it sets the maximum range 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.
maxWidth Number, String 600 Sets the maximum width of the component.
min Number 0 Minimum value.
minRange Number undefined

It sets the minimum range that can be selected. When selecting a date range without the time part, it sets the minimum number of days the selected range can contain. When there is a time part in the selection, it sets the minimum range 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
minWidth Number, String undefined Sets the maximum width of the component.
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 !
multiple Boolean false If true, multiple selection will be enabled.
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.
rangeHighlight Boolean true

When selecting a range on the calendar control, it is optional to highlight the dates between the start and end date.

By default, the dates are highlighted between the start and end values. When the highlight is turned off, only the start and end dates are shown as selected on the calendar.

On desktop devices where a cursor is available, hovering the calendar days also help to visualize the selecting range. The hover styling is also turned off, when the range is not highlighted.

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
const myCustomHeader = () => {
    return <>
        <CalendarPrev />
        <CalendarNext />
    </>
}
responsive Object undefined Specify different settings for different viewport 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.

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
Custom breakpoints can be defined by passing an object containing the breakpoint property specifying the min-width in pixels. Example:
responsive: {
    small: {
        display: 'bottom'
    },
    custom: { // Custom breakpoint
        breakpoint: 600,
        display: 'center'
    },
    large: {
        display: 'anchored'
    }
}
returnFormat String 'jsdate' Specifies the format in which the selected date(s) is returned in the onChange event.
Possible values:
  • 'jsdate' - Javascript date object
  • 'iso8601' - ISO 8601 date string.
  • 'locale' - Formatted date string based on the lang setting, or the dateFormat and timeFormat settings, if they are specified.
  • 'moment' - moment object. Ensure that moment.js is loaded.
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).
select String 'date'

In terms of value selection, the datepicker can be used to select a single date/time or multiple dates/times, as well as a date range or a time range.

The select setting defines if the picker is used for selecting independent dates or a range.

Possible values are:

  • 'date' - it is used for single of multiple date/time selection
  • 'range' - it is used for date range or time range selection

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.
showArrow Boolean true Show or hide the popup arrow, when display mode is 'anchored'.
showInput Boolean true If true, it will render an input field for the component.
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 'vertical'.

showOverlay Boolean true Show or hide overlay.
showRangeLabels Boolean true

By default when selecting a range, a start and end label is shown on the Datepicker. These labels indicate which part of the range are we selecting (start or end). The labels can also be used to switch the active selection from start to end or vice versa.

The showRangeLabels option can be used to show or hide the labels.

The start label text and end label text as well as the start value placeholder and end value placeholder can be localized and/or customized.

showWeekNumbers Boolean false Show week numbers on the calendar view. Enumeration starts with the first week of the year.
startInput String, HTMLElement, Mobiscroll Input or IonInput 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 'auto' or undefined, the theme will automatically be chosen based on the platform. If custom themes are also present, they will take precedence over the built in themes, e.g. if there's an iOS based custom theme, it will be chosen on the iOS platform instead of the default iOS theme.

Supplied themes:
  • 'ios' - iOS theme
  • 'material' - Material theme
  • 'windows' - Windows theme
It's possible to modify theme colors or create custom themes.
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:
  • 'light' - Use the light variant of the theme.
  • 'dark' - Use the dark variant of the theme.
  • 'auto' or undefined - Detect the preferred system theme on devices where this is supported.

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 '-dark', e.g.: 'my-theme' and 'my-theme-dark'.

touchUi Boolean, String 'auto'

Use true to render a touch optimized user interface, or false for a user interface optimized for pointer devices (mouse, touchpad).

Can be used with the responsive option to change the user interface based on viewport width.

If set to 'auto', the touch UI will be automatically enabled based on the platform.

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 make an option dynamic, you can pass a variable as option value. Whenever the value of the variable changes, the component will be re-rendered.

const App = () => {
        
  const [myTheme, setMyTheme] = useState('ios');

  const changeTheme = useCallback(() => {
    // Changes the theme to Material
    setMyTheme('material');
  }, []);

  return <div>
    <Datepicker theme={myTheme} />
    <button onClick={changeTheme}>Change theme</button>
  </div>;
};
For performance reasons on re-render we compare prop values by reference. This means, that in case of options, which accept complex data structures, like arrays or objects, changes made inside the array or object won't be detected. To ensure the change is detected, always pass a new array or object reference.

Events

Name Description
onCancel(event, inst) Allows you to define your own event when cancel is pressed.

Parameters

  • event: Object - The event object has the following properties:
    • valueText: String - The selected value as text.
  • inst: Object - The instance object of the datepicker.

Example

<mobiscroll.Datepicker
    onCancel={function (event, inst) {
    }}
/>
onCellClick(event, inst) Triggered when a cell is clicked on the calendar or on the schedule grid.

Parameters

  • event: Object - The event object has the following properties:
    • date: Date - The date of the clicked cell.
    • domEvent: Event The DOM event of the click.
    • resource: String, Number - The id of the resource where the cell was clicked, if resources are set.
    • selected: Boolean - Specifies if the day is currently selected or not (before it was clicked).
    • source: String - The view where the cell was clicked, 'calendar' or 'schedule'.
    • target: HTMLElement - The DOM element of the clicked cell.
  • inst: Object - The instance object of the datepicker.

Example

<mobiscroll.Datepicker
    onCellClick={function (event, inst) {
    }}
/>
onChange(event, inst) Triggered when the value is changed.

Parameters

  • event: Object - The event object has the following properties:
    • value - The selected value
    • valueText: String - The selected value as text (if any).
  • inst: Object - The instance object of the datepicker.

Example

<mobiscroll.Datepicker
    onChange={function (event, inst) {
    }}
/>
onClose(event, inst) Triggered when the component is closed.

Parameters

  • event: Object - The event object has the following properties:
    • valueText: String - The selected value as text.
  • inst: Object - The instance object of the datepicker.

Example

<mobiscroll.Datepicker
    onClose={function (event, inst) {
    }}
/>
onDestroy(event, inst) Triggered when the component is destroyed.

Parameters

  • event: Object - The event object.
  • inst: Object - The instance object of the datepicker.

Example

<mobiscroll.Datepicker
    onDestroy={function (event, inst) {
    }}
/>
onInit(event, inst) Triggered when the component is initialized.

Parameters

  • event: Object - The event object.
  • inst: Object - The instance object of the datepicker.

Example

<mobiscroll.Datepicker
    onInit={function (event, inst) {
    }}
/>
onLabelClick(event, inst) Triggered when a label on the calendar is clicked.

Parameters

  • event: Object - The event object has the following properties:
    • date: Date - The date of the day on which the label was clicked.
    • domEvent: Event - The DOM event of the click.
    • label: Object - The original object of the label which was clicked, undefined in case of the "more" label.
    • labels: Array - An array containing each label object for the given day.
    • target: HTMLElement - The DOM element of the label.
  • inst: Object - The instance object of the datepicker.

Example

<mobiscroll.Datepicker
    onLabelClick={function (event, inst) {
    }}
/>
onOpen(event, inst) Triggered when the component is opened.

Parameters

  • event: Object - The event object has the following properties:
    • target: Object - The DOM element containing the generated html.
    • valueText: String - The selected value as text.
  • inst: Object - The instance object of the datepicker.

Example

<mobiscroll.Datepicker
    onOpen={function (event, inst) {
    }}
/>
onPageChange(event, inst) Triggered when the calendar page is changed (month or week, with buttons or swipe).

Parameters

  • event: Object - The event object has the following property:
    • firstDay: Date - The first day of the displayed page.
    • lastDay: Date - The last day of the displayed page.
    • month: Date - The first day of the visible month in case of month view.
  • inst: Object - The instance object of the datepicker.

Example

<mobiscroll.Datepicker
    onPageChange={function (event, inst) {
    }}
/>
onPageLoaded(event, inst) Triggered when the calendar page is changed (month or week, with buttons or swipe) and the animation has finished.

Parameters

  • event: Object - The event object has the following property:
    • firstDay: Date - The first day of the displayed page.
    • lastDay: Date - The last day of the displayed page.
    • month: Date - The first day of the visible month in case of month view.
  • inst: Object - The instance object of the datepicker.

Example

<mobiscroll.Datepicker
    onPageLoaded={function (event, inst) {
    }}
/>
onPageLoading(event, inst) Triggered before the markup of a calendar page (month or week) is starting to render.

Parameters

  • event: Object - The event object has the following property:
    • firstDay: Date - The first day of the displayed page.
    • lastDay: Date - The last day of the displayed page.
    • month: Date - The first day of the visible month in case of month view.
  • inst: Object - The instance object of the datepicker.

Example

<mobiscroll.Datepicker
    onPageLoading={function (event, inst) {
    }}
/>
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

  • event: Object - The event object has the following properties:
    • target: Object - The DOM element containing the generated html.
    • windowWidth: Number - The window width.
    • windowHeight: Number - The window height.
  • inst: Object - The instance object of the datepicker.

Example

<mobiscroll.Datepicker
    onPosition={function (event, inst) {
    }}
/>
onTempChange(event, inst) Triggered when the temporary value is changed.

Parameters

  • event: Object - The event object has the following properties:
    • value: String, Date, Moment.js Object or Array of String, Date, Moment.js object - The selected value.
  • inst: Object - The instance object of the datepicker.

Methods

Name Description
close() Closes the component.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.close();
getVal() Returns the selected value of the picker, that has been set to the model 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 getTempVal method on the picker instance.

Returns: String, Date, Moment.js Object or Array of String, Date or Moment.js Object

The return value type depends on the returnFormat and the select option.

The getTempVal and getVal methods are usually for advanced use-cases, when the built in options and the state management tools of React are not sufficien to work with.
isVisible() Returns a boolean indicating whether the component is visible or not.

Returns: Boolean

  • True if the component is visible, false if it's not.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.isVisible();
navigate(date) Display a specific month on the calendar without setting the date.

Parameters

  • date: Date, String, Object - Date to navigate to. Can be a Date object, ISO8601 date string, or moment object.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.navigate(new Date(2016, 1, 1));
open() Opens the component.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.open();
position() Recalculates the position of the component (if not inline).

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.position();
setActiveDate(active) Sets which date is currently selected (start or end). If the picker is visible, it will also highlight the respective date.

Parameters

  • active: String - Currently selected date. It can be 'start' or 'end'.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.setActiveDate('start');
setVal(value) Sets the picker value and also writes it to the model.

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 setTempVal method on the picker instance.

To get the current selected value, check out the getVal instance method.

Parameters

  • value: String, Date, Moment.js Object or Array of String, Date or Moment.js Object - the value to set to the picker

The value type should be choosen depending on the returnFormat and the select option.

The setTempVal and setVal methods are usually for advanced use-cases, when the built in options and the state management tools of React are not sufficien to work with.

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.
  • M - month of year (no leading zero)
  • MM - month of year (two digit)
  • MMM - month name short
  • MMMM - month name long
  • D - day of month (no leading zero)
  • DD - day of month (two digit)
  • DDD - day of week (short)
  • DDDD - day of week (long)
  • YY - year (two digit)
  • YYYY - year (four digit)
  • '...' - literal text
  • '' - single quote
  • anything else - literal text
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:

dateWheels: '|D M d|' // Will produce 'Sun Sep 9'
            
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:
  • Arabic: localeAr
  • Bulgarian: localeBg
  • Catalan: localeCa
  • Czech: localeCs
  • Chinese: localeZh
  • Croatian: localeHr
  • Danish: localeDa
  • Dutch: localeNl
  • English: localeEn or undefined
  • English (UK): localeEnGB
  • Farsi: localeFa
  • German: localeDe
  • Greek: localeEl
  • Spanish: localeEs
  • Finnish: localeFi
  • French: localeFr
  • Hebrew: localeHe
  • Hindi: localeHi
  • Hungarian: localeHu
  • Italian: localeIt
  • Japanese: localeJa
  • Korean: localeKo
  • Lithuanian: localeLt
  • Norwegian: localeNo
  • Polish: localePl
  • Portuguese (Brazilian): localePtBR
  • Portuguese (European): localePtPT
  • Romanian: localeRo
  • Russian: localeRu
  • Russian (UA): localeRuUA
  • Slovak: localeSk
  • Serbian: localeSr
  • Thai: localeTh
  • Swedish:localeSv
  • Turkish: localeTr
  • Ukrainian: localeUa
  • Vietnamese: localeVi
import { Eventcalendar, localeDe } from '@mobiscroll/react';

export function MyComponent() {
  return <Eventcalendar locale={localeDe} />;
}
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.
rangeEndHelp String 'Please select' When selecting a range, it specifies the placeholder text for the end value under the end label.
rangeEndLabel String 'End' When selecting a range, it specifies the text of the end label.
rangeStartHelp String 'Please select' When selecting a range, it specifies the placeholder text for the start value under the start label.
rangeStartLabel String 'Start' When selecting a range, it specifies the text of the start label.
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
  • h - 12 hour format (no leading zero)
  • hh - 12 hour format (leading zero)
  • H - 24 hour format (no leading zero)
  • HH - 24 hour format (leading zero)
  • m - minutes (no leading zero)
  • mm - minutes (leading zero)
  • s - seconds (no leading zero)
  • ss - seconds (leading zero)
  • a - lowercase am/pm
  • A - uppercase AM/PM
  • '...' - literal text
  • '' - single quote
  • anything else - literal text
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:
timeWheels: '|h:mm A|' // Will produce '9:12 AM' 
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:

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/React/dist/css/mobiscroll.react.scss"
It's important that you override the variables BEFORE the scss file import, otherwise it won't make any difference.
Here's a complete guide on how to set up Mobiscroll with SASS support

You can also customize the colors on many levels:

  1. Theme specific variables (ex. $mbsc-material-background, $mbsc-ios-dark-text) are applied to all components in a theme. Complete list of variables here.
  2. Component specific global variables (ex. $mbsc-card-background-light, $mbsc-listview-text-dark) are applied to all themes for a specific component.
  3. 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.

Hereinafter you will see all the variables that are specific to the Datepicker component or affect its look: