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 in three major areas for selecting dates and times:

  1. single value selection
  2. multiple value selection
  3. range selection
The options that control what selection is on, are the select and the selectMultiple.

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} />;
}

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

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 String, 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.
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:
  • date Date, String, Object - Date of the calendar day which should be colored.
  • start Date, String, Object - Start date of the calendar days which should be colored.
  • end Date, String, Object - End date of the calendar days which should be colored.
  • background: String - Background color of the day 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.
  • cellCssClass: String - CSS class for the day cell.
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.
fullScreen Boolean false If true, the popup will appear in full screen, but, by default, its width and height won't exceed 600px. You can change that using the maxWidth and maxHeight options.
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.
invalid Array undefined An array containing the invalid values. Must be an array containing dates (Javascript Date objects, ISO 8601 strings, or moment objects), or objects with the following properties:
  • start: Date, String, Object - Start date of the calendar days which should be invalid.
  • end: Date, String, Object - End date of the calendar days which should be invalid.
  • recurring: String, Object - Recurrence rule for recurring invalid days.
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.
  • 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.
  • 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.
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) should be returned by the getVal method
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.
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.

valid Object null Can be used to override invalid dates and times. E.g. if every Thursday is set to invalid, but you want May 15th, 2014 to be valid, you can do it using the valid option. The syntax is the same as for the invalid option.
It's important if you want to use the valid setting together with invalid make sure to set: invalid day with valid day, invalid time with valid time or both invalid date and time with valid date and time. So in case you use an invalid day and a valid time, this will not override the invalid setting.
A sample configuration
invalid: [
    { start: '00:00', end: '23:59' }, // Invalid time
    { start: new Date(2018, 11, 21), end: new Date(2018, 11, 31) } // Invalid date
],
valid: [
    { start: '09:00', end: '20:00' }, // Valid time
    { start: new Date(2018, 11, 26), end: new Date(2018, 11, 30) } // Valid date
]
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 component.

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.
    • selected: Boolean - Specifies if the day is currently selected or not (before it was clicked).
    • 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:
    • 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();
getTempVal()

Returns the temporary value that's selected on the picker.

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.

The value that has been set to the model can be aquired using the getVal() method.

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.

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.

getVal([temp]) Returns the selected datepicker value.

Parameters

  • temp (Optional): Boolean - If true, returns the temporary values (prior clicking the Set button).

Returns: String

  • The selected datepicker value.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.getVal();
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();
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();
setOptions(options) Update options for the component.

Parameters

  • options: Object - A map of option-value pairs to set.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.setOptions({
    display: 'bottom'
});
setTempVal(value)

Sets the temporary value that's selected on the picker.

Depending on how the picker is displayed, the selection shown might be just a temporary value until the users hits 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 temporary value, check out the getTempVal instance method.

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.

Parameters

  • value: String, Date, Moment.js Object or Array of String, Date, Moment.js Object - Can be a date string in the specified date format, a Date object, a Moment.js Object or an Array of these.

The type of the value parameter depends on the returnFormat and the select options.

setVal(value [, fill ] [, change ] [, temp ] [, time ]) Sets the datepicker value.

Parameters

  • value: String - The datepicker value.
  • fill (Optional): Boolean - If true, the associated input element is also updated with the new value.
  • change (Optional): Boolean - If false, change event won't be triggered on the input element.
  • temp (Optional): Boolean - If true, only temporary value is set.
  • time (Optional): Number - Specifies the duration of the animation in seconds to scroll the wheels to the new values. There is no animation, if time is omitted or 0.

Example

Methods can be called on an instance. For more details see calling methods

Localization

Name Type Default value Description
amText String 'am' Text for AM.
cancelText String 'Cancel' Text for Cancel button.
clearText String 'Clear' Text for the clear 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:ii 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:ii 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: