Angular Calendar Component Overview

    Angular Calendar is a UI component used for displaying dates and days in an app. Supporting different features, it enables users to easily manage calendar functionalities, drag and create events in a calendar, navigate to a preferred date in it, and show events in an Angular calendar month view, week view, or day view in a single click.

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

    Angular Calendar Example

    We created the following Angular Calendar example using the Ignite UI for Angular Calendar package. It quickly shows how a basic calendar looks and feels like, how users can choose and highlight a single date, and how to move back and forth to a specific date.

    Getting Started with Ignite UI for Angular Calendar

    To get started with the Ignite UI for Angular Calendar component, first you need to install Ignite UI for Angular. In an existing Angular application, type the following command:

    ng add igniteui-angular

    For a complete introduction to the Ignite UI for Angular, read the getting started topic.

    The next step is to import the IgxCalendarModule in your app.module.ts file.

    Note

    The IgxCalendarComponent also depends on the BrowserAnimationsModule and optionally 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';
// import { IgxCalendarModule } from '@infragistics/igniteui-angular'; for licensed package

@NgModule({
    ...
    imports: [..., BrowserAnimationsModule, HammerModule, IgxCalendarModule],
    ...
})
export class AppModule {}

    Alternatively, as of 16.0.0 you can import the IgxCalendarComponent as a standalone dependency, or use the IGX_CALENDAR_DIRECTIVES token to import the component and all of its supporting components and directives.

    // home.component.ts

import { HammerModule } from '@angular/platform-browser';
import { BrowserAnimationsModule } from '@angular/platform-browser/animations';
import { IGX_CALENDAR_DIRECTIVES } from 'igniteui-angular';
// import { IGX_CALENDAR_DIRECTIVES } from '@infragistics/igniteui-angular'; for licensed package

@Component({
    selector: 'app-home',
    template: '<igx-calendar></igx-calendar>',
    styleUrls: ['home.component.scss'],
    standalone: true,
    imports: [BrowserAnimationsModule, HammerModule, IGX_CALENDAR_DIRECTIVES]
    /* or imports: [BrowserAnimationsModule, HammerModule, IgxCalendarComponent] */
})
export class HomeComponent {}

    Now that you have the Ignite UI for Angular Calendar module or directives imported, you can start using the igx-calendar component.

    Note

    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.

    Using the Angular Calendar

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

    Angular Calendar Multiselect

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

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

    Angular Calendar Range Picker

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

    How to Disable Dates In Angular Calendar

    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.Between, dateRange: this.range }];
    }
}

    These configurations 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"
    (selected)="selectPTOdays($event)">
</igx-calendar>
<igx-dialog #alert title="Request Time Off"
    leftButtonLabel="OK"
    (leftButtonSelect)="alert.close()">
</igx-dialog>
<button igxButton="contained" (click)="submitPTOdays($event)">Submit Request</button>

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

    Week numbers

    You can now use showWeekNumbers input to show the week numbers for both Calendar and DatePicker components.

    
<!-- app.component.html -->
<igx-calendar selection="multi" [showWeekNumbers]="true"></igx-calendar>

    The following demo illustrates a calendar with enabled week numbers:

    Calendar Events

    Let's explore the events emitted by the calendar:

    • selected - emitted when selecting date(s) in the calendar.
    • viewDateChanged - emitted every time when the presented month/year is changed - for example after navigating to the next or previous month.
    • activeViewChanged - emitted after the active view is changed - for example after the user has clicked on the month or year section in the header.
    <!-- app.component.html -->
<igx-calendar #calendar
    (selected)="onSelection($event)"
    (viewDateChanged)="viewDateChanged($event)"
    (activeViewChanged)="activeViewChanged($event)">
</igx-calendar>

    The selected event is suitable to build input validation logic. Use the code from below to alert the user if selection exceeds 5 days, and then reset the selection:

    // app.component.ts
...
public onSelection(dates: Date[]) {
    if (dates.length > 5) {
        this.calendar.selectedDates = [];
        // alert the user
    }
}
public viewDateChanged(event: IViewDateChangeEventArgs) {
    // use event.previousValue to get previous month/year that was presented.
    // use event.currentValue to get current month/year that is presented.
}

