Calendar

The Ignite UI for Angular Calendar component, developed as a native Angular component, provides easy and intuitive ways to display date information. Users can choose from three different selection modes - a single selection, a multi selection or a range selection.

Demo

Usage

First Steps

To get started with the Calendar component, first you need to import the IgxCalendarModule in the app.module.ts file.

Note that the IgxCalendar also depends on the BrowserAnimationsModule and the HammerModule for touch interactions, so they need to be added to the AppModule as well:

// app.module.ts
...
import { HammerModule } from "@angular/platform-browser";
import { BrowserAnimationsModule } from '@angular/platform-browser/animations';
import { IgxCalendarModule } from 'igniteui-angular';
@NgModule({
    ...
    imports: [..., BrowserAnimationsModule, HammerModule, IgxCalendarModule],
    ...
})
export class AppModule {}
Warning

The IgxCalendarComponent uses the Intl Web API for localization and formatting of dates. Consider using appropriate polyfills if your target platform does not support them.

Single Selection Calendar

Instantiating the IgxCalendarComponent is as easy as placing its selector element in the template. This will display the current month in the single selection calendar mode.

<!-- app.component.html -->
<!-- Single selection mode -->
<igx-calendar></igx-calendar>

Examples

Multi Selection

We can easily change the default mode using the selection property:

<!-- app.component.html -->
<!-- Multi selection mode -->
<igx-calendar selection="multi"></igx-calendar>

Range Selection

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

<!-- app.component.html -->
<!-- Range selection mode -->
<igx-calendar selection="range"></igx-calendar>
Note

Notice that the calendar header is not rendered when the selection is either multi or range.

Localization and Formatting

Due to their very nature, localization and formatting are essential to any calendar. In the IgxCalendarComponent those are controlled and customized through the following properties - locale, formatOptions, formatViews, weekStart.

Let's go ahead and try those along with other customizations from the IgxCalendarComponent API. First thing we need to set is the weekStart, which controls the starting day of the week. It defaults to 0, which corresponds to Sunday, so we will set a value of 1 for Monday. In the markup below we are also binding the formatOptions and formatViews properties to customize the display formatting. Finally, we are binding the locale property to a value, based on the user's location choice:

<!-- app.component.html -->
<igx-select #select [(ngModel)]="locale">
    <igx-select-item *ngFor="let locale of locales" [value]="locale">
        {{ locale }}
    </igx-select-item>
</igx-select>

<igx-calendar #calendar
    [weekStart]="1"
    [locale]="locale"
    [formatOptions]="formatOptions"
    [formatViews]="formatViews">
</igx-calendar>

All property values should be set in the AppCоmponent file:

// app.component.ts
@ViewChild('calendar', { read: IgxCalendarComponent }) public calendar: IgxCalendarComponent;

public formatOptions: any;
public formatViews: any;
public locales = ["EN", "DE", "FR", "AR", "ZH"];
public locale = "EN";

public ngOnInit() {
    this.formatOptions = { day: "2-digit", month: "long", weekday: "long", year: "numeric" };
    this.formatViews = { day: true, month: true, year: true };
}

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

Events

Let's build on top of that sample a bit. We will require the user to enter a date range that does not exceed 5 days. We need to change the selection mode of the calendar to "range" and prompt the user to correct the selection, if the range is not valid. In order to do this, we will use the onSelection event:

<!-- app.component.html -->
<igx-calendar #calendar
    ...
    selection="range"
    (onSelection)="verifyRange($event)">
</igx-calendar>

The value passed in the onSelection event is the collection of dates selected, so we can read its length and base our logic upon it. While alerting the user for an invalid selection, we will also reset the selection to contain only the first date from the range using the selectDate method:

// app.component.ts
...
public verifyRange(dates: Date[]) {
    if (dates.length > 5) {
        this.calendar.selectDate(dates[0]);
        this.dialog.open();
    }
}

In the following demo, an alert will be displayed, if the selected range exceeds 5 days. Let's try this out by playing around with different ranges:

Disabled dates

This section demonstrates the usage of disabledDates functionality. For this purpose, different single dates or ranges can be added to an array and then passed to the disabledDates descriptor.

The DateRangeType is used to specify a range that is going to be disabled.

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

export class CalendarSample6Component {
    @ViewChild("calendar") public calendar: IgxCalendarComponent;
    public today = new Date(Date.now());
    public range = [
        new Date(this.today.getFullYear(), this.today.getMonth(), 3),
        new Date(this.today.getFullYear(), this.today.getMonth(), 8)
    ];

    public ngOnInit() {
        this.calendar.disabledDates = [{ type: DateRangeType.Specific, dateRange: this.range }];
    }
}

