diff --git a/docs/angular/src/content/en/components/avatar.mdx b/docs/angular/src/content/en/components/avatar.mdx index a362e26b4d..dad9c74cf5 100644 --- a/docs/angular/src/content/en/components/avatar.mdx +++ b/docs/angular/src/content/en/components/avatar.mdx @@ -1,215 +1,214 @@ --- title: Angular Avatar Component – Ignite UI for Angular | Infragistics | MIT license -description: Ignite UI for Angular Avatar control enables users to add images, material icons or initials within any application for instances such as a profile button. +description: The Ignite UI for Angular Avatar is a compact UI element that represents a user or entity with a profile image, an igx-icon, or their initials. keywords: Angular Avatar component, Angular Avatar control, Ignite UI for Angular, Angular UI components license: MIT llms: - description: "Angular Avatar component helps adding initials, images, or material icons to your application." + description: "The Angular Avatar is a compact UI element that represents a user, entity, or object by displaying their profile image, an igx-icon, or their initials." +relatedComponents: [Badge] --- import DocsAside from 'igniteui-astro-components/components/mdx/DocsAside.astro'; import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; -# Angular Avatar Component Overview +# Avatar Component
-Angular Avatar component helps adding initials, images, or material icons to your application. +The Angular Avatar is a compact UI element that represents a user, entity, or object by displaying their profile image, an `igx-icon`, or their initials.
- -## Angular Avatar Example +## Overview - +### When to Use -
+Use the avatar to represent a user, entity, or object with a compact image, icon, or set of initials — for example a profile button, a comment author, or a list item's leading visual. -## Getting Started with Ignite UI for Angular Avatar +### When Not to Use -To get started with the Ignite UI for Angular Avatar component, first you need to install Ignite UI for Angular. In an existing Angular application, type the following command: +To display a count, status, or notification indicator rather than represent an entity, use the component, which is designed to decorate other elements (including avatars) with a small count or status icon. -```cmd -ng add igniteui-angular -``` + -For a complete introduction to the Ignite UI for Angular, read the [_getting started_](/general/getting-started) topic. +## Anatomy -The next step is to import the `IgxAvatarModule` in your **app.module.ts** file. +{/*TODO: add an anatomy diagram (screenshot or GIF) labeling the avatar's parts.*/} -```typescript -// app.module.ts +The avatar is a single host element that renders one content template, chosen by [content priority](#content). Its rendered DOM is: -... -import { IgxAvatarModule } from 'igniteui-angular/avatar'; -// import { IgxAvatarModule } from '@infragistics/igniteui-angular'; for licensed package - -@NgModule({ - ... - imports: [..., IgxAvatarModule], - ... -}) -export class AppModule {} +``` +igx-avatar[role="img"] // host — shape & size set via attributes / CSS vars +└─ one of, by priority: + ├─ div.igx-avatar__image // `src` set — image painted as a background + ├─ igx-icon // `icon` set + ├─ span // `initials` set — first two characters + └─ // custom projected content ``` -Alternatively, as of `16.0.0` you can import the `IgxAvatarComponent` as a standalone dependency. +## Getting Started + +Install Ignite UI for Angular first (`ng add igniteui-angular`) — see [Getting Started](/general/getting-started) for the full walkthrough. + +Import the standalone `IgxAvatarComponent` and add it to your component's `imports` array, then use the `` tag in that component's template. ```typescript // home.component.ts - -... +import { Component } from '@angular/core'; import { IgxAvatarComponent } from 'igniteui-angular/avatar'; -// import { IgxAvatarComponent } from '@infragistics/igniteui-angular'; for licensed package +// Licensed package: import from '@infragistics/igniteui-angular' instead @Component({ selector: 'app-home', - template: '', - styleUrls: ['home.component.scss'], - standalone: true, - imports: [IgxAvatarComponent] + imports: [IgxAvatarComponent], // makes available in this template + template: '' }) export class HomeComponent {} ``` -Now that you have the Ignite UI for Angular Avatar module or component imported, you can start with a basic configuration of the `igx-avatar` component. - -## Using the Angular Avatar Component +## Usage -The Ignite UI for Angular Avatar component comes in three shapes (square, rounded, and circle) and three size options (small, medium, and large). It can be used for displaying initials, images or icons. +The avatar renders initials, an image, or an [`igx-icon`](/icon), in one of three shapes and three preset sizes. -### Avatar Shape +### Shape -We can change the avatar shape through the attribute setting its value to `square`, `rounded` or `circle`. By default, the shape of the avatar is `square`. +Set the `shape` attribute to `square`, `rounded`, or `circle`. The default is `square`. ```html ``` -### Avatar displaying initials +### Size -To get a simple avatar with (i.e. JS for 'Jack Sock'), add the following code inside the component template: +Set the `size` attribute to a preset value — `small`, `medium`, or `large` (default `small`). For arbitrary sizes, use the CSS variables described under [Custom sizing](#custom-sizing). ```html - + ``` -Let's enhance our avatar by making it circular and bigger in size. +### Content -```html - -``` +An avatar displays a single kind of content, chosen by **priority**: (image) wins over , which wins over . Set the one you need — a higher-priority value hides the others (this is a precedence rule, not an image load-failure fallback). If none is set, the avatar renders its projected content. -We can also change the background using the `--ig-avatar-background` CSS variable or set a color on the initials through the `color` property. - -```scss -// avatar.component.scss - -igx-avatar { - --ig-avatar-background: #e41c77; - color: #000000; -} +**Initials** — the first two characters of `initials` are shown (e.g. `JS` for "Jack Sock"): +```html + ``` - -The `roundShape` property of the `igx-avatar` component have been deprecated. The attribute should be used instead. - + -If all went well, you should see something like the following in the browser: +**Image** — set the image URL via `src`: - +```html + +``` -### Avatar displaying image + -To get an avatar that displays an image, all you have to do is set the image source via the property. +**Icon** — render an [`igx-icon`](/icon) by setting its name via `icon`: ```html - - + ``` + +The avatar renders icons with the [`igx-icon`](/icon) component. To use Google's Material Icons font, add the following to your `index.html`: `` + -If all went well, you should see something like the following in the browser: + - +## Best Practices -### Avatar displaying icon +- Pick one content strategy per context and use it consistently — mixing images, icons, and initials in the same list of avatars reads as inconsistent. +- Set only the content you intend to show. `src`, `icon`, and `initials` follow a fixed precedence rather than falling back automatically on failure, so an unreachable image URL won't be replaced by initials — verify the URL if you need a reliable result. +- Set a descriptive `aria-label` whenever the avatar identifies a specific person or entity, not just when it's convenient. +- Don't use the avatar to show a count, status, or notification badge — decorate it with instead of encoding that information into the initials or icon. -Analogically, the avatar can display an icon via the property. Currently all icons from the material icon set are supported. +## Properties -```html - - -``` +The core inputs used to configure the avatar are listed below. For the complete, always-current API surface, see the [API References](#api-references) section. - -This component uses Material Icons. Add the following link to your `index.html`: `` - +| Property | Type | Default | Description | +| --- | --- | --- | --- | +| `shape` | `"square" \| "rounded" \| "circle"` | `"square"` | Sets the shape of the avatar. | +| `size` | `"small" \| "medium" \| "large"` | `"small"` | Sets the size of the avatar. | +| `initials` | `string` | — | Text initials rendered when no image or icon is set. | +| `icon` | `string` | — | Icon name to render via [`igx-icon`](/icon). | +| `src` | `string` | — | Image source URL to render. | +| `id` | `string` | `"igx-avatar-{n}"` | The unique identifier of the avatar. | -You should see something like this: +## Styling - + -## Styling +The avatar's appearance is controlled through the parameters below. Set `$background`, and the contrast-dependent colors (`$color` and `$icon-color`) are derived automatically. -### Avatar Theme Property Map +| Variable | Description | +| --- | --- | +| `$background` | The avatar background color. Primary token — derives `$color` and `$icon-color`. | +| `$color` | The text/initials color. Auto-derived from `$background` for contrast when not set. | +| `$icon-color` | The icon color. Auto-derived from `$background` for contrast when not set. | +| `$border-radius` | The border radius. Only takes effect when `shape` is `rounded`. | +| `$size` | The size of the avatar. | -Changing the `$background` property automatically updates the following dependent properties: +### Sass Theming -| Primary Property | Dependent Property | Description | -| --- | --- | --- | -| **$background** | $color | The text color used for the avatar. | -| | $icon-color | The icon color used for the avatar. | +#### Using SCSS -To get started with styling the avatar, we need to import the `index` file, where all the theme functions and component mixins live: +To get started with styling the avatar, import the theme entry point where all the theme functions and component mixins live: ```scss @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 providing values for the `$background` and `$border-radius` parameters. The `$color` (or `$icon-color`) is automatically set to either black or white, depending on which offers better contrast with the specified background. Note that the `$border-radius` property only takes effect when the avatar's is set to `rounded`. +Create a new theme that extends the , providing values for the `$background` and `$border-radius` parameters. The `$color` (or `$icon-color`) is automatically set to either black or white, depending on which offers better contrast with the specified background. Note that `$border-radius` only takes effect when the avatar's `shape` is set to `rounded`. Given the following markup: ```html -
- - +
+
``` -We create the following avatar theme: +Create the theme: ```scss $custom-avatar-theme: avatar-theme( - $background: #72da67, - $border-radius: 16px + $background: #72da67, + $border-radius: 16px ); ``` -The last step is to pass the custom avatar theme: +Then apply it to your markup: ```scss -.initials { - @include tokens($custom-avatar-theme); +.my-container:has(igx-avatar[initials]) { + @include tokens($custom-avatar-theme); } ``` -If all went well, you should see something like the following in the browser: +#### Using pure CSS - +Prefer not to use SCSS? Override the component's CSS variables directly: -### Styling with Tailwind +```css +/* overrides all avatars */ +:root { + --ig-avatar-background: #e41c77; +} -You can style the `avatar` using our custom Tailwind utility classes. Make sure to [set up Tailwind](/themes/misc/tailwind-classes) first. +/* overrides only the avatar with class .special */ +igx-avatar.special { + --background: #e41c77; +} +``` + +### Tailwind + +You can style the avatar using our Tailwind utility classes. Make sure to [set up Tailwind](/themes/misc/tailwind-classes) first. -Along with the tailwind import in your global stylesheet, you can apply the desired theme utilities as follows: +With the Tailwind import in your global stylesheet, apply the theme utilities: ```scss @import "tailwindcss"; @@ -223,25 +222,23 @@ The utility file includes both `light` and `dark` theme variants. - Use `dark-*` classes for the dark theme. - Append the component name after the prefix, e.g., `light-avatar`, `dark-avatar`. -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.). +Once applied, these classes enable dynamic theme calculations. From there, override the generated CSS variables using Tailwind's arbitrary-property syntax — for example `[--background:#FF4E00]` — with any valid CSS color format (HEX, CSS variable, RGB, etc.). -You can find the full list of properties in the . The syntax is as follows: +See the for the full list of parameters. For example: ```html + class="!light-avatar ![--background:#FF4E00]" + initials="DY" + shape="rounded"> ``` -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. +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 avatar should look like this: - - + ### Custom sizing @@ -257,7 +254,6 @@ Or you can use the universal `--ig-avatar-size` variable to target all instances ```html
-
``` @@ -268,7 +264,7 @@ Or you can use the universal `--ig-avatar-size` variable to target all instances } ``` -You can also use one of the predefined sizes, assigning it to the `--ig-size` variable, if theres no size attribute applied. The available values for `--ig-size` are `--ig-size-small`, `--ig-size-medium`, and `--ig-size-large`: +You can also use one of the predefined sizes by assigning it to the `--ig-size` variable, if no `size` attribute is set. The available values for `--ig-size` are `--ig-size-small`, `--ig-size-medium`, and `--ig-size-large`: ```scss igx-avatar { @@ -276,23 +272,81 @@ igx-avatar { } ``` -Learn more about it in the [Size](/display-density) article. +Learn more in the [Size](/display-density) article. + +## Accessibility + +### Keyboard Interaction + +The avatar is a non-interactive, presentational element — it doesn't receive focus and has no keyboard interaction to document. + +### Screen Readers / ARIA + +The avatar renders with `role="img"` and a default `aria-label` of `avatar`, and it automatically sets `aria-roledescription` to reflect its content — `image avatar`, `icon avatar`, `initials avatar`, or `custom avatar` for projected content. + +When the avatar carries meaning — such as identifying a specific person — set a descriptive `aria-label` so screen-reader users get the same information sighted users get from the image, icon, or initials: + +```html + +``` + +If the avatar is purely decorative and its meaning is already conveyed by adjacent text (for example, a name shown next to it), keep the label minimal so the same information isn't announced twice. + +### Accessibility Compliance + +Infragistics evaluates Ignite UI for Angular components against Section 508 and WCAG guidelines — see the [Accessibility Compliance](/interactivity/accessibility-compliance) topic for the full component-by-component matrix. + +| Criterion | How the Avatar complies | +| --- | --- | +| [1.1.1 Non-text Content](https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html) | The default `aria-label="avatar"` gives every avatar an accessible name; set your own `aria-label` when the image, icon, or initials convey specific meaning (e.g. a person's identity). | +| [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html) | The host element exposes `role="img"` and an `aria-roledescription` (`image avatar`, `icon avatar`, `initials avatar`, or `custom avatar`) reflecting its current content. | + +**Your responsibilities** + +- Provide a descriptive `aria-label` whenever the avatar identifies a specific person or entity. +- Keep sufficient color contrast between the avatar's background and its text/icon color when customizing the theme — see [Styling](#styling). + +## Troubleshooting + +### Why doesn't the `roundShape` property work anymore? + +`roundShape` was replaced by `shape` in `15.1.0`. Run `ng update` to migrate existing usages automatically, or update them by hand — `shape="circle"` replaces `roundShape="true"`, and `shape="square"` (the default) replaces `roundShape="false"`. + +### How do I use the avatar in a module-based (NgModule) app? + +Standalone is the default in modern Angular, and Ignite UI for Angular components support it since `16.0.0`. In an older, module-based application, import `IgxAvatarModule` and add it to your `@NgModule` `imports` array instead of importing the component directly: + +```typescript +// app.module.ts +import { IgxAvatarModule } from 'igniteui-angular/avatar'; +// import { IgxAvatarModule } from '@infragistics/igniteui-angular'; for licensed package + +@NgModule({ + imports: [IgxAvatarModule], +}) +export class AppModule {} +``` + +### Why does my theme import fail on older versions? + +The `@use "igniteui-angular/theming" as *;` entry point was introduced in v13. On earlier versions, import the themes index instead: -
+```scss +@import '~igniteui-angular/lib/core/styles/themes/index'; +``` ## API References -
+ - -## Theming Dependencies + +## Dependencies - - ## Additional Resources -
- Our community is active and always welcoming to new ideas. - [Ignite UI for Angular **Forums**](https://www.infragistics.com/community/forums/f/ignite-ui-for-angular) -- [Ignite UI for Angular **GitHub**](https://github.com/IgniteUI/igniteui-angular) +- [Ignite UI for Angular **GitHub**](https://github.com/IgniteUI/igniteui-angular) \ No newline at end of file diff --git a/docs/angular/src/content/en/components/calendar.mdx b/docs/angular/src/content/en/components/calendar.mdx index a89e434a99..558cfba00c 100644 --- a/docs/angular/src/content/en/components/calendar.mdx +++ b/docs/angular/src/content/en/components/calendar.mdx @@ -1,8 +1,9 @@ --- -title: Angular Calendar Component – Ignite UI for Angular | MIT license -description: With Angular Calendar Component, users can create intuitive calendars for applications to display date information using three different selection modes. Try it Now +title: Angular Calendar Component – Ignite UI for Angular | MIT license +description: The Angular Calendar component displays dates with single, multiple, or range selection, localization, disabled and special dates, and multiple views. keywords: angular calendar, angular calendar component, angular UI components, angular UI library, ignite ui for angular license: MIT +relatedComponents: [DatePicker, DateRangePicker] llms: description: "Angular Calendar is a UI component used for displaying dates and days in an app." --- @@ -11,59 +12,47 @@ import DocsAside from 'igniteui-astro-components/components/mdx/DocsAside.astro' import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; -# Angular Calendar Component Overview +# Calendar Component -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. +Angular Calendar is a UI component used for displaying dates and days in an app. It renders a month, year, or decade view and lets users select a single date, multiple dates, or a date range, with support for localization, disabled dates, and special dates. -
+## Overview -The Ignite UI for Angular Calendar component, developed as a native [Angular component](https://angular.io/guide/architecture#components), 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. -
+### When to Use -## Angular Calendar Example +Use the Calendar when you need an always-visible date surface embedded in the page — a scheduling panel, an availability view, or a form that benefits from selecting single dates, multiple dates, or a range directly in the layout. -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. +### When Not to Use -
+- To bind a single date to a text input in a compact dropdown, use the — it hosts a calendar in a drop-down and exposes the value through an input. +- To capture a start/end pair bound to inputs, use the instead of wiring range selection onto a bare calendar. - + -## Getting Started with Ignite UI for Angular Calendar +## Anatomy -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: +{/*TODO: add an annotated screenshot of the calendar parts (header, navigation subheader, days grid).*/} -```cmd -ng add igniteui-angular +The calendar renders a header, a navigation subheader, and a view area that swaps between the days, months, and years views. The header is hidden when `selection` is `multi` or `range`. + +``` +igx-calendar +├── Header // selected date; hidden for multi/range selection +├── Navigation subheader // previous button · month button · year button · next button +└── View area (role="grid") + ├── igx-days-view // day grid for the current month(s) + ├── igx-months-view // month picker + └── igx-years-view // decade (year) picker ``` -For a complete introduction to the Ignite UI for Angular, read the [_getting started_](/general/getting-started) topic. +## Getting Started -The next step is to import the `IgxCalendarModule` in your **app.module.ts** file. +Requires Ignite UI for Angular — see [Getting Started](/general/getting-started) (`ng add igniteui-angular`). - -The also depends on the [`BrowserAnimationsModule`](https://angular.io/api/platform-browser/animations/BrowserAnimationsModule), so it needs to be added to the AppModule as well: - - -```typescript -// app.module.ts -... -import { BrowserAnimationsModule } from '@angular/platform-browser/animations'; -import { IgxCalendarModule } from 'igniteui-angular/calendar'; -// import { IgxCalendarModule } from '@infragistics/igniteui-angular'; for licensed package - -@NgModule({ - ... - imports: [..., BrowserAnimationsModule, IgxCalendarModule], - ... -}) -export class AppModule {} -``` - -Alternatively, as of `16.0.0` you can import the as a standalone dependency, or use the [`IGX_CALENDAR_DIRECTIVES`](https://github.com/IgniteUI/igniteui-angular/blob/master/projects/igniteui-angular/calendar/src/calendar/public_api.ts) token to import the component and all of its supporting components and directives. +Import `IGX_CALENDAR_DIRECTIVES` in the component where you use the calendar. The calendar also depends on `BrowserAnimationsModule`, so add it to the same `imports`: ```typescript // home.component.ts - import { BrowserAnimationsModule } from '@angular/platform-browser/animations'; import { IGX_CALENDAR_DIRECTIVES } from 'igniteui-angular/calendar'; // import { IGX_CALENDAR_DIRECTIVES } from '@infragistics/igniteui-angular'; for licensed package @@ -72,72 +61,66 @@ import { IGX_CALENDAR_DIRECTIVES } from 'igniteui-angular/calendar'; selector: 'app-home', template: '', styleUrls: ['home.component.scss'], - standalone: true, imports: [BrowserAnimationsModule, IGX_CALENDAR_DIRECTIVES] - /* or imports: [BrowserAnimationsModule, 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. +The `IGX_CALENDAR_DIRECTIVES` token imports the together with its views and supporting directives. To register the calendar on its own, import `IgxCalendarComponent` instead. For the legacy `NgModule` setup, see [Troubleshooting](#troubleshooting). -The uses the [Intl Web API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat) for localization and formatting of dates. +The uses the [Intl Web API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat) for localization and formatting of dates. Consider using [appropriate polyfills](https://github.com/andyearnshaw/Intl.js/) if your target platform does not support them. -Consider using [appropriate polyfills](https://github.com/andyearnshaw/Intl.js/) if your target platform does not support them. -## Using the Angular Calendar +## Usage -### Angular Single Selection Calendar +### Single selection -Instantiating the is as easy as placing its selector element in the template. This will display the current month in the single selection calendar mode. +Place the `igx-calendar` selector in the template. With no `selection` set, the calendar renders the current month in single selection mode: ```html {/* app.component.html */} -{/* Single selection mode */} ``` -### Angular Calendar Multiselect +### Multiple selection -We can easily change the default mode using the property: +Set the property to `multi` to let users pick several individual dates: ```html {/* app.component.html */} -{/* Multi selection mode */} ``` - + -### Angular Calendar Range Picker +### Range selection -Following the same approach, we can switch to range selection mode: +Set `selection` to `range` to let users pick a continuous range between two dates: ```html {/* app.component.html */} -{/* Range selection mode */} ``` - + -Notice that the calendar header is not rendered when the selection is either `multi` or `range`. +The calendar header is not rendered when `selection` is either `multi` or `range`. -### Localization and Formatting +### Localization and formatting -Due to their very nature, localization and formatting are essential to any calendar. In the those are controlled and customized through the following properties - , , , . +Control localization and formatting through , , , and . -Let's go ahead and try those along with other customizations from the API. First thing we need to set is the , 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 properties to customize the display formatting. Finally, we are binding the `locale` property to a value, based on the user's location choice: +`weekStart` sets the starting day of the week. If you don't set it, the calendar uses the first day of the week for its `locale`. Set it to `1` for Monday. `formatOptions` and `formatViews` customize how the day, month, and year are rendered, and `locale` sets the language: ```html {/* app.component.html */} - - {{ locale }} - + @for (locale of locales; track locale) { + {{ locale }} + } ``` -All property values should be set in the AppComponent file: +Set the bound values in the component: ```typescript // app.component.ts @@ -165,17 +148,13 @@ public ngOnInit() { } ``` -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 +### Disabled dates -This section demonstrates the usage of functionality. For this purpose, different single dates or ranges can be added to an array and then passed to the descriptor. +Assign an array of descriptors to to prevent dates from being selected. Use to describe the range to disable. -The 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: +Disable the dates between the 3rd and the 8th of the current month: ```typescript export class CalendarSample6Component { @@ -192,15 +171,11 @@ export class CalendarSample6Component { } ``` -These configurations should have the following result: - - + ### Special dates -The feature is using almost the same configuration principles as the . The ability to select and focus is what differs them from the `disabled` ones. - -Let's add some to our `igxCalendar`. In order to do this, we have to create a item of type and pass an array of dates as a : + uses the same descriptor configuration as `disabledDates`, but special dates stay selectable and focusable. Create a of type and pass an array of dates as its : ```typescript export class CalendarSample7Component { @@ -239,165 +214,44 @@ export class CalendarSample7Component { ``` -The following demo illustrates a calendar with a vacation request option: - - + ### Week numbers -You can now use input to show the week numbers for both Calendar and DatePicker components. +Set to `true` to display week numbers. The same input applies to the Date Picker. ```html - {/* app.component.html */} ``` -The following demo illustrates a calendar with enabled week numbers: - - - -## Calendar Events - -Let's explore the events emitted by the calendar: - -- - emitted when selecting date(s) in the calendar. -- - emitted every time when the presented month/year is changed - for example after navigating to the `next` or `previous` month. -- - emitted after the active view is changed - for example after the user has clicked on the `month` or `year` section in the header. - -```html -{/* app.component.html */} - - -``` - -The 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: - -```typescript -// 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: - -- Angular Calendar Days View - - - + -- Angular Calendar Month View - +### Views - +The days, months, and years views ship as standalone components you can use independently of the full calendar: -- Angular Calendar Year View - +- — the day grid. - + -## Keyboard navigation +- — the month picker. -If you traverse the page using _Tab key_ you should keep in mind that based on [W3 accessibility recommendations](https://www.w3.org/TR/wai-aria-practices/#layoutGrid) the 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_. - - -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. - - -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. - +- — the year picker. -## Multi View Calendar + -Multi-view calendar supports all three types of selection. Use the 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 property. Keyboard navigation moves to next/previous months when those are in view. +### Multi-view - +Set to render several months side by side in a flex container; multi-view supports all three selection types. There is no maximum value. Set to `true` to hide days that don't belong to the current month, and keyboard navigation moves to the next or previous month when it is in view. -## Calendar Orientation + -The orientation settings allows users to choose how the header and the view of the calendar are displayed. +### Orientation -### 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 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 property, setting it respectively to `horizontal` or `vertical`. - - -You need at least two month view calendar to see that property working. - +Set `headerOrientation` to place the header `horizontal` (above the view) or `vertical` (beside the view). Set `orientation` to lay the months out `horizontal` (side by side) or `vertical` (stacked). Both default to `horizontal`. ```html @@ -422,234 +276,239 @@ export class CalendarSample9Component { } ``` - + +Set `monthsViewNumber` to at least `2` to see the `orientation` setting take effect. + -## Styling + -### Calendar Theme Property Map +### Handling events -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. +Bind to the calendar events to react to selection and navigation: -
+```html +{/* app.component.html */} + + +``` -{/*Theme Switcher Radios and Labels*/} - - - - - - - - +The event emits a single `Date` in `single` selection and a `Date[]` in `multi` or `range` selection, so it is a good place for validation. Alert the user when the selection exceeds 5 days and then reset it: -
+```typescript +// 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 the previously presented month/year. + // use event.currentValue to get the currently presented month/year. +} - {/* Material Theme Table */} -
+public activeViewChanged(event: CalendarView) { + // use CalendarView[event] to get the current active view (DEFAULT, YEAR or DECADE) +} +``` - | Primary Property | Dependent Property | Description | -| --- | --- | --- | -| **$header-background** | $header-foreground | Text color for the calendar header | -| | $picker-hover-foreground | Picker hover foreground | -| | $picker-focus-foreground | Picker focus foreground | -| | $navigation-hover-color | Hover color for navigation | -| | $navigation-focus-color | Focus color for navigation | -| | $date-selected-background | Background for selected dates | -| | $date-selected-current-background | Selected current date background | -| | $date-selected-foreground | Foreground for selected dates | -| | $date-selected-current-foreground | Foreground for selected current date | -| | $date-selected-current-border-color | Border color for selected current date | -| | $date-selected-special-border-color | Border color for selected special dates | -| | $ym-selected-background | Year/month selected background | -| | $ym-selected-hover-background | Hover background for year/month selected date | -| | $ym-selected-current-background | Current selected year/month background | -| | $ym-selected-current-hover-background | Hover background for current selected year/month | -| | $ym-selected-foreground | Foreground for selected year/month | -| | $ym-selected-hover-foreground | Hover foreground for selected year/month | -| | $ym-selected-current-foreground | Foreground for current selected year/month | -| | $ym-selected-current-hover-foreground | Hover foreground for current selected year/month | -| **$content-background** | $content-foreground | Text and icon color inside calendar content area | -| | $weekend-color | Color for weekend dates | -| | $inactive-color | Color for dates outside active range | -| | $weekday-color | Color for weekday labels | -| | $picker-background | Picker background | -| | $date-hover-background | Background for hovered dates | -| | $date-hover-foreground | Foreground for hovered dates | -| | $date-focus-background | Background for focused dates | -| | $date-focus-foreground | Foreground for focused dates | -| | $date-current-background | Background for the current date | -| | $date-current-foreground | Foreground for the current date | -| | $date-current-border-color | Border color for the current date | -| | $ym-current-background | Year/month current background | -| | $ym-current-hover-background | Hover background for current year/month | -| | $ym-current-foreground | Foreground for current year/month | -| | $ym-current-hover-foreground | Hover foreground for current year/month | -| | $date-selected-range-background | Selected range background | -| | $date-selected-range-foreground | Foreground for selected date ranges | -| | $date-selected-current-range-background | Background for selected current date ranges | -| | $date-selected-current-range-hover-background | Hover background for selected current date ranges | -| | $date-selected-current-range-focus-background | Focus background for selected current date ranges | -| | $date-selected-current-range-foreground | Foreground for selected current date ranges | -| | $date-special-foreground | Foreground for special dates | -| | $date-special-border-color | Border color for special dates | -| | $date-special-hover-border-color | Hover border color for special dates | -| | $date-special-focus-foreground | Focus foreground for special dates | -| | $date-special-range-foreground | Foreground for special date ranges | -| | $date-special-range-border-color | Border color for special date ranges | -| | $date-special-range-hover-background | Hover background for special date ranges | -| | $date-selected-special-border-color | Border color for selected special dates | -| | $date-selected-special-hover-border-color | Hover border color for selected special dates | -| | $date-selected-special-focus-border-color | Focus border color for selected special dates | -| | $date-disabled-foreground | Foreground for disabled dates | -| | $date-disabled-range-foreground | Foreground for disabled ranges | -| **$date-border-radius** | $date-range-border-radius | Controls the border radius for date ranges. | -| | $date-current-border-radius | Controls the border radius for the current date. | -| | $date-special-border-radius | Controls the border radius for special dates. | -| | $date-border-radius | If not specified and `$date-range-border-radius` is set, uses the value of `$date-range-border-radius`. | - -
- {/* Fluent Theme Table */} -
- - | Primary Property | Dependent Property | Description | + + +## Best Practices + +- Match the `selection` mode to the real task — `single` for one date, `multi` for scattered individual picks, `range` for a start/end pair — instead of layering custom logic onto the wrong mode. +- Use `disabledDates` and `specialDates` to communicate availability directly in the grid rather than relying on separate legend text the user has to cross-reference. +- Set `weekStart` and `locale` together when localizing — leaving `weekStart` unset lets the calendar infer it from `locale`, so setting one without the other can produce a week layout that doesn't match the surrounding page's language. +- Don't embed a full Calendar just to capture one date bound to a text field — use the Date Picker instead (see [When Not to Use](#when-not-to-use)). + +## Properties + +{/*Curated core inputs, verified from IgxCalendarComponent. See API References for the complete list.*/} + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `selection` | `'single' \| 'multi' \| 'range'` | `'single'` | Selection mode. Changing it resets the current selection. | +| `value` | `Date \| Date[]` | — | Selected date(s): a single `Date` for `single`, otherwise a `Date[]`. | +| `viewDate` | `Date` | current date | The date presented when the calendar renders. | +| `weekStart` | `WEEKDAYS \| number` | locale's first day | Starting day of the week; falls back to the `locale`'s first day. | +| `locale` | `string` | application locale | BCP 47 language tag used for formatting. | +| `formatOptions` | `IFormattingOptions` | `{ day: 'numeric', month: 'long', weekday: 'narrow', year: 'numeric' }` | `Intl` date-format options per view. | +| `formatViews` | `IFormattingViews` | `{ day: false, month: true, year: false }` | Which views apply `formatOptions`. | +| `disabledDates` | `DateRangeDescriptor[]` | `[]` | Ranges that cannot be selected. | +| `specialDates` | `DateRangeDescriptor[]` | `[]` | Highlighted ranges that remain selectable. | +| `showWeekNumbers` | `boolean` | `false` | Displays the week numbers column. | +| `hideOutsideDays` | `boolean` | `false` | Hides days that fall outside the current month. | +| `monthsViewNumber` | `number` | `1` | Number of month views rendered side by side. | +| `hasHeader` | `boolean` | `true` | Renders the calendar header (single selection only). | +| `headerOrientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Header placement relative to the view. | +| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout direction of the month views. | +| `activeView` | `IgxCalendarView` | `'month'` | The view in focus (`month`, `year`, or `decade`). | + +## Methods + +| Name | Parameters | Description | | --- | --- | --- | -| **$header-background** | $header-foreground | Text color for the calendar header | -| | $picker-hover-foreground | Picker hover foreground | -| | $picker-focus-foreground | Picker focus foreground | -| | $date-current-background | Background for the current date | -| | $date-current-hover-foreground | Hover foreground for the current date | -| | $date-current-focus-foreground | Focus foreground for the current date | -| | $date-selected-current-foreground | Foreground for the currently selected date | -| | $date-selected-current-hover-foreground | Hover foreground for the currently selected date | -| | $date-selected-current-focus-foreground | Focus foreground for the currently selected date | -| | $date-special-border-color | Border color for special dates | -| | $date-special-hover-foreground | Hover foreground for special dates | -|**$content-background** | $content-foreground | Text and icon color inside calendar content area | -| | $weekend-color | Color for weekend dates | -| | $inactive-color | Color for dates outside active range | -| | $weekday-color | Color for weekday labels | -| | $picker-background | Picker background | -| | $date-hover-background | Background for hovered dates | -| | $date-hover-foreground | Foreground for hovered dates | -| | $date-focus-background | Background for focused dates | -| | $date-focus-foreground | Foreground for focused dates | -| | $date-selected-background | Background for selected dates | -| | $date-selected-hover-background | Hover background for selected dates | -| | $date-selected-focus-background | Focus background for selected dates | -| | $date-selected-foreground | Foreground for selected dates | -| | $date-selected-hover-foreground | Hover foreground for selected dates | -| | $date-selected-focus-foreground | Focus foreground for selected dates | -| | $date-selected-range-background | Background for selected date ranges | -| | $date-selected-range-foreground | Foreground for selected date ranges | -| | $date-disabled-foreground | Foreground for disabled dates | -| | $date-disabled-range-foreground | Foreground for disabled ranges | -| **$date-border-radius** | $date-range-border-radius | Controls the border radius for date ranges. | -| | $date-current-border-radius | Controls the border radius for the current date. | -| | $date-special-border-radius | Controls the border radius for special dates. | -| | $date-border-radius | If not specified and `$date-range-border-radius` is set, uses the value of `$date-range-border-radius`. | - -
- {/* Bootstrap Theme Table */} -
- - | Primary Property | Dependent Property | Description | -| --- | --- | --- | -| **$header-background** | $header-foreground | Text color for the calendar header | -| | $picker-background | Picker background | -| | $picker-hover-foreground | Picker hover foreground | -| | $weekday-color | Color for weekday labels | -| | $picker-focus-foreground | Picker focus foreground | -| | $date-special-border-color | Border color for special dates | -| | $date-special-focus-foreground | Focus foreground for special dates | -| **$content-background** | $content-foreground | Text and icon color inside calendar content area | -| | $weekend-color | Color for weekend dates | -| | $inactive-color | Color for dates outside active range | -| | $weekday-color | Color for weekday labels | -| | $date-hover-background | Background for hovered dates | -| | $date-hover-foreground | Foreground for hovered dates | -| | $date-focus-background | Background for focused dates | -| | $date-focus-foreground | Foreground for focused dates | -| | $date-current-background | Background for the current date | -| | $date-current-foreground | Foreground for the current date | -| | $date-current-border-color | Border color for the current date | -| | $date-selected-background | Background for selected dates | -| | $date-selected-current-background | Background for the currently selected date | -| | $date-selected-foreground | Foreground for selected dates | -| | $date-selected-current-foreground | Foreground for the currently selected date | -| | $date-selected-special-border-color | Border color for selected special dates | -| | $date-selected-special-hover-border-color | Hover border color for selected special dates | -| | $date-selected-special-focus-border-color | Focus border color for selected special dates | -| | $date-selected-range-background | Background for selected date ranges | -| | $date-selected-range-foreground | Foreground for selected date ranges | -| | $date-disabled-foreground | Foreground for disabled dates | -| | $date-disabled-range-foreground | Foreground for disabled ranges | -| **$date-border-radius** | $date-range-border-radius | Controls the border radius for date ranges. | -| | $date-current-border-radius | Controls the border radius for the current date. | -| | $date-special-border-radius | Controls the border radius for special dates. | -| | $date-border-radius | If not specified and `$date-range-border-radius` is set, uses the value of `$date-range-border-radius`. | - -
- {/* Indigo Theme Table */} -
- - | Primary Property | Dependent Property | Description | +| `selectDate` | `value: Date \| Date[] \| string` | Selects date(s) according to the current `selection` mode. | +| `deselectDate` | `value?: Date \| Date[] \| string` | Deselects date(s); clears the whole selection when called with no argument. | + +## Events + +| Name | Type | Description | | --- | --- | --- | -| **$header-background** | $header-foreground | Text color for the calendar header | -| | $picker-background | Picker background | -| | $picker-hover-foreground | Picker hover foreground | -| | $picker-focus-foreground | Picker focus foreground | -| | $navigation-hover-color | Navigation hover color | -| | $navigation-focus-color | Navigation focus color | -| | $date-current-background | Background for the current date | -| | $date-current-border-color | Border color for the current date | -| | $date-current-hover-background | Background for hovered current date | -| | $date-current-hover-border-color | Border color for hovered current date | -| | $date-current-focus-background | Background for focused current date | -| | $date-current-focus-border-color | Border color for focused current date | -| | $date-current-foreground | Foreground for the current date | -| | $date-current-hover-foreground | Foreground for hovered current date | -| | $date-current-focus-foreground | Foreground for focused current date | -| | $date-selected-current-border-color | Border color for the currently selected date | -| **$content-background** | $content-foreground | Text and icon color inside calendar content area | -| | $weekend-color | Color for weekend dates | -| | $inactive-color | Color for dates outside active range | -| | $weekday-color | Color for weekday labels | -| | $date-hover-background | Background for hovered dates | -| | $date-hover-foreground | Foreground for hovered dates | -| | $date-focus-background | Background for focused dates | -| | $date-focus-foreground | Foreground for focused dates | -| | $date-selected-background | Background for selected dates | -| | $date-selected-current-background | Background for the currently selected date | -| | $date-selected-foreground | Foreground for selected dates | -| | $date-selected-current-foreground | Foreground for the currently selected date | -| | $date-selected-current-border-color | Border color for the currently selected date | -| | $date-selected-range-background | Background for selected date ranges | -| | $date-selected-range-foreground | Foreground for selected date ranges | -| | $date-selected-current-range-background | Background for the current date in a selected range | -| | $date-selected-current-range-hover-background | Hover background for the current date in a selected range | -| | $date-selected-current-range-foreground | Foreground for the current date in a selected range | -| | $date-disabled-foreground | Foreground for disabled dates | -| | $date-disabled-range-foreground | Foreground for disabled ranges | -| **$date-border-radius** | $date-range-border-radius | Controls the border radius for date ranges. | -| | $date-current-border-radius | Controls the border radius for the current date. | -| | $date-special-border-radius | Controls the border radius for special dates. | -| | $date-border-radius | If not specified and `$date-range-border-radius` is set, uses the value of `$date-range-border-radius`. | - -
- -
-
{/* .theme-switcher-wrapper */} - -To get started with styling the calendar, we need to import the `index` file, where all the theme functions and component mixins live: +| `selected` | `EventEmitter` | Emitted when date(s) are selected. | +| `viewDateChanged` | `EventEmitter` | Emitted when the presented month or year changes. | +| `activeViewChanged` | `EventEmitter` | Emitted when the active view changes (for example, from month to year). | + +## Styling + +Style the calendar by creating a theme and passing it to the component. The sample below applies a custom `$header-background` and `$content-background`: + + + +All themes expose the same set of variables — only their default values differ per theme. Many of them auto-derive from the primary properties (`$header-background`, `$content-background`) when not set explicitly, so the component stays visually consistent. + +| Variable | Description | +| --- | --- | +| `$size` | Size of days, months, and years views. | +| `$inner-size` | Inner size for calendar elements. | +| `$weekday-color` | Color for weekday labels. Auto-derived from content-background. | +| `$actions-divider-color` | Divider color for date-picker actions. | +| `$border-radius` | Border radius for calendar container. | +| `$content-background` | Background color for calendar. PRIMARY - derives content-foreground, inactive-color, date-hover colors, week-number colors. | +| `$border-color` | Border color for calendar container. | +| `$header-background` | Header background color. PRIMARY - derives header-foreground and most accent/selection colors. | +| `$header-foreground` | Header foreground color. Auto-derived from header-background. | +| `$picker-foreground` | Foreground for the calendar picker. Auto-derived from picker-background. | +| `$picker-background` | Background for the calendar picker. | +| `$picker-hover-foreground` | Hover foreground for the calendar picker. Auto-derived from header-background. | +| `$picker-focus-foreground` | Focus foreground for the calendar picker. Auto-derived from picker-hover-foreground. | +| `$navigation-color` | Icon color for month navigation. Auto-derived from picker-background. | +| `$navigation-hover-color` | Hover color for navigation icons. Auto-derived from picker-hover-foreground. | +| `$navigation-focus-color` | Focus color for navigation icons. Auto-derived from navigation-hover-color. | +| `$ym-border-radius` | Border radius for year/month views. | +| `$ym-hover-foreground` | Hover foreground for year/month. Auto-derived from ym-hover-background. | +| `$ym-hover-background` | Hover background for year/month. Auto-derived from date-hover-background. | +| `$ym-current-outline-color` | Outline color for current year/month. Auto-derived from date-current-border-color. | +| `$ym-current-outline-hover-color` | Hover outline color for current year/month. | +| `$ym-current-outline-focus-color` | Focus outline color for current year/month. | +| `$ym-current-background` | Background for current year/month. | +| `$ym-current-foreground` | Foreground for current year/month. Auto-derived from ym-current-background. | +| `$ym-current-hover-foreground` | Hover foreground for current year/month. | +| `$ym-current-hover-background` | Hover background for current year/month. | +| `$ym-selected-outline-color` | Outline color for selected year/month. | +| `$ym-selected-hover-outline-color` | Hover outline color for selected year/month. | +| `$ym-selected-focus-outline-color` | Focus outline color for selected year/month. | +| `$ym-selected-foreground` | Foreground for selected year/month. Auto-derived from ym-selected-background. | +| `$ym-selected-background` | Background for selected year/month. Auto-derived from header-background. | +| `$ym-selected-hover-foreground` | Hover foreground for selected year/month. | +| `$ym-selected-hover-background` | Hover background for selected year/month. | +| `$ym-selected-current-outline-color` | Outline color for selected current year/month. | +| `$ym-selected-current-outline-hover-color` | Hover outline color for selected current year/month. | +| `$ym-selected-current-outline-focus-color` | Focus outline color for selected current year/month. | +| `$ym-selected-current-foreground` | Foreground for selected current year/month. | +| `$ym-selected-current-background` | Background for selected current year/month. | +| `$ym-selected-current-hover-foreground` | Hover foreground for selected current year/month. | +| `$ym-selected-current-hover-background` | Hover background for selected current year/month. | +| `$week-number-border-radius` | Border radius for week number column. | +| `$week-number-foreground` | Foreground for week number column. Auto-derived from week-number-background. | +| `$week-number-background` | Background for week number column. Auto-derived from content-background. | +| `$content-foreground` | The foreground color for idle dates. Auto-derived from content-background. | +| `$weekend-color` | Color for weekend days. Auto-derived from content-foreground. | +| `$inactive-color` | Color for inactive dates (outside current month). Auto-derived from content-background. | +| `$date-border-radius` | Border radius for date cells. | +| `$date-border-color` | Border color for date cells. | +| `$date-hover-border-color` | Hover border color for date cells. | +| `$date-focus-border-color` | Focus border color for date cells. | +| `$date-hover-background` | Hover background for date cells. Auto-derived from content-background. | +| `$date-focus-background` | Focus background for date cells. Auto-derived from date-hover-background. | +| `$date-hover-foreground` | Hover foreground for date cells. Auto-derived from date-hover-background. | +| `$date-focus-foreground` | Focus foreground for date cells. Auto-derived from date-hover-foreground. | +| `$date-selected-border-color` | Border color for selected date. | +| `$date-selected-hover-border-color` | Hover border color for selected date. | +| `$date-selected-focus-border-color` | Focus border color for selected date. | +| `$date-selected-background` | Background for selected date. Auto-derived from header-background. | +| `$date-selected-foreground` | Foreground for selected date. Auto-derived from date-selected-background. | +| `$date-selected-hover-background` | Hover background for selected date. Auto-derived from date-selected-background. | +| `$date-selected-focus-background` | Focus background for selected date. | +| `$date-selected-hover-foreground` | Hover foreground for selected date. | +| `$date-selected-focus-foreground` | Focus foreground for selected date. | +| `$date-selected-special-border-color` | Border color for selected special date. | +| `$date-selected-special-hover-border-color` | Hover border color for selected special date. | +| `$date-selected-special-focus-border-color` | Focus border color for selected special date. | +| `$date-selected-special-background` | Background for selected special date. | +| `$date-selected-special-foreground` | Foreground for selected special date. | +| `$date-selected-special-hover-background` | Hover background for selected special date. | +| `$date-selected-special-focus-background` | Focus background for selected special date. | +| `$date-selected-special-hover-foreground` | Hover foreground for selected special date. | +| `$date-selected-special-focus-foreground` | Focus foreground for selected special date. | +| `$date-range-border-radius` | Border radius for date range selection. | +| `$date-range-border-color` | Border color for date range selection. | +| `$date-range-preview-border-color` | Preview border color for date range selection. | +| `$date-selected-range-foreground` | Foreground for dates in selected range. | +| `$date-selected-range-background` | Background for dates in selected range. | +| `$date-selected-range-hover-foreground` | Hover foreground for dates in selected range. | +| `$date-selected-range-hover-background` | Hover background for dates in selected range. | +| `$date-selected-range-focus-foreground` | Focus foreground for dates in selected range. | +| `$date-selected-range-focus-background` | Focus background for dates in selected range. | +| `$date-selected-current-range-foreground` | Foreground for current date in selected range. | +| `$date-selected-current-range-background` | Background for current date in selected range. | +| `$date-selected-current-range-hover-foreground` | Hover foreground for current date in selected range. | +| `$date-selected-current-range-hover-background` | Hover background for current date in selected range. | +| `$date-selected-current-range-focus-foreground` | Focus foreground for current date in selected range. | +| `$date-selected-current-range-focus-background` | Focus background for current date in selected range. | +| `$date-current-border-radius` | Border radius for current date. | +| `$date-current-border-color` | Border color for current date. | +| `$date-current-hover-border-color` | Hover border color for current date. | +| `$date-current-focus-border-color` | Focus border color for current date. | +| `$date-current-background` | Background for current date. | +| `$date-current-foreground` | Foreground for current date. | +| `$date-current-hover-background` | Hover background for current date. | +| `$date-current-focus-background` | Focus background for current date. | +| `$date-current-hover-foreground` | Hover foreground for current date. | +| `$date-current-focus-foreground` | Focus foreground for current date. | +| `$date-selected-current-border-color` | Border color for selected current date. | +| `$date-selected-current-hover-border-color` | Hover border color for selected current date. | +| `$date-selected-current-focus-border-color` | Focus border color for selected current date. | +| `$date-selected-current-background` | Background for selected current date. | +| `$date-selected-current-hover-background` | Hover background for selected current date. | +| `$date-selected-current-focus-background` | Focus background for selected current date. | +| `$date-selected-current-foreground` | Foreground for selected current date. | +| `$date-selected-current-hover-foreground` | Hover foreground for selected current date. | +| `$date-selected-current-focus-foreground` | Focus foreground for selected current date. | +| `$date-special-border-radius` | Border radius for special date. | +| `$date-special-border-color` | Border color for special date. | +| `$date-special-hover-border-color` | Hover border color for special date. | +| `$date-special-focus-border-color` | Focus border color for special date. | +| `$date-special-foreground` | Foreground for special date. Auto-derived from header-background. | +| `$date-special-background` | Background for special date. | +| `$date-special-hover-foreground` | Hover foreground for special date. | +| `$date-special-hover-background` | Hover background for special date. | +| `$date-special-focus-foreground` | Focus foreground for special date. | +| `$date-special-focus-background` | Focus background for special date. | +| `$date-special-range-border-color` | Border color for special date in range. | +| `$date-special-range-hover-border-color` | Hover border color for special date in range. | +| `$date-special-range-focus-border-color` | Focus border color for special date in range. | +| `$date-special-range-foreground` | Foreground for special date in range. | +| `$date-special-range-hover-foreground` | Hover foreground for special date in range. | +| `$date-special-range-focus-foreground` | Focus foreground for special date in range. | +| `$date-special-range-background` | Background for special date in range. | +| `$date-special-range-hover-background` | Hover background for special date in range. | +| `$date-special-range-focus-background` | Focus background for special date in range. | +| `$date-disabled-foreground` | Foreground for disabled dates. | +| `$date-disabled-range-foreground` | Foreground for disabled dates in selected range. | + +### Sass Theming + +Import the theming index, where the theme functions and component mixins live: ```scss @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 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. +Create a theme that extends . Specifying just `$header-background` and `$content-background` computes the related state colors and contrast foregrounds automatically, and you can still override any parameter: ```scss $custom-calendar-theme: calendar-theme( @@ -658,7 +517,7 @@ $custom-calendar-theme: calendar-theme( ); ``` -The last step is to pass the custom calendar theme: +Pass the custom theme: ```scss :host { @@ -666,13 +525,11 @@ The last step is to pass the custom calendar theme: } ``` - - -### Styling with Tailwind +### Tailwind -You can style the `calendar` using our custom Tailwind utility classes. Make sure to [set up Tailwind](/themes/misc/tailwind-classes) first. +Style the calendar with the custom Tailwind utility classes. First, [set up Tailwind](/themes/misc/tailwind-classes). -Along with the tailwind import in your global stylesheet, you can apply the desired theme utilities as follows: +Along with the Tailwind import in your global stylesheet, add the theme utilities: ```scss @import "tailwindcss"; @@ -680,15 +537,9 @@ Along with the tailwind import in your global stylesheet, you can apply the desi @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.). +The utility file includes both `light` and `dark` variants. Use `light-*` classes for the light theme and `dark-*` classes for the dark theme, appending the component name after the prefix — `light-calendar`, `dark-calendar`. These classes enable dynamic theme calculations, and you 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 . The syntax is as follows: +Find the full list of properties in the : ```html -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. +The exclamation mark (`!`) is required so the utility class takes precedence. Tailwind applies styles in layers, and without marking these styles as important they get overridden by the component's default theme. -At the end your calendar should look like this: + - +## Accessibility + +### Keyboard Interaction + +When the calendar is focused, use: + +| Key | Action | +| --- | --- | +| PageUp | Move to the previous month | +| PageDown | Move to the next month | +| Shift + PageUp | Move to the previous year | +| Shift + PageDown | Move to the next year | +| Home | Focus the first day of the month, or the first month/year in view | +| End | Focus the last day of the month, or the last month/year in view | +| Arrow keys | Navigate through days, months, or years in the active view (disabled dates are skipped) | +| Enter / Space | Select the focused day, or open/confirm the focused month or year | + +When the previous or next month button in the subheader is focused, press Space or Enter to scroll the next or previous month into view. When the month button is focused, Space or Enter opens the months view; when the year button is focused, it opens the decade view. + +Day navigation is continuous — arrow keys move through days across month boundaries and change the month in view as needed. + + +Tab navigation reaches these stops: the previous-month button, the month button, the year button, the next-month button, and one date in the grid (the selected date, the current date, or the first focusable date). In multi and range selection, only the first selected date is part of the tab sequence; move between dates in the grid with the arrow keys. + + +### Screen Readers / ARIA + +The calendar view exposes `role="grid"` and tracks the focused cell with `aria-activedescendant`, and sets `aria-multiselectable` when `selection` is `multi` or `range`. The navigation buttons and the month/year pickers expose `role="button"` with localized `aria-label`s, and off-screen live regions announce the presented month and year. All labels come from the calendar resource strings, so they follow the component's `locale` and can be overridden through `resourceStrings`. + +### Accessibility Compliance + +Infragistics evaluates Ignite UI for Angular components against Section 508 and WCAG guidelines — see the [Accessibility Compliance](/interactivity/accessibility-compliance) topic for the full component-by-component matrix. + +| Criterion | How the Calendar complies | +| --- | --- | +| [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG21/Understanding/keyboard.html) / [2.1.2 No Keyboard Trap](https://www.w3.org/WAI/WCAG21/Understanding/no-keyboard-trap.html) | Every view (days, months, years) is fully operable from the keyboard — paging, navigation, and selection all have a documented key binding, and arrow-key navigation moves continuously between days without trapping focus. | +| [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html) | The view area exposes `role="grid"` with `aria-activedescendant` for the focused cell and `aria-multiselectable` in `multi`/`range` selection; the navigation and picker buttons expose `role="button"` with localized `aria-label`s. | +| [4.1.3 Status Messages](https://www.w3.org/WAI/WCAG21/Understanding/status-messages.html) | Off-screen live regions announce the presented month and year as the user navigates, so the change is available to assistive technology without moving focus. | + +**Your responsibilities** + +- Keep sufficient color contrast between the calendar's background and its date/text colors when customizing the theme — see [Styling](#styling). +- Preserve a logical tab order when embedding the calendar in a custom layout, so the documented Tab stops (navigation buttons, then the grid) stay reachable in sequence. +- If you override `resourceStrings`, keep the replacement labels as descriptive as the defaults they replace. + +## Troubleshooting + +**How do I register the calendar with an `NgModule` instead of the standalone directives?** + +Before standalone components, the calendar was imported through `IgxCalendarModule`. Add it — together with `BrowserAnimationsModule` — to your `AppModule`: + +```typescript +// app.module.ts +import { BrowserAnimationsModule } from '@angular/platform-browser/animations'; +import { IgxCalendarModule } from 'igniteui-angular/calendar'; +// import { IgxCalendarModule } from '@infragistics/igniteui-angular'; for licensed package + +@NgModule({ + imports: [..., BrowserAnimationsModule, IgxCalendarModule], +}) +export class AppModule {} +``` + +Standalone imports (`IGX_CALENDAR_DIRECTIVES` or `IgxCalendarComponent`) are available as of `16.0.0` and are the recommended approach. + +**My Sass `@import` of the theming index no longer resolves.** + +Prior to Ignite UI for Angular version 13, import the themes from the legacy path instead of `@use "igniteui-angular/theming"`: + +```scss +@import '~igniteui-angular/lib/core/styles/themes/index'; +``` + +**Arrow keys don't move focus between days when I press Tab.** + +From version 10.2.0, Tab no longer steps through the days view; use the arrow keys to move between dates. From version 8.2.0, arrow-key navigation does not focus days outside the current month — it changes the month in view instead. ## API References -
+ - - - - - -## Additional Resources -
+## Additional Resources Our community is active and always welcoming to new ideas. - [Ignite UI for Angular **Forums**](https://www.infragistics.com/community/forums/f/ignite-ui-for-angular) -- [Ignite UI for Angular **GitHub**](https://github.com/IgniteUI/igniteui-angular) +- [Ignite UI for Angular **GitHub**](https://github.com/IgniteUI/igniteui-angular) \ No newline at end of file