public activeViewChanged(event: CalendarView) {
    // use CalendarView[event] to get the current active view (DEFAULT, YEAR or DECADE)
}

    Use the demo below to play around (change selection, navigate through months and years) and see the events logged real time:

    Angular Calendar Views

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

    Keyboard navigation

    If you traverse the page using Tab key you should keep in mind that based on W3 accessibility recommendations the igxCalendarComponent now introduces the following tab stops:

    • Previous month button
    • Month selection button
    • Year selection button
    • Next month button
    • Selected date, Current date, First focusable (not disabled) date in the days view

    In an Angular Calendar that contains more than one selected dates, only the first date will be introduced as a tab stop. For example, when an Angular Calendar multi-select is enabled and you have selected the dates: 13/10/2020, 17/10/2020 and 21/10/2020 only 13/10/2020 will be accessible during tab navigation; in an Angular Calendar Range Picker, only the first date of the selected range will be part of the page tab sequence.

    Note

    Behavioral change, from v10.2.0 - Tab key navigation in the days view is no longer available. In order to navigate between the dates in the date view you should use the arrow keys.

    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

    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. Note: The disabled dates will be skipped.
    • Focus will be persisted on the current month that is in the view, while navigation from/to the last day/first day of the month.
    • THe kb navigation would be continuous, which means that it will go through all months while navigating with the arrows.
    • Use 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 up and Arrow down 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

    Multi-view 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.

    Calendar Orientation

    The orientation settings allows users to choose how the header and the view of the calendar are displayed.

    Header Orientation Options

    You can change the header orientation to place the header of the calendar to be either horizontal(above the calendar view) or vertical(on the side of the calendar view). To do that, use the [headerOrientation] property, setting it respectively to horizontal or vertical

    View Orientation Options

    You can set the view orientation to place the months in the calendar either horizontally(side by side) or vertically(above one another). To do that, use the [orientation] property, setting it respectively to horizontal or vertical.

    Note

    You need at least two month view calendar to see that property working.

    <igx-calendar [monthsViewNumber]="2" [headerOrientation]="headerOrientation" [orientation]="orientation"></igx-calendar>

    const orientations = ["horizontal", "vertical"] as const;
type Orientation = (typeof orientations)[number];

export class CalendarSample9Component {
    protected orientations = Array.from(orientations, (o) => o);
    protected headerOrientation: Orientation = "horizontal";
    protected orientation: Orientation = "horizontal";

    protected setHeaderOrientation(orientation: Orientation) {
        this.headerOrientation = orientation;
    }