These configurions should have the following result:

Special dates

The specialDates feature is using almost the same configuration principles as the disabledDates. The ability to select and focus specialDates is what differs them from the disabled ones.

Let's add some specialDates to our igxCalendar. In order to do this, we have to create a DateRangeDescriptor item of type DateRangeType.Specific and pass an array of dates as a dateRange:

export class CalendarSample7Component {
    @ViewChild("calendar", { static: true })
    public calendar: IgxCalendarComponent;
    @ViewChild("alert", { static: true })
    public dialog: IgxDialogComponent;
    public range = [];

    public selectPTOdays(dates: Date[]) {
        this.range = dates;
    }

    public submitPTOdays(eventArgs) {
        this.calendar.specialDates =
            [{ type: DateRangeType.Specific, dateRange: this.range }];

        this.range.forEach((item) => {
            this.calendar.selectDate(item);
        });

        ...
    }
}
 <igx-calendar #calendar weekStart="1"
               selection="multi" 
               (onSelection)="selectPTOdays($event)">
</igx-calendar>
<igx-dialog #alert title="Request Time Off" 
            leftButtonLabel="OK" 
            (onLeftButtonSelect)="alert.close()">
</igx-dialog>
<button igxButton="raised" (click)="submitPTOdays($event)">Submit Request</button>

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

Views

There are separate views provided by the IgxCalendarModule that can be used independently:

Keyboard navigation

When the igxCalendar component is focused, use:

  • PageUp key to move to the previous month,
  • PageDown key to move to the next month,
  • Shift + PageUp keys to move to the previous year,
  • Shift + PageDown keys to move to the next year,
  • Home key to focus the first day of the current month or first month in view
  • End key to focus the last day of the current month or last month in view
  • Tab key to navigate through the subheader buttons;

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

  • Space or Enter key to scroll into view the next or previous month.

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

  • Space or Enter key to open the months view.

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

  • Space or Enter key to open the decade view.

When a day inside the current month is focused, use:

  • Arrow keys to navigate through the days,
  • Arrow keys to navigate to previous/next month as well,
  • Navigating next from last day in current month or previous from first day in current month, will move focus to next/previos month that is in view.
  • Navigating next from last day in last visible current month or previous from first day in first current month, will change the months in view.
  • Enter key to select the currently focused day.

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

  • Arrow keys to navigate through the months,
  • Home key to focus the first month inside the months view,
  • End key to focus the last month inside the months view,
  • Enter key to select the currently focused month and close the view.

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

  • Arrow keys to navigate through the years,
  • Enter key to select the currently focused year and close the view.
Note

Following version 8.2.0, keyboard navigation will not focus days that are outside of current month, but will rather change the month in view.

Multi View Calendar

Multiview calendar supports all three types of selection. Use the monthsViewNumber input to set the number of displayed months, which will be shown horizontally in a flex container. There is no limit on the max value set. While using a multi view calendar, you may want to hide the days that do not belong to the current month. You are able to do it with the hideOutsideDays property. Keyboard navigation moves to next/previous months when those are in view.

Styling

To get started with styling the calendar, we need to import the index file, where all the theme functions and component mixins live:

@import '~igniteui-angular/lib/core/styles/themes/index';

Following the simplest approach, we create a new theme that extends the igx-calendar-theme and accepts some of the default theme's parameters.

$custom-calendar-theme: igx-calendar-theme(
  $header-background: #345779,
  $content-background: #fdfdfd,
  $header-text-color: #ffffff,
  $date-current-text-color: #2dabe8,
  $picker-arrow-color: #2dabe8,
  $date-selected-text-color: #fdfdfd,
  $date-current-bg-color: #fdfdfd,
  $picker-arrow-hover-color:  #345779,
  $year-current-text-color: #2dabe8,
  $year-hover-text-color: #2dabe8,
  $month-current-text-color: #2dabe8,
  $month-hover-text-color: #2dabe8,
  $picker-text-color: #2dabe8,
  $picker-text-hover-color:  #345779
);

Using CSS variables

The last step is to pass the custom calendar theme:

 @include igx-css-vars($custom-calendar-theme);

Using Theme Overrides

In order to style components for older browsers, like Internet Explorer 11, we have to use a different approach, since it doesn't support CSS variables.

If the component is using the Emulated ViewEncapsulation, it is necessary to penetrate this encapsulation using ::ng-deep. To prevent the custom theme to leak into other components, be sure to include the :host selector before ::ng-deep:

:host {
 ::ng-deep {
   @include igx-calendar($custom-calendar-theme);
 }
}

API References

Additional Resources

Our community is active and always welcoming to new ideas.