React Calendar Overview

The Ignite UI for React Calendar component is lightweight and easy to configure. It is used for showing dates and weekdays. It is also the best way for providing monthly or yearly views to end-users. The Ignite UI for React Calendar control lets you restrict the minimum and maximum date ranges that people can navigate through.

The Ignite UI for Ignite UI for React Calendar provides an easy and intuitive way for displaying date information. It packs different features like single or multiple date selection modes, highlight and select date range, keyboard navigation, enabling week numbers, size and spacing options, and more.

React Calendar Example

The following React IgrCalendar component example shows a basic calendar with a single day selection mode. See how it works or inspect the code behind.

How To Create a Calendar in React with Ignite UI

First, you need to the install the corresponding Ignite UI for React npm package by running the following command:

npm install igniteui-react

You will then need to import the Ignite UI for React IgrCalendar and its necessary CSS, like so:

import { IgrCalendar } from 'igniteui-react';
import 'igniteui-webcomponents/themes/light/bootstrap.css';

Before using the IgrCalendar, you need to register it as follows:

For a complete introduction to the Ignite UI for React, read the Getting Started topic.

The simplest way to start using the Ignite UI for React IgrCalendar is as follows:

<IgrCalendar />

Selection Modes

Users can choose from three different selection modes - single selection, multiple selection or range selection. By default, the Ignite UI for React IgrCalendar is using single selection mode but you can change it by setting the IgrCalendar.selection property as shown in this example.

<IgrCalendar selection="multiple" />

Range Selection

Following the same approach, we can switch IgrCalendar.selection to range mode:

<IgrCalendar selection="range" />

Active View and Date

The Ignite UI for React Calendar component allows you to switch between three different views: days, months and years. The IgrCalendar.activeView property of the component reflects the current view. By default, the Calendar displays the current date when loaded initially. You could modify this by setting the IgrCalendar.activeDate property. The IgrCalendar.activeDate property also reflects the changes of the currently visible date made by the end user.

Header Options

By default, the Ignite UI for React Calendar component renders a header area which contains information about the selected dates. You could hide the header by setting the IgrCalendar.hasHeader property to false. You could also configure vertical or horizontal orientation of the header using the IgrCalendar.headerOrientation property.

The Ignite UI for React Calendar component exposes a title slot which allows you to customize the title of the header.

When slotting content into the title slot, we recommend using a <span> element rather than heading elements (<h1>–<h6>). Heading elements carry built-in styling (such as font size, line height, and margins) that can interfere with the component’s intended typography and layout. Using a <span> gives you a neutral container that inherits the component’s styles cleanly.

<IgrCalendar selection="range" headerOrientation="vertical">
    <span slot="title">Trip dates</span>
</IgrCalendar>

The following sample demonstrates the above configuration:

Localization and Formatting

Due to their very nature, localization and formatting are essential to any calendar. In the Ignite UI for React IgrCalendar those are controlled and customized through the following properties - IgrCalendar.locale, IWorksheetCellFormat.formatOptions, IgrFieldPipeArgs.weekStart.

Let’s go ahead and try those along with other customizations. First thing we need to set is the IgrFieldPipeArgs.weekStart, which controls the starting day of the week. It defaults to Sunday, so we will set it to Monday. We will also customize the IWorksheetCellFormat.formatOptions property which specifies the options used to format the months and the weekdays in the Calendar views. Finally, we will set the IgrCalendar.locale property to a value, based on the user’s location choice:

<IgrRadioGroup alignment="horizontal" value={this.state.calendarLocale}>
    <IgrRadio name="lang" value="en" checked={true} onChange={this.onRadioChange}>
        <span>EN</span>
    </IgrRadio>
    <IgrRadio name="lang" value="de" onChange={this.onRadioChange}>
        <span>DE</span>
    </IgrRadio>
    <IgrRadio name="lang" value="fr" onChange={this.onRadioChange}>
        <span>FR</span>
    </IgrRadio>
    <IgrRadio name="lang" value="ar" onChange={this.onRadioChange}>
        <span>AR</span>
    </IgrRadio>
    <IgrRadio name="lang" value="ja" onChange={this.onRadioChange}>
        <span>JA</span>
    </IgrRadio>
</IgrRadioGroup>

<IgrCalendar weekStart='monday' formatOptions={this.state.calendarFormat}
    locale={this.state.calendarLocale}
    value={new Date()}/>

constructor(props: any) {
    super(props);
    this.onRadioChange = this.onRadioChange.bind(this);
    const formatOptions: IgrCalendarFormatOptions = {
        month: 'short',
        weekday: 'short',
    }
    this.state = { calendarLocale: "en", calendarFormat: formatOptions };
}

public onRadioChange(e: any) {
    if (e.detail.checked) {
        this.setState({ calendarLocale: e.detail.value });
    }
}

If everything went well, we should now have a Calendar with customized display, that also changes the locale representation, based on the user selection. Let’s have a look at it:

Disabled dates

In some cases you would want to have disabled dates in the Calendar which can’t be selected by the end user. This functionality is achieved by using the IgrCalendar.disabledDates property. The IgrCalendar.disabledDates property is an array of DateRangeDescriptor objects. Each descriptor has a Type and optionally a DateRange which is an array of Date objects.

These are the available options for the Type property:

• After - disables the dates after the first date in the DateRange
• Before - disables the dates before the first date in the DateRange
• Between - disables the dates between the first and the second date in the DateRange
• Specific - disables the dates specified in the DateRange array
• Weekdays - disables all weekdays
• Weekends - disables all weekends

Let’s create a sample that is disabling the dates between the 3rd and the 8th of the current month:

const today = new Date(Date.now());
const range = [
    new Date(today.getFullYear(), today.getMonth(), 3),
    new Date(today.getFullYear(), today.getMonth(), 8)
];