    protected setOrientation(orientation: Orientation) {
        this.orientation = orientation;
    }
}

    Styling

    Calendar Theme Property Map

    When you modify the $header-background and $content-background properties, all related theme properties are automatically adjusted to ensure your calendar component is styled consistently. See the tables below for a detailed overview of which theme properties are affected.

    Primary Property Dependent Property Description
    $header-background
    		 $header-foreground Text color for the calendar header
    $picker-hover-foregroundPicker hover foreground
    $picker-focus-foregroundPicker focus foreground
    $navigation-hover-colorHover color for navigation
    $navigation-focus-colorFocus color for navigation
    $date-selected-backgroundBackground for selected dates
    $date-selected-current-backgroundSelected current date background
    $date-selected-foregroundForeground for selected dates
    $date-selected-current-foregroundForeground for selected current date
    $date-selected-current-border-colorBorder color for selected current date
    $date-selected-special-border-colorBorder color for selected special dates
    $ym-selected-backgroundYear/month selected background
    $ym-selected-hover-backgroundHover background for year/month selected date
    $ym-selected-current-backgroundCurrent selected year/month background
    $ym-selected-current-hover-backgroundHover background for current selected year/month
    $ym-selected-foregroundForeground for selected year/month
    $ym-selected-hover-foregroundHover foreground for selected year/month
    $ym-selected-current-foregroundForeground for current selected year/month
    $ym-selected-current-hover-foregroundHover foreground for current selected year/month
    $content-background
    		 $content-foreground Text and icon color inside calendar content area
    $weekend-colorColor for weekend dates
    $inactive-colorColor for dates outside active range
    $weekday-colorColor for weekday labels
    $picker-backgroundPicker background
    $date-hover-backgroundBackground for hovered dates
    $date-hover-foregroundForeground for hovered dates
    $date-focus-backgroundBackground for focused dates
    $date-focus-foregroundForeground for focused dates
    $date-current-backgroundBackground for the current date
    $date-current-foregroundForeground for the current date
    $date-current-border-colorBorder color for the current date
    $ym-current-backgroundYear/month current background
    $ym-current-hover-backgroundHover background for current year/month
    $ym-current-foregroundForeground for current year/month
    $ym-current-hover-foregroundHover foreground for current year/month
    $date-selected-range-backgroundSelected range background
    $date-selected-range-foregroundForeground for selected date ranges
    $date-selected-current-range-backgroundBackground for selected current date ranges
    $date-selected-current-range-hover-backgroundHover background for selected current date ranges
    $date-selected-current-range-focus-backgroundFocus background for selected current date ranges
    $date-selected-current-range-foregroundForeground for selected current date ranges
    $date-special-foregroundForeground for special dates
    $date-special-border-colorBorder color for special dates
    $date-special-hover-border-colorHover border color for special dates
    $date-special-focus-foregroundFocus foreground for special dates
    $date-special-range-foregroundForeground for special date ranges
    $date-special-range-border-colorBorder color for special date ranges
    $date-special-range-hover-backgroundHover background for special date ranges
    $date-selected-special-border-colorBorder color for selected special dates
    $date-selected-special-hover-border-colorHover border color for selected special dates
    $date-selected-special-focus-border-colorFocus border color for selected special dates
    $date-disabled-foregroundForeground for disabled dates
    $date-disabled-range-foregroundForeground for disabled ranges
    $date-border-radius
    		 $date-range-border-radius Controls the border radius for date ranges.
    $date-current-border-radiusControls the border radius for the current date.
    $date-special-border-radiusControls the border radius for special dates.
    $date-border-radiusIf not specified and $date-range-border-radius is set, uses the value of $date-range-border-radius.
    Primary Property Dependent Property Description
    $header-background
    		 $header-foreground Text color for the calendar header
    $picker-hover-foregroundPicker hover foreground
    $picker-focus-foregroundPicker focus foreground
    $date-current-backgroundBackground for the current date
    $date-current-hover-foregroundHover foreground for the current date
    $date-current-focus-foregroundFocus foreground for the current date
    $date-selected-current-foregroundForeground for the currently selected date
    $date-selected-current-hover-foregroundHover foreground for the currently selected date
    $date-selected-current-focus-foregroundFocus foreground for the currently selected date
    $date-special-border-colorBorder color for special dates
    $date-special-hover-foregroundHover foreground for special dates
    $content-background
    		 $content-foreground Text and icon color inside calendar content area
    $weekend-colorColor for weekend dates
    $inactive-colorColor for dates outside active range
    $weekday-colorColor for weekday labels
    $picker-backgroundPicker background
    $date-hover-backgroundBackground for hovered dates
    $date-hover-foregroundForeground for hovered dates
    $date-focus-backgroundBackground for focused dates
    $date-focus-foregroundForeground for focused dates
    $date-selected-backgroundBackground for selected dates
    $date-selected-hover-backgroundHover background for selected dates
    $date-selected-focus-backgroundFocus background for selected dates
    $date-selected-foregroundForeground for selected dates
    $date-selected-hover-foregroundHover foreground for selected dates
    $date-selected-focus-foregroundFocus foreground for selected dates
    $date-selected-range-backgroundBackground for selected date ranges
    $date-selected-range-foregroundForeground for selected date ranges
    $date-disabled-foregroundForeground for disabled dates
    $date-disabled-range-foregroundForeground for disabled ranges
    $date-border-radius
    		 $date-range-border-radius Controls the border radius for date ranges.
    $date-current-border-radiusControls the border radius for the current date.
    $date-special-border-radiusControls the border radius for special dates.
    $date-border-radiusIf not specified and $date-range-border-radius is set, uses the value of $date-range-border-radius.
    Primary Property Dependent Property Description
    $header-background
    		 $header-foreground Text color for the calendar header
    $picker-backgroundPicker background
    $picker-hover-foregroundPicker hover foreground
    $weekday-colorColor for weekday labels
    $picker-focus-foregroundPicker focus foreground
    $date-special-border-colorBorder color for special dates
    $date-special-focus-foregroundFocus foreground for special dates
    $content-background
    		 $content-foreground Text and icon color inside calendar content area
    $weekend-colorColor for weekend dates
    $inactive-colorColor for dates outside active range
    $weekday-colorColor for weekday labels
    $date-hover-backgroundBackground for hovered dates
    $date-hover-foregroundForeground for hovered dates
    $date-focus-backgroundBackground for focused dates
    $date-focus-foregroundForeground for focused dates
    $date-current-backgroundBackground for the current date
    $date-current-foregroundForeground for the current date
    $date-current-border-colorBorder color for the current date
    $date-selected-backgroundBackground for selected dates
    $date-selected-current-backgroundBackground for the currently selected date
    $date-selected-foregroundForeground for selected dates
    $date-selected-current-foregroundForeground for the currently selected date
    $date-selected-special-border-colorBorder color for selected special dates
    $date-selected-special-hover-border-colorHover border color for selected special dates
    $date-selected-special-focus-border-colorFocus border color for selected special dates
    $date-selected-range-backgroundBackground for selected date ranges
    $date-selected-range-foregroundForeground for selected date ranges
    $date-disabled-foregroundForeground for disabled dates
    $date-disabled-range-foregroundForeground for disabled ranges
    $date-border-radius
    		 $date-range-border-radius Controls the border radius for date ranges.
    $date-current-border-radiusControls the border radius for the current date.
    $date-special-border-radiusControls the border radius for special dates.
    $date-border-radiusIf not specified and $date-range-border-radius is set, uses the value of $date-range-border-radius.
    Primary Property Dependent Property Description
    $header-background
    		 $header-foreground Text color for the calendar header
    $picker-backgroundPicker background
    $picker-hover-foregroundPicker hover foreground
    $picker-focus-foregroundPicker focus foreground
    $navigation-hover-colorNavigation hover color
    $navigation-focus-colorNavigation focus color
    $date-current-backgroundBackground for the current date
    $date-current-border-colorBorder color for the current date
    $date-current-hover-backgroundBackground for hovered current date
    $date-current-hover-border-colorBorder color for hovered current date
    $date-current-focus-backgroundBackground for focused current date
    $date-current-focus-border-colorBorder color for focused current date
    $date-current-foregroundForeground for the current date
    $date-current-hover-foregroundForeground for hovered current date
    $date-current-focus-foregroundForeground for focused current date
    $date-selected-current-border-colorBorder color for the currently selected date
    $content-background
    		 $content-foreground Text and icon color inside calendar content area
    $weekend-colorColor for weekend dates
    $inactive-colorColor for dates outside active range
    $weekday-colorColor for weekday labels
    $date-hover-backgroundBackground for hovered dates
    $date-hover-foregroundForeground for hovered dates
    $date-focus-backgroundBackground for focused dates
    $date-focus-foregroundForeground for focused dates
    $date-selected-backgroundBackground for selected dates
    $date-selected-current-backgroundBackground for the currently selected date
    $date-selected-foregroundForeground for selected dates
    $date-selected-current-foregroundForeground for the currently selected date
    $date-selected-current-border-colorBorder color for the currently selected date
    $date-selected-range-backgroundBackground for selected date ranges
    $date-selected-range-foregroundForeground for selected date ranges
    $date-selected-current-range-backgroundBackground for the current date in a selected range
    $date-selected-current-range-hover-backgroundHover background for the current date in a selected range
    $date-selected-current-range-foregroundForeground for the current date in a selected range
    $date-disabled-foregroundForeground for disabled dates
    $date-disabled-range-foregroundForeground for disabled ranges
    $date-border-radius
    		 $date-range-border-radius Controls the border radius for date ranges.
    $date-current-border-radiusControls the border radius for the current date.
    $date-special-border-radiusControls the border radius for special dates.
    $date-border-radiusIf not specified and $date-range-border-radius is set, uses the value of $date-range-border-radius.

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

    @use "igniteui-angular/theming" as *;

