igxCalendar Component

The igxCalendar provides a way for the user to select date(s). A walkthrough of how to get started can be found here

Dependencies

In order to be able to use igxCalendar you should keep in mind that it is dependent on BrowserAnimationsModule, which must be imported only once in your application's AppModule, for example:

import { BrowserAnimationsModule } from '@angular/platform-browser/animations';
@NgModule({
	imports: [
        BrowserAnimationsModule,
        ...
	]
})
export class AppModule {
}

Also the igxCalendar uses the Intl WebAPI for localization and formatting of dates. Consider using the appropriate polyfills if your target platform does not support them.

Usage

Be sure to consult the API below for additional information.

Importing the calendar in your application

import { IgxCalendarComponent } from "igniteui-angular/main";

or

import { IgxCalendarComponent } from "igniteui-angular/calendar";

Instantiate a calendar component in single selection mode displaying the current month.

<igx-calendar></igx-calendar>

A range selection calendar with first day of week set to Monday and an event handler when selection is done.

<igx-calendar [weekStart]="1" selection="range" (selected)="eventHandler($event)"></igx-calendar>

A multiple selection calendar with different locale and templating for the subheader.

<igx-calendar locale="ja-JP" selection="multi">
        <ng-template igxCalendarSubheader let-format>
                <span (click)="format.yearView()">{{ format.year.combined }}</span>
                <span (click)="format.monthView()">{{ format.month.combined | titlecase }}</span>
        </ng-template>
</igx-calendar>

A calendar displaying more than one month in the view and hiding the days that are outside of the current month

<igx-calendar monthsViewNumber="2" [hideOutsideDays]="'true'">
</igx-calendar>

The igxCalendar implements the ControlValueAccessor interface, providing two-way data-binding and the expected behavior when used both in Template-driven or Reactive Forms.

Keyboard navigation

When the igxCalendar component is focused:

• PageUp will move to the previous month.
• PageDown will move to the next month.
• Shift + PageUp will move to the previous year.
• Shift + PageDown will move to the next year.
• Home will focus the first day of the current month (or first month if more months are displayed) hat is into view.
• End will focus the last day of the current month ((or last month if more months are displayed)) that is into view.
• Tab will navigate through the subheader buttons;

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

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

When months button (in the subheader) is focused:

• Space or Enter will open the months view.

When year button (in the subheader) is focused:

• Space or Enter will open the decade view.

When a day inside the current month is focused:

• Arrow keys will navigate through the days.
• Arrow keys will allow navigation to previous/next month as well.
• Enter will select the currently focused day.
• When more than one month view is displayed, navigating with the arrow keys should move to next/previous month after navigating from first/last day in current month.

When a month inside the months view is focused:

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

When an year inside the decade view is focused:

• Arrow keys will navigate through the years.
• Enter will select the currently focused year and close the view.

API Summary

Inputs

• id: string

Unique identifier of the component. If not provided it will be automatically generated.

• vertical: boolean

Controls the layout of the calendar component. When vertical is set to true the calendar header will be rendered to the side of the calendar body. Defaults to false.

• weekStart: WEEKDAYS | number

Controls the starting day of the weeek for the calendar. Defaults to Sunday.

• locale: string

Controls the locale used for formatting and displaying the dates in the calendar. The expected string should be a BCP 47 language tag. The default value is en.

• selection: CalendarSelection | string

Controls the type of selection in the calendar. Defaults to CalendarSelection.SINGLE which is equivalent to the string single. Changing the selection type during 'runtime' will clear the previously selected values in the calendar. The calendar header will not be rendered when the selection is either multi or range.

• viewDate: Date

Controls the year/month that will be presented in the default view when the calendar renders. By default it is the first day of the current year/month.

• value: Date | Date[]

Gets and sets the selected date(s) in the calendar component. Both multi and range selection accepts single date values but they always return an array of date objects.

• formatOptions: Object

Controls the date-time components to use in formatted output, and their desired representations. Consult this for additional information on the available options.

The defaul values are listed below.

{ day: 'numeric', month: 'short', weekday: 'short', year: 'numeric' }

• formatViews: Object

Controls whether the date parts in the different calendar views should be formatted according to the provided locale and formatOptions.

The default values are listed below.

{ day: false, month: true, year: false }

• monthViewsNumber: number Controls the number of month views displayed. Default is 1.

• hideOusideDays: boolean Controls the visibility of the dates that do not belong to the current month.

Outputs

• selected(): Date | Date[]

Event fired when a value is selected through UI interaction. Emits the selected value (depending on the type of selection).

• viewDateChanged(): IViewDateChangeEventArgs

Event fired after the month/year presented in the view is changed. Emits an object containing the previous and current value of the viewDate property.

• activeViewChanged(): CalendarView

Event fired after the active view is changed. Emits an CalendarView enum, indicating the activeView property value.

Methods

• selectedDate(value: Date | Date[]): void

Sets a new value for the calendar component. Does not trigger selected event.

Templating

The igxCalendar supports templating of its header and subheader parts. Just decorate a ng-template inside the calendar with igxCalendarHeader or igxCalendarSubheader directive and use the context returned to customize the way the date is displayed.

The template decorated with the igxCalendarHeader directive is rendered only when the calendar selection is set to single. The igxCalendarSubheader is available in all selection modes.

Example:

<igx-calendar>
        <ng-template igxCalendarHeader let-parts>
                ...
        </ng-template>
        <ng-template igxCalendarSubheader let-parts>
        <!-- Let's change the default representation to YYYY-MM -->
                <span class="date__el" (click)="parts.monthView()">
                        {{ parts.month.combined }}
                </span>
                <span class="date__el" (click)="parts.yearView()">
                        {{ parts.year.combined }}
                </span>
        </ng-template>
</igx-calendar>

Template context

Name	Type	Description
date	Date	The date object in the context of the template. See * below for details.
full	string	The full date representation returned after applying the formatOptions.
monthView	Function	A function which when called puts the calendar in month view.
yearView	Function	A function which when called puts the calendar in year view.
era	Object	The era date component (if applicable) formatted to the supplied locale.
year	Object	The year date component (if applicable) formatted to the supplied locale.
month	Object	The month date component (if applicable) formatted to the supplied locale.
day	Object	The day date component (if applicable) formatted to the supplied locale.
weekday	Object	The weekday date component (if applicable) formatted to the supplied locale.

* In the igxCalendarHeader context this is either the current date or the current selection of the calendar. In the igxCalendarSubheaderContext this is the same as the viewDate

NOTE: All of the date components (year, month, etc.) are objects with the structure

{
        value: string;
        literal: string;
        combined: string;
}

where value is the locale string representation of the date component, literal is the locale string separator (if any), and combined is as the name suggests the combined output of the two.

NOTE 2: Mind that both in Internet Explorer and Edge all of the date parts will be empty strings as both browsers don't implement the Intl API providing this functionality.