this.calendar.disabledDates = [{ type: DateRangeType.Between, dateRange: range }];

<IgrCalendar disabledDates={this.state.disabledDates}/>

const today = new Date();
const range = [
    new Date(today.getFullYear(), today.getMonth(), 3),
    new Date(today.getFullYear(), today.getMonth(), 8)
];
const desc: DateRangeDescriptor = {
    dateRange: range,
    type: DateRangeType.Specific,
}
const disabledDates = [desc];
this.state = { disabledDates };

These configurations should have the following result:

Special dates

The IgrCalendar.specialDates property is using almost the same configuration principles as the IgrCalendar.disabledDates. The special dates have a highlighted look and feel and unlike the disabled ones can be selected.

Let’s add some special dates to our Calendar. In order to do this, we will create a DateRangeDescriptor and pass the dates between the 3rd and the 8th of the current month:

const today = new Date();
const range = [
    new Date(today.getFullYear(), today.getMonth(), 3),
    new Date(today.getFullYear(), today.getMonth(), 8)
];

this.calendar.specialDates = [{ type: DateRangeType.Between, dateRange: range }];

<IgrCalendar specialDates={this.state.specialDates}/>

const today = new Date();
const range = [
    new Date(today.getFullYear(), today.getMonth(), 3),
    new Date(today.getFullYear(), today.getMonth(), 8)
]
const desc: DateRangeDescriptor = {
    dateRange: range,
    type: DateRangeType.Between,
}
const specialDates = [desc]
this.state = { specialDates };

The following demo illustrates a Calendar with a vacation request option:

Week numbers

You can use the IgrCalendar.showWeekNumbers property to show the week numbers of the Calendar component. You can do this by using its corresponding boolean attribute show-week-numbers like this:

<IgrCalendar showWeekNumbers={true} />

The following demo illustrates a Calendar with enabled week numbers:

Multiple Months

Using the IgrCalendar.visibleMonths property, you can display more than one month when the Calendar is in days view. When multiple months are displayed, you can configure whether you want to stack them vertically or horizontally by using the IgrCalendar.orientation property. By default, the IgrCalendar.orientation property is set to horizontal.

The Calendar displays leading and trailing dates from the previous and the next months. You could hide these dates by setting the IgrCalendar.hideOutsideDays property to true or using its corresponding boolean attribute HideOutsideDays.

<IgrCalendar visibleMonths={2} hideOutsideDays={true} />

The following sample demonstrates the multiple months configuration:

Size

You could control the size and spacing of the calendar inner elements using the --ig-size CSS variable. The default size of the component is large.

Events

The Calendar component emits the IgrCalendar.change event when the selected dates are changed by the end user. You can subscribe to the event like this:

<IgrCalendar onChange={this.onCalendarChange} />

public onCalendarChange(e: IgrComponentDataValueChangedEventArgs) {

}

Keyboard navigation

If you traverse the page using the TAB key you should keep in mind that based on W3 accessability recommendations the IgrCalendar introduces the following tab stops:

• Month selection button
• Year selection button
• Previous button
• Next button
• Active date element

When a day/month/year in the IgrCalendar component is focused, use:

• PAGE UP key to move to the previous month/year/years page.
• PAGE DOWN key to move to the next month/year/years page.
• HOME key to focus the first day of the current month/first month in view/first year in view.
• END key to focus the last day of the current month/last month in view/last year in view.
• Arrow keys to navigate through the days/months/years. Navigating before the first item and after the last item will switch the view to the next/previous month/year/years page.

When a day inside the days view is focused, use:

• SHIFT + PAGE UP keys to move to the previous year.
• SHIFT + PAGE DOWN keys to move to the next year.
• SPACE or ENTER key to select the currently focused day.

When a month inside the months view is focused, use:

• SPACE or ENTER key to change the IgrCalendar.activeDate to the currently focused month and switch to days view.

When an year inside the years view is focused, use:

• SPACE or ENTER key to change the IgrCalendar.activeDate to the currently focused year and switch to months view.

When the previous or the next buttons (in the subheader) are focused, use:

• SPACE or ENTER key to switch to the previous/next month/year/years page.

When the month button (in the subheader) is focused, use:

• SPACE or ENTER key to switch to months view.

When the year button (in the subheader) is focused, use:

• SPACE or ENTER key to switch to years view.

Styling

The IgrCalendar component exposes CSS parts for almost all of its inner elements. The following table lists all of the exposed CSS parts:

Using these CSS parts we can customize thе appearance of the IgrCalendar component like this:

igc-calendar::part(date-inner selected),
igc-calendar::part(month-inner selected),
igc-calendar::part(year-inner selected),
igc-calendar::part(month-inner selected):focus,
igc-calendar::part(year-inner selected):focus {
  background: var(--ig-primary-500);
  border-color: var(--ig-primary-800);
}

igc-calendar::part(date-inner selected):hover,
igc-calendar::part(month-inner selected):hover,
igc-calendar::part(year-inner selected):hover {
  background: var(--ig-primary-500);
  border-color: var(--ig-primary-800);
}

igc-calendar::part(label),
igc-calendar::part(navigation-button),
igc-calendar::part(months-navigation):hover,
igc-calendar::part(months-navigation):focus,
igc-calendar::part(years-navigation):hover,
igc-calendar::part(years-navigation):focus {
  color: var(--ig-primary-300);
}

igc-calendar::part(navigation-button):hover,
igc-calendar::part(navigation-button):focus {
  color: var(--ig-primary-800);
}

The following sample demonstrates the above CSS configuration:

API References

Additional Resources

• Ignite UI for React Forums
• Ignite UI for React GitHub