// IMPORTANT: Prior to Ignite UI for Angular version 13 use:
// @import '~igniteui-angular/lib/core/styles/themes/index';

    Following the simplest approach, we create a new theme that extends the calendar-theme and by specifying just the $header-background and $content-background parameters, the theme will automatically compute appropriate state colors and contrast foregrounds. Of course, you're still free to override any of the theme parameters with custom values if needed.

    $custom-calendar-theme: calendar-theme(
  $header-background: #ecaa53,
  $content-background: #011627,
);

    The last step is to pass the custom calendar theme:

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

    Styling with Tailwind

    You can style the calendar using our custom Tailwind utility classes. Make sure to set up Tailwind first.

    Along with the tailwind import in your global stylesheet, you can apply the desired theme utilities as follows:

    @import "tailwindcss";
...
@use 'igniteui-theming/tailwind/utilities/material.css';

    The utility file includes both light and dark theme variants.

    • Use light-* classes for the light theme.
    • Use dark-* classes for the dark theme.
    • Append the component name after the prefix, e.g., light-calendar, dark-calendar.

    Once applied, these classes enable dynamic theme calculations. From there, you can override the generated CSS variables using arbitrary properties. After the colon, provide any valid CSS color format (HEX, CSS variable, RGB, etc.).

    You can find the full list of properties in the calendar-theme. The syntax is as follows:

    <igx-calendar
class="!light-calendar
![--header-background:#4F6A5A]
![--content-background:#A3C7B2]"
[weekStart]="1">
</igx-calendar>
    Note

    The exclamation mark(!) is required to ensure the utility class takes precedence. Tailwind applies styles in layers, and without marking these styles as important, they will get overridden by the component’s default theme.

    At the end your calendar should look like this:

    API References

    Additional Resources

    Our community is active and always welcoming to new ideas.