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.

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

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

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.

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.

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:

• 'jsdate'

  - Javascript date object - Ex. if you need to manipulate programmatically the selected value further, the Date object is a good starting point, since it has most of the functions for date ∧ time manipulation

• 'iso8601'

  - ISO 8601 date string - Ex. if you need to send the selected value to a server, or need to serialize it, the ISO8601 string is the way to go.

• 'locale'

  - Formatted date string based on the lang setting, or the dateFormat and timeFormat settings, if they are specified. It gives the most flexible formatting options.

• 'moment'

  - moment object - The Moment.js library helps in manipulating the date ∧ time values. It has many functions the built in JavaScript Date object doesn't. It is very convenient when working a lot with dates.

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:

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.

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

• The Calendar view can be used for single or multiple date selection as well as date range selection. It is represented by the 'calendar' string. It is the default of the controls option.

• The Date picker can be used for single date selection or date range selection. It is represented by the 'date' string.

• The Time picker can be used for single time selection or time range selection. It can also be combined with other controls. It is represented by the 'time' string.

• The Datetime picker can be used for single date & time selection as well as date & time range selection. It is represented by the 'datetime' string.

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.

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.

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.

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.

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:

• Modal display modes
• "Live" selection

Modal display

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:

• repeatString - The frequency of the recurrence. String equivalent: FREQ.
  • 'daily' - Daily repeat
  • 'weekly' - Weekly repeat
  • 'monthly' - Monthly repeat
  • 'yearly' - Yearly repeat
• dayNumber - The day of the month in case of monthly and yearly repeat. String equivalent: BYMONTHDAY.
  Negative numbers are calculated from the end of the month, -1 meaning the last day of the month.
  Specifying multiple days for the rule is currently not supported.
  Rules like every first/second/third/fourth week day of month are currently not supported.
• monthNumber - Specify the month in case of yearly repeat. String equivalent: BYMONTH.
  Specifying multiple months for the rule is currently not supported.
• weekDaysString - Comma separated list of the week days ('SU', 'MO', 'TU', 'WE', 'TH', 'FR', 'SA') for the occurrences. String equivalent: BYDAY.
• countNumber - The number of occurrences. String equivalent: COUNT.
• fromDate, String, Object - The start date of the occurrences. String equivalent: DTSTART.
• until:Date, String, Object - The end date of the occurrences. String equivalent: UNTIL.
• intervalNumber - The time interval for the rule, e.g. every 3 days, or every 2 weeks. This depends on the repeat property. String equivalent: INTERVAL.

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

recurring: {
  repeat: 'daily',
  count: 5,
  interval: 2
}

recurring: 'FREQ=DAILY;COUNT=5;INTERVAL=2'

Examples

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

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.

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:

• <CalendarPrev /> - Previous button component, that navigates to the previous month.
• <CalendarNext /> - Next button component, that navigates to the next month.
• <CalendarToday /> - Today button component, that navigates to the current date.
• <CalendarNav /> - The title navigation button component, that opens the year/month navigation.

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

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

<Datepicker renderCalendarHeader={customWithNavButtons} />

Options

buttons: [
    'set',
    {
        text: 'Custom',
        icon: 'checkmark',
        cssClass: 'my-btn', 
        handler: function (event) {
            alert('Custom button clicked!');
        }
    },
    'cancel'
]

buttons: [
    'set',
    {
        text: 'Hide',
        handler: 'cancel',
        icon: 'close',
        cssClass: 'my-btn'
    }
]

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' } }
]

invalid: [
    // Passing exact dates and times
    new Date(2021, 1, 7), // Date object
    '2021-10-15T12:00', // ISO 8601 string
    moment("2020-12-25"), // moment object

    // Passing invalid ranges
    { 
      // ISO 8601 strings
      start: '2021-10-15T12:00',
      end: '2021-10-18T13:00', 
      title: 'Company 10th anniversary',
    },
    {
      // Date objects
      allDay: true,
      start: new Date(2021, 2, 7),
      end: new Date(2021, 2, 9),
      title: 'Conference for the whole team',
    },
    {
      // Time range with recurrence
      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'
      }
    }
];

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: [
  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 }
  }
]

const myCustomHeader = () => {
    return <>
        <CalendarPrev />
        <CalendarNext />
    </>
}

responsive: {
    small: {
        display: 'bottom'
    },
    custom: { // Custom breakpoint
        breakpoint: 600,
        display: 'center'
    },
    large: {
        display: 'anchored'
    }
}

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

Events

<mobiscroll.Datepicker
    onCancel={function (event, inst) {
    }}
/>

<mobiscroll.Datepicker
    onCellClick={function (event, inst) {
    }}
/>

<mobiscroll.Datepicker
    onCellHoverIn={function (event, inst) {
    }}
/>

<mobiscroll.Datepicker
    onCellHoverOut={function (event, inst) {
    }}
/>

<mobiscroll.Datepicker
    onChange={function (event, inst) {
    }}
/>

<mobiscroll.Datepicker
    onClose={function (event, inst) {
    }}
/>

<mobiscroll.Datepicker
    onDestroy={function (event, inst) {
    }}
/>

<mobiscroll.Datepicker
    onInit={function (event, inst) {
    }}
/>

<mobiscroll.Datepicker
    onLabelClick={function (event, inst) {
    }}
/>

<mobiscroll.Datepicker
    onOpen={function (event, inst) {
    }}
/>

<mobiscroll.Datepicker
    onPageChange={function (event, inst) {
    }}
/>

<mobiscroll.Datepicker
    onPageLoaded={function (event, inst) {
    }}
/>

<mobiscroll.Datepicker
    onPageLoading={function (event, inst) {
    }}
/>

<mobiscroll.Datepicker
    onPosition={function (event, inst) {
    }}
/>

Methods

mobiscrollInstance.close();

mobiscrollInstance.isVisible();

mobiscrollInstance.navigate(new Date(2016, 1, 1));

mobiscrollInstance.open();

mobiscrollInstance.position();

mobiscrollInstance.setActiveDate('start');

Localization

dateWheels: '|D M d|' // Will produce 'Sun Sep 9'
            

import { Eventcalendar, localeDe } from '@mobiscroll/react';

export function MyComponent() {
  return <Eventcalendar locale={localeDe} />;
}

import { Eventcalendar, locale } from '@mobiscroll/react';

export function MyComponent() {
  return <Eventcalendar locale={locale['de']} />;
}

timeWheels: '|h:mm A|' // Will produce '9:12 AM' 

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:

• Create custom themes using the theme builder - the custom themes can be also built using out theme builder, on a graphical user interface, without any coding, or the need for Sass support in your project.
• Create custom themes using Sass - use this, if you need multiple themes with different color variatons, in case you have pages with different colors, or you'd like to users to customize the colors of your app.
• Override the Sass color variables - the straightforward way to change the colors in one place throughout the application.

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"

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.