diff --git a/docs/angular/src/content/en/components/carousel.mdx b/docs/angular/src/content/en/components/carousel.mdx deleted file mode 100644 index 6e1fddfaa6..0000000000 --- a/docs/angular/src/content/en/components/carousel.mdx +++ /dev/null @@ -1,646 +0,0 @@ ---- -title: Angular Carousel Component – Ignite UI for Angular - MIT license -description: Use Ignite UI for Angular Carousel component to navigate through a collection of slides, cards or page-based interfaces with endless programmatic features. Try it now -keywords: Ignite UI for Angular, UI controls, Angular widgets, web widgets, UI widgets, Angular, Native Angular Components Suite, Native Angular Controls, Native Angular Components Library, Angular Carousel component, Angular Carousel control -license: MIT -llms: - description: "Ignite UI for Angular Carousel is a responsive, lightweight component that provides the most flexible way to create slideshow-like web experience for users who navigate back and forth through a collection of images with text slides, links, and other html elements." ---- - -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 Carousel Component Overview - -
-Ignite UI for Angular Carousel is a responsive, lightweight component that provides the most flexible way to create slideshow-like web experience for users who navigate back and forth through a collection of images with text slides, links, and other html elements. - -The Angular Carousel component allows you to use animations, slide transitions, and customization so you can easily tweak the interface and build Angular custom carousel. -
- - -## Angular Carousel Example - -The Angular Carousel demo you see below shows slides containing only images. We’ve enabled navigation buttons allowing users to easily move from one slide to another – going back and forth. - - - -
- -## Getting Started with Ignite UI for Angular Carousel - -To get started with the Ignite UI for Angular Carousel component, first you need to install Ignite UI for Angular. In an existing Angular application, type the following command: - -```cmd -ng add igniteui-angular -``` - -For a complete introduction to the Ignite UI for Angular, read the [_getting started_](/general/getting-started) topic. - -The next step is to import the **IgxCarouselModule** in our **app.module.ts** file: - -```typescript -// app.module.ts - -import { IgxCarouselModule } from 'igniteui-angular/carousel'; -// import { IgxCarouselModule } from '@infragistics/igniteui-angular'; for licensed package - -@NgModule({ - ... - imports: [..., IgxCarouselModule], - ... -}) -export class AppModule {} -``` - - -Alternatively, as of `16.0.0` you can import the `IgxCarouselComponent` as a standalone dependency, or use the [`IGX_CAROUSEL_DIRECTIVES`](https://github.com/IgniteUI/igniteui-angular/blob/master/projects/igniteui-angular/carousel/src/carousel/public_api.ts) token to import the component and all of its supporting components and directives. - -```typescript -// home.component.ts - -import { IGX_CAROUSEL_DIRECTIVES } from 'igniteui-angular/carousel'; -// import { IGX_CAROUSEL_DIRECTIVES } from '@infragistics/igniteui-angular'; for licensed package - -@Component({ - selector: 'app-home', - template: ` - - -
- - - -
- - - `, - styleUrls: ['home.component.scss'], - standalone: true, - imports: [IGX_CAROUSEL_DIRECTIVES] - /* or imports: [IgxCarouselComponent, IgxSlideComponent] */ -}) -export class HomeComponent {} -``` - -Now that you have the Ignite UI for Angular Carousel module or directives imported, you can start using the `igx-carousel` component. - -## Using the Angular Carousel Component - -The Ignite UI for Angular Carousel component can be used as a full-screen element or situated inside another component. Also, the slides may feature any valid html content inside, including other Angular components. - -In this section we will go through the setup of the above defined **demo**. - -### Adding slides with *ngFor - -
- -If we have slides with the same type of content, the easiest approach is to use _\*ngFor_ to add them in the template. - -Since our slides are going to contain only images, we are going to create an array of objects in the **ts** file and use it to populate the **igx-carousel** with slides: - -```typescript -@Component({...}) -export class HomeComponent { - public slides = [ - { src: '/assets/images/carousel/ignite-ui-angular-indigo-design.png' }, - { src: '/assets/images/carousel/slider-image-chart.png' }, - { src: '/assets/images/carousel/ignite-ui-angular-charts.png' } - ]; -} -``` - -```html -
- - - -
- - - -
- - -
-``` - -## Angular Carousel Custom Examples - -### Configuring IgxCarousel - -
- -By default, the Carousel in Angular has its input property set to `true` (_looping occurs when the first slide comes after the last by navigating using the Next action, or when the last slide comes after the first by using the Previous action_). The looping behavior can be disabled by setting the value of the input to `false`. - -```html - - ... - -``` - -To keep track of each slide index, the carousel has indicators that are positioned at the `end` of the carousel by default. In order to change this behavior, use the property and assign it to `start`. - -```html - - ... - -``` - -By default, the displays its navigation buttons and indicators. Use the property to hide the indicators and the property to hide the navigation buttons. - -```html - - ... - -``` - -The supports vertical mode. Use the property to enable it. - -```html - - ... - -``` - -### Custom indicators - -
- -To add Angular custom carousel indicators we will have to use the , like this: - -```html -... - -
- -... -``` - -### Custom nav buttons - -To achieve this we will use the and directives: - -```html -... - - - - - - - -... -``` - - -This component uses Material Icons. Add the following link to your `index.html`: `` - - -### Slide containing other components - -
- -This carousel is going to contain slides with forms and images: - -```html -... -
- - - -
- - -
- - - person - - - - - - - lock - - - - -
-
- - - -
- -
- - - -
- - -
- - - search - - - - -
-
- - - -
- -
- - -
-... -``` - -#### Demo - - - -## Angular Carousel Animations - -Animated slide transitions provide the end-users a nice experience when interacting with the carousel. - -The carousel is configured to use the `slide` animation by default but it also supports `fade` as an alternative animation. - -The animations are configured through the input, like this: - -```html - -... - - -``` - -Setting `none` to the input disables carousel's animations. - -### Demo - -The demo below demonstrates the different types of animations, which the carousel supports. - - - -## Navigation - -
- -Transition and navigation are the most important carousel features. - -The navigation in the carousel can be handled by the user through navigation buttons, keyboard navigation and pan interaction on mobile devices. - -### Pan gestures - -
- -By default, the carousel can be used on any touch-enabled device. This is optional and can be changed by setting the property to `false`. - -The carousel [animations](/carousel#angular-carousel-animations) are fully supported on touch devices, which makes the carousel consistent with any platform and great when used in progressive web applications ([PWA](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps)). - -### Keyboard navigation - -
- -- Navigation buttons - - `Space`/`Enter` key - navigates to the next/previous slide. -- Indicators - - `Arrow Left` key - navigates to the previous (next in Right-to-Left mode) slide. - - `Arrow Right` key - navigates to the next (previous in Right-to-Left mode) slide. - - `Home` key - navigates to the first (last in Right-to-Left mode) slide. - - `End` key - navigates to the last (first in Right-to-Left mode) slide. - -### Automatic transitioning - -
- -The **IgxCarousel** can be easily configured to change the slides automatically, without any user interaction. This way you can create your own slideshow by only setting a transition interval to the property, which determines the amount of time in milliseconds between slides transition. - - -The automatic slide transitioning is not entirely user-independent by default. Positioning the mouse pointer over a slide will interrupt the current slide transition until the mouse pointer leaves the slide area. This can be prevented by setting property to `false`. - - -## Advanced Example - -
- -Let's create a fully automated carousel with looping enabled. Each slide will be synced with a in a list. Clicking on a list item will trigger a slide change. - -To achieve this goal, we have to do the following configurations to the carousel: - -- disable -- disable the buttons -- disable the carousel -- disable the on user interaction with the slide -- add transition - -Our carousel will look like this in the template: - -```html -... -
- - - - {/* Slides content goes here */} - - -
-... -``` - -We are ready with the carousel configuration. Now we need only to add a [list](/list) component and sync the both components: - -adding : - -```html -... -
- - - {/* Adding disabled classes when the list item index does not match the current slide index*/} - - {/* List item content goes here */} - - -
-... -``` - -syncing the components by hooking up on carousel's and list's events: - - -As of v15.1.0 `onSlideChanged` was renamed to `slideChanged`. Using `ng update` will automatically migrate your code prior to use the new event name. - - -```typescript - public ngOnInit() { - this.list.itemClicked.subscribe((args: IListItemClickEventArgs) => { - this.currentIndex = args.item.index; - this.carousel.select(this.carousel.get(this.currentIndex)); - }); - - this.carousel.slideChanged.subscribe((args: ISlideEventArgs) => { - this.currentIndex = args.slide.index; - }); - } -``` - -These configurations will have the following result: - - - -## Angular Carousel Styling - -### Carousel Theme Property Map - -When you modify a primary property, all related dependent properties are automatically updated to reflect the change: - -
- - - - - - - - - - -
- - {/* Material Theme Table */} -
- - | Primary Property | Dependent Property | Description | -| --- | --- | --- | -| **$button-background** | $button-hover-background | The background color of the button on hover. | -| | $button-arrow-color | The color of the button arrow. | -| | $button-disabled-background | The background color of the button when disabled. | -| | $indicator-focus-color (When $indicator-background is not provided) | The color of the indicator when focused. | -|**$button-hover-background** | $button-hover-arrow-color | The color of the button arrow on hover. | -| **$button-disabled-background** | $button-disabled-arrow-color | The color of the button arrow when disabled. | -|**$button-hover-arrow-color** | $button-focus-arrow-color | The color of the button arrow when focused. | -| **$button-focus-arrow-color** | $button-focus-border-color | The border color of the button when focused. | -|**$indicator-background** | $indicator-border-color | The color of the indicator border. | -| | $indicator-active-dot-color | The color of the indicator dot when active. | -| | $indicator-focus-color | The color of the indicator when focused. | -| **$indicator-active-dot-color** | $indicator-active-hover-dot-color | The color of the indicator when active and hovered. | -| | $indicator-active-border-color | The color of the indicator border when active. | -| **$indicator-dot-color** | $indicator-hover-dot-color | The color of the indicator dot on hover. | - -
- {/* Fluent Theme Table */} -
- - | Primary Property | Dependent Property | Description | -| --- | --- | --- | -| **$button-background** | $button-hover-background | The background color of the button on hover. | -| | $button-arrow-color | The color of the button arrow. | -| | $button-disabled-background | The background color of the button when disabled. | -| | $button-focus-border-color | The border color of the button when focused. | -| | $indicator-focus-color (When $indicator-background is not provided) | The color of the indicator when focused. | -| **$button-hover-background** | $button-hover-arrow-color | The color of the button arrow on hover. | -| **$button-disabled-background**| $button-disabled-arrow-color | The color of the button arrow when disabled. | -| **$button-hover-arrow-color** | $button-focus-arrow-color | The color of the button arrow when focused. | -| **$indicator-background**| $indicator-border-color | The color of the indicator border. | -| | $indicator-active-dot-color | The color of the indicator dot when active. | -| | $indicator-focus-color | The color of the indicator when focused. | -| **$indicator-active-dot-color** | $indicator-active-hover-dot-color | The color of the indicator when active and hovered. | -| | $indicator-active-border-color | The color of the indicator border when active. | -| **$indicator-dot-color** | $indicator-hover-dot-color | The color of the indicator dot on hover. | - -
- {/* Bootstrap Theme Table */} -
- - | Primary Property | Dependent Property | Description | -| --- | --- | --- | -| **$button-background** | $button-hover-background | The background color of the button on hover. | -| | $button-arrow-color | The color of the button arrow. | -| | $button-disabled-background | The background color of the button when disabled. | -| | $button-focus-border-color | The border color of the button when focused. | -| | $indicator-focus-color (When $indicator-background is not provided) | The color of the indicator when focused. | -| **$button-hover-background** | $button-hover-arrow-color | The color of the button arrow on hover. | -| **$button-disabled-background**| $button-disabled-arrow-color | The color of the button arrow when disabled. | -| **$button-hover-arrow-color** | $button-focus-arrow-color | The color of the button arrow when focused. | -| **$indicator-background**| $indicator-border-color | The color of the indicator border. | -| | $indicator-active-dot-color | The color of the indicator dot when active. | -| | $indicator-focus-color | The color of the indicator when focused. | -| **$indicator-active-dot-color** | $indicator-active-hover-dot-color | The color of the indicator when active and hovered. | -| | $indicator-active-border-color | The color of the indicator border when active. | -| **$indicator-dot-color** | $indicator-hover-dot-color | The color of the indicator dot on hover. | - -
- {/* Indigo Theme Table */} -
- - | Primary Property | Dependent Property | Description | -| --- | --- | --- | -| **$button-background** | $button-hover-background | The background color of the button on hover. | -| | $button-border-color | The border color of the button. | -| | $button-arrow-color | The color of the button arrow. | -| | $button-disabled-background | The background color of the button when disabled. | -| | $indicator-active-dot-color (When $indicator-background is not provided) | The color of the indicator dot when active. | -| **$button-hover-background** | $button-hover-arrow-color | The color of the button arrow on hover. | -| **$button-disabled-background**| $button-disabled-arrow-color | The color of the button arrow when disabled. | -| **$button-border-color** | $button-hover-border-color | The border color of the button on hover. | -| **$button-hover-arrow-color**| $button-focus-arrow-color | The color of the button arrow when focused. | -| **$indicator-background** | $indicator-dot-color | The color of the indicator dot. | -| | $indicator-active-dot-color | The color of the indicator dot when active. | -| **$indicator-dot-color** | $indicator-hover-dot-color | The color of the indicator dot on hover. | -| | $indicator-border-color | The color of the indicator border. | -| **$indicator-active-dot-color** | $indicator-active-hover-dot-color | The color of the indicator when active and hovered. | -| | $indicator-active-border-color | The color of the indicator border when active. | -| | $button-focus-border-color | The border color of the button when focused. | -| **$indicator-active-hover-dot-color** | $indicator-focus-color | The color of the indicator when focused. | - -
- -
-
- -Using the [Ignite UI for Angular Theming](/themes), we can greatly alter the `carousel` appearance. - -First, in order to use the functions exposed by the theme engine, we need to import the `index` file in our style file: - -```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 providing just a few base parameters like `$button-background` and `$indicator-background`, the theme will generate the appropriate state-specific colors and contrasting foregrounds. You can also override any of the available parameters if you want more control over the appearance. - -```scss -$carousel-theme: carousel-theme( - $button-background: #7c32dd, - $indicator-background: #7c32dd, -); -``` - -The last step is to include the component's theme. - -```scss -:host { - @include tokens($carousel-theme); -} -``` - -### Demo - -The sample below demonstrates a simple styling applied through the [Ignite UI for Angular Theming](/themes). - - - -### Styling with Tailwind - -You can style the `carousel` using our custom 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: - -```scss -@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-carousel`, `dark-carousel`. - -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 . The syntax is as follows: - -```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. - - -At the end your carousel should look like this: - - - -## Accessibility - -### WAI-ARIA Roles, States, and Properties - -- The Carousel base element role is [`region`](https://www.w3.org/TR/wai-aria-1.1/#region) - section containing content that is relevant to specific purpose and users will likely want to be able to navigate easily. -- Carousel indicators are with role [`tab`](https://www.w3.org/TR/wai-aria-1.1/#tab) - grouping label providing a mechanism for selecting the tab content that is to be rendered to the user -- The element that serves as the container for the set of tabs (carousel indicators) role is set to [`tablist`](https://www.w3.org/TR/wai-aria-1.1/#tab). -- Each slide element is set with role [`tabpanel`](https://www.w3.org/TR/wai-aria-1.1/#tabpanel). -- The element that serves as the container for the set of igx-slides is set with [aria-live](https://www.w3.org/TR/wai-aria-1.1/#aria-live)="polite". Both options are - - **off**: if the carousel is automatically rotating. - - **polite**: if the carousel is NOT automatically rotating. - -### ARIA support - -#### **Carousel component** - -##### **Attributes** - -- [aria-roledescription](https://www.w3.org/TR/wai-aria-1.1/#aria-roledescription) set to 'carousel'. -- [aria-selected](https://www.w3.org/TR/wai-aria/states_and_properties#aria-selected)- set to _true_ or _false_ based on the active slide. -- [aria-controls](https://www.w3.org/TR/wai-aria-1.1/#aria-controls) - set a slide index whose content is controlled by the current element. -- [aria-live](https://www.w3.org/TR/wai-aria-1.1/#aria-live) - used to set the priority with which screen reader should treat updates to live regions - the possible settings are: **off** and **polite**. The default setting is **polite**. When the option set, the **aria-live** attribute would be set to **off**. -- [aria-label](https://www.w3.org/TR/wai-aria/states_and_properties#aria-label) slide based. -- aria-label (buttons) - - aria-label - for previous slide. - - aria-label - for next slide. - -#### **Slide component** - -##### **Roles** - -- [attr.role="tabpanel"](https://www.w3.org/TR/wai-aria-1.1/#tabpanel) - container for the resources associated with a tab, where each tab is contained in a tablist. - -##### **Attributes** - -- id - follows the pattern "panel-${this.index}" -- [aria-labelledby](https://www.w3.org/TR/wai-aria/#aria-labelledby) follows the pattern "tab-${this.index}-${this.total}" -- [aria-selected](https://www.w3.org/TR/wai-aria-1.1/#aria-selected) set **active** slide. Indicates the current **selected** state of a particular slide element. - -## API References -
-- -- -- -- -- -## Theming 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) diff --git a/docs/angular/src/content/en/components/general/cli/component-templates.mdx b/docs/angular/src/content/en/components/general/cli/component-templates.mdx index 1b4d9466c2..1a7209d7ba 100644 --- a/docs/angular/src/content/en/components/general/cli/component-templates.mdx +++ b/docs/angular/src/content/en/components/general/cli/component-templates.mdx @@ -41,7 +41,7 @@ These templates generate components into an existing Angular workspace only. The | geographic-map | Ignite UI Schematics collection:
ng g @igniteui/angular-schematics:c geographic-map newGeographicMap
Ignite UI CLI:
ig add geographic-map newGeographicMap
Basic IgxGeographicMap.
| [IgxGeographicMap](../../geo-map.mdx) displaying geo-spatial data on geographic imagery maps. | | Layouts | | | | dock-manager | Ignite UI Schematics collection:
ng g @igniteui/angular-schematics:c dock-manager newDockManager
Ignite UI CLI:
ig add dock-manager newDockManager
Basic IgcDockManager.
| [IgcDockManager](../../dock-manager.mdx) with nine content slots. | -| carousel | Ignite UI Schematics collection:
ng g @igniteui/angular-schematics:c carousel newCarousel
Ignite UI CLI:
ig add carousel newCarousel
Basic IgxCarousel.
| [IgxCarousel](../../carousel.mdx) cycling through a series of images. | +| carousel | Ignite UI Schematics collection:
ng g @igniteui/angular-schematics:c carousel newCarousel
Ignite UI CLI:
ig add carousel newCarousel
Basic IgxCarousel.
| [IgxCarousel](../../layouts/carousel.mdx) cycling through a series of images. | | tabs | Ignite UI Schematics collection:
ng g @igniteui/angular-schematics:c tabs newTabs
Ignite UI CLI:
ig add tabs newTabs
Basic IgxTabs.
| [IgxTabs](../../tabs.mdx) component that includes three customized tab-groups. | | bottom-nav | Ignite UI Schematics collection:
ng g @igniteui/angular-schematics:c bottom-nav newBottomNav
Ignite UI CLI:
ig add bottom-nav newBottomNav
Three item bottom-nav template.
| Three item bottom [navbar](../../navbar.mdx) template. | | accordion | Ignite UI Schematics collection:
ng g @igniteui/angular-schematics:c accordion newAccordion
Ignite UI CLI:
ig add accordion newAccordion
Basic IgxAccordion sample.
| [IgxAccordion](../../accordion.mdx) with multiple collapsible panels in a single container. | diff --git a/docs/angular/src/content/en/components/layouts/carousel.mdx b/docs/angular/src/content/en/components/layouts/carousel.mdx new file mode 100644 index 0000000000..f81d52d380 --- /dev/null +++ b/docs/angular/src/content/en/components/layouts/carousel.mdx @@ -0,0 +1,444 @@ +--- +title: "Carousel | Ignite UI for {Framework}" +description: "Use the Ignite UI for Angular Carousel component to show slide-based content with navigation, indicators, animation, and automatic transitions." +keywords: "Ignite UI for Angular, UI controls, Angular widgets, web widgets, UI widgets, Angular, Native Angular Components Suite, Native Angular Controls, Native Angular Components Library, Angular Carousel component, Angular Carousel control" +license: MIT +mentionedTypes: ["Carousel", "CarouselSlide", "CarouselIndicator", "Icon", "Input", "Button"] +relatedComponents: ["Tabs", "Stepper"] +last_updated: "2026-08-17" +llms: + description: "The Ignite UI for Angular Carousel is a slide-based layout component for presenting images, cards, or other content with navigation controls and indicators." +--- +import DocsAside from 'igniteui-astro-components/components/mdx/DocsAside.astro'; +import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; +import Anatomy from 'igniteui-astro-components/components/mdx/Anatomy.astro'; +import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; +import Faq from 'igniteui-astro-components/components/mdx/Faq.astro'; +import FaqItem from 'igniteui-astro-components/components/mdx/FaqItem.astro'; +import { Image } from 'astro:assets'; +import carouselAnatomy from '@xplat-images/anatomy-content-light/carousel-lt-a.png'; +import carouselDo1 from '@xplat-images/carousel/carousel_do1.png'; +import carouselDo1_2x from '@xplat-images/carousel/carousel_do1@2x.png'; +import carouselDo2 from '@xplat-images/carousel/carousel_do2.png'; +import carouselDo2_2x from '@xplat-images/carousel/carousel_do2@2x.png'; +import carouselDoNot1 from '@xplat-images/carousel/carousel_do_not1.png'; +import carouselDoNot1_2x from '@xplat-images/carousel/carousel_do_not1@2x.png'; +import carouselDoNot2 from '@xplat-images/carousel/carousel_do_not2.png'; +import carouselDoNot2_2x from '@xplat-images/carousel/carousel_do_not2@2x.png'; + +# Carousel Component + +The Ignite UI for Angular Carousel is a slide-based layout component for presenting images, cards, or other content with navigation controls and indicators. + +Use the Carousel when users need to browse a small collection of related slides one at a time, with optional animation, custom navigation, and automatic transitions. + +## Live Demo + + + +## Anatomy + +The Carousel component is composed of a host element, projected slides, navigation controls, and indicators that select the active slide. + + + + + +1. Slides: The content panels that cycle through the carousel, each displaying an image, text, or media.
+2. Navigation Icon Buttons: Navigate previous and next slides.
+3. Indicators: Show the total number of slides and highlight the currently active one. + +```text +igx-carousel // host - coordinates slides, navigation, and indicators +|- igx-slide // slide item +|- ng-template[igxCarouselIndicator] // optional custom indicator template +|- ng-template[igxCarouselPrevButton] // optional previous navigation template +`- ng-template[igxCarouselNextButton] // optional next navigation template +``` + +## Getting Started + +The Angular Carousel requires the carousel component, slide component, and theme stylesheet before you declare slides. + +### Prerequisites and Version Compatibility + +Install Ignite UI for Angular and configure the theme from the [Getting Started](../general-getting-started.mdx) topic before adding the Carousel to an application. + +Import the Carousel directives and the Ignite UI theme stylesheet. + +```ts +import { Component } from '@angular/core'; +import { IGX_CAROUSEL_DIRECTIVES } from 'igniteui-angular/carousel'; + +@Component({ + selector: 'app-carousel-sample', + imports: [IGX_CAROUSEL_DIRECTIVES], + template: ` + + + Ignite UI Indigo Design + + + `, +}) +export class CarouselSampleComponent {} +``` + +## Usage + +The Angular Carousel is configured by placing slide components inside the host and then enabling the navigation, indicator, and transition behavior your layout needs. + +### Slides + +Use the selector to wrap your slides. The slides may contain images, text, forms, or other components. + +```html + + + Ignite UI Indigo Design + + + Chart preview + + + Ignite UI Charts + + +``` + +### Active Slide + +### Configuration + +Use the Carousel configuration properties to control looping, indicator placement, navigation visibility, and orientation. + +Use the input to control whether the Carousel wraps from the last slide to the first slide, or from the first slide to the last slide. + +```html + + ... + +``` + +Use the input to change where the indicators are positioned. + +```html + + ... + +``` + +Use to hide the indicators and to hide the navigation buttons. + +```html + + ... + +``` + +Use the input to display the Carousel in vertical mode. + +```html + + ... + +``` + +### Custom Indicators + +Use the template directive to replace the default indicator content. + +```html + + +
+ + + Ignite UI Indigo Design + + + Chart preview + + +``` + +### Custom Navigation Buttons + +Use the and template directives to provide custom navigation button content. + +```html + + + + + + + + ... + +``` + +### Slide Content + +Place forms, images, and other components inside a slide when each step in the Carousel needs richer content. + +```html + + +
+ Sign up +
+ + + person + + + + + + password + + + + +
+
+ + +``` + + + +### Animations + +Set the input to change the slide transition animation. + +```html + + ... + +``` + + + +### Touch Gestures + +Use the Carousel on touch-enabled devices when swipe navigation should mirror the configured slide transition. + +Set the input to `false` when pan gestures should be disabled. + +```html + + ... + +``` + +### Automatic Transitioning + +Set the input to create an automatic slideshow, and set to `false` when transitioning should not pause on interaction. + +```html + + ... + +``` + +### Thumbnail Indicators + +### Synced List Navigation + +Use a linked list when Angular Carousel navigation needs a visible list of slide labels instead of thumbnail indicators. + +```html + + + ... + + +``` + + + +### Do/Don't + +**When to use:** Use Carousel when the interface needs to show a compact set of related visual or mixed-content slides that users browse one at a time. + +**When not to use:** Do not use Carousel for primary navigation, long sequential workflows, or content users must compare side by side. Use [Tabs](../tabs.mdx) for switching between named sections, or [Stepper](../stepper.mdx) for guided sequential tasks. + +
+ + + + + + + + + + + + + + + + + +
DoDon't
Angular Carousel do guidanceAngular Carousel don't guidance
Angular Carousel do guidance with visual slidesAngular Carousel don't guidance with dense content
+
+ +## Properties + +The following Carousel properties cover the configuration used most often in slide-based layouts. + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| | `boolean` | `true` | Enables looping between the first and last slides. | +| | `boolean` | `true` | Shows or hides the previous and next navigation buttons. | +| | `boolean` | `true` | Shows or hides the slide indicators. | +| | `string` | See API | Controls where the indicators are positioned. | +| | `number` | See API | Sets the automatic transition interval in milliseconds. | +| | `boolean` | See API | Controls whether automatic transitioning pauses on interaction. | +| | `boolean` | `false` | Displays the Carousel in vertical orientation. | +| | `boolean` | See API | Enables or disables pan gestures. | +| | `string` | See API | Sets the slide transition animation. | + +## Styling + +The Carousel can be styled through its exposed parts, custom indicator content, and custom navigation slots. + + + +### Sass Theming + +Use Sass theming when the Carousel needs theme-level changes that should stay consistent across the application. + +{/*TODO: Add the verified Carousel Sass theme variable table.*/} + +### Parts and Slots + +Use the exposed slots and parts when only a specific Carousel surface needs custom content or local styling. + +| Surface | What it customizes | +| --- | --- | +| | Replaces the previous navigation button content. | +| | Replaces the next navigation button content. | +| | Replaces the default slide indicator content. | + +### Styling with Tailwind + +## Accessibility + +The Angular Carousel exposes carousel, slide, and indicator semantics for keyboard and assistive technology users. + +### Keyboard Interaction + +| Key | Action | +| --- | --- | +| Space or Enter | Activates the focused navigation button. | +| Arrow Left | Moves indicator focus to the previous slide indicator, or to the next indicator in right-to-left mode. | +| Arrow Right | Moves indicator focus to the next slide indicator, or to the previous indicator in right-to-left mode. | +| Home | Moves indicator focus to the first slide indicator, or to the last indicator in right-to-left mode. | +| End | Moves indicator focus to the last slide indicator, or to the first indicator in right-to-left mode. | + +### Screen Readers / ARIA + +The Carousel provides ARIA roles and state for the host, slides, indicators, and navigation controls. + +| Element | Role or attribute | Purpose | +| --- | --- | --- | +| Carousel host | `role="region"` and `aria-roledescription="carousel"` | Identifies the Carousel as a navigable content region. | +| Slides container | `aria-live="polite"` or `aria-live="off"` | Announces slide changes when automatic playback is not active. | +| Slide | `role="tabpanel"`, `aria-roledescription="slide"`, and `aria-label` | Identifies each slide and its position in the set. | +| Indicator container | `role="tablist"` | Groups the slide indicators. | +| Indicator | `role="tab"`, `aria-label`, and `aria-selected` | Identifies the slide represented by the indicator and whether it is selected. | +| Navigation buttons | `aria-label` | Names the previous and next slide actions. | + +### Accessibility Compliance + +Infragistics documents Ignite UI for Angular accessibility support for Section 508 and WCAG 2.1 guideline areas in the [Accessibility Compliance](../interactivity/accessibility-compliance.mdx) topic. + +| Criterion | How the component complies | +| --- | --- | +| [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html) | Navigation buttons and indicators support keyboard operation. | +| [2.1.2 No Keyboard Trap](https://www.w3.org/WAI/WCAG22/Understanding/no-keyboard-trap.html) | Carousel keyboard interaction does not require focus to remain inside the component. | +| [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) | The host, slides, indicators, and navigation controls expose roles, names, and selected state. | + +Application authors still need to provide meaningful slide content, image alternative text, and enough contrast for custom indicator or navigation content. + +## Troubleshooting + +Use this section to check content and interaction boundaries before treating Carousel as a general navigation or comparison layout. + +### Known Limitations + +The Carousel is intended for a compact set of related slides and can become hard to scan when it contains long, unrelated, or comparison-heavy content. + +## API References + +The generated API references list the complete Carousel, slide, indicator, and supporting component APIs. + + + + + + + + + + +## Dependencies + +The Carousel examples rely on the Carousel slide and indicator types, the theme stylesheet, and supporting input, icon, and button components when those components appear inside slides or navigation slots. + +## Additional Resources + +Use these resources for broader product support and source information. + +- [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) + +## Related Components + +Use these related layout components when Carousel is not the best match for the interaction model. + +- [Tabs](../tabs.mdx) - Use Tabs when users need to switch between named sections without slide-style navigation. +- [Stepper](../stepper.mdx) - Use Stepper when users need to complete a guided sequence of steps. + +## FAQ + + + + Use Carousel for a compact set of visual or mixed-content slides. Use Tabs when each section needs a persistent label and direct random access. + + + + Yes. Place forms, images, buttons, and other components inside a slide when each slide needs richer content. + + + + Set the interval property to the number of milliseconds between slide transitions. Use disablePauseOnInteraction when playback should continue during pointer or keyboard interaction. + + diff --git a/docs/angular/src/content/en/components/themes/roundness.mdx b/docs/angular/src/content/en/components/themes/roundness.mdx index 36eb3f72e4..16409836bd 100644 --- a/docs/angular/src/content/en/components/themes/roundness.mdx +++ b/docs/angular/src/content/en/components/themes/roundness.mdx @@ -20,7 +20,7 @@ Many Ignite UI components have predefined minimum and maximum border-radius valu When you set `--ig-radius-factor` to 0, the component uses its minimum border-radius and will appear more block-like with sharp corners. When set to 1, the component uses its maximum predefined border-radius and will appear rounded. Here is a list of the components that have predefined minimum and maximum border-radius values and can be modified using the `--ig-radius-factor` variable:
-• [Action Strip](/action-strip) • [Button](/button) • [Button Group](/components/inputs/button-group) • [Calendar](/calendar) • [Card](/card) • [Carousel](/carousel) • [Checkbox](/checkbox) • [Chip](/chip) • [Combo](/combo) • [Date Picker](/date-picker) • [Date Range Picker](/date-range-picker) • [Grid](/grid/grid) • [Input Group](/input-group) • [Linear Progress](/linear-progress) • [List](/list) • [Month Picker](/month-picker) • [Navigation Drawer](/navdrawer) • [Radio](/radio-button) • [Ripple](/ripple) • [Snackbar](/snackbar) • [Switch](/switch) • [Toast](/toast) +• [Action Strip](/action-strip) • [Button](/button) • [Button Group](/components/inputs/button-group) • [Calendar](/calendar) • [Card](/card) • [Carousel](../layouts/carousel.mdx) • [Checkbox](/checkbox) • [Chip](/chip) • [Combo](/combo) • [Date Picker](/date-picker) • [Date Range Picker](/date-range-picker) • [Grid](/grid/grid) • [Input Group](/input-group) • [Linear Progress](/linear-progress) • [List](/list) • [Month Picker](/month-picker) • [Navigation Drawer](/navdrawer) • [Radio](/radio-button) • [Ripple](/ripple) • [Snackbar](/snackbar) • [Switch](/switch) • [Toast](/toast) ## Usage diff --git a/docs/angular/src/content/en/images/anatomy-content-light/carousel-lt-a.png b/docs/angular/src/content/en/images/anatomy-content-light/carousel-lt-a.png new file mode 100644 index 0000000000..708f22598d Binary files /dev/null and b/docs/angular/src/content/en/images/anatomy-content-light/carousel-lt-a.png differ diff --git a/docs/angular/src/content/en/images/carousel/carousel_do1.png b/docs/angular/src/content/en/images/carousel/carousel_do1.png new file mode 100644 index 0000000000..b4f0d0636b Binary files /dev/null and b/docs/angular/src/content/en/images/carousel/carousel_do1.png differ diff --git a/docs/angular/src/content/en/images/carousel/carousel_do1@2x.png b/docs/angular/src/content/en/images/carousel/carousel_do1@2x.png new file mode 100644 index 0000000000..cb4dda5df3 Binary files /dev/null and b/docs/angular/src/content/en/images/carousel/carousel_do1@2x.png differ diff --git a/docs/angular/src/content/en/images/carousel/carousel_do2.png b/docs/angular/src/content/en/images/carousel/carousel_do2.png new file mode 100644 index 0000000000..4a4face6b5 Binary files /dev/null and b/docs/angular/src/content/en/images/carousel/carousel_do2.png differ diff --git a/docs/angular/src/content/en/images/carousel/carousel_do2@2x.png b/docs/angular/src/content/en/images/carousel/carousel_do2@2x.png new file mode 100644 index 0000000000..b723b52381 Binary files /dev/null and b/docs/angular/src/content/en/images/carousel/carousel_do2@2x.png differ diff --git a/docs/angular/src/content/en/images/carousel/carousel_do_not1.png b/docs/angular/src/content/en/images/carousel/carousel_do_not1.png new file mode 100644 index 0000000000..fcab971b8b Binary files /dev/null and b/docs/angular/src/content/en/images/carousel/carousel_do_not1.png differ diff --git a/docs/angular/src/content/en/images/carousel/carousel_do_not1@2x.png b/docs/angular/src/content/en/images/carousel/carousel_do_not1@2x.png new file mode 100644 index 0000000000..eaf2ae7256 Binary files /dev/null and b/docs/angular/src/content/en/images/carousel/carousel_do_not1@2x.png differ diff --git a/docs/angular/src/content/en/images/carousel/carousel_do_not2.png b/docs/angular/src/content/en/images/carousel/carousel_do_not2.png new file mode 100644 index 0000000000..3703918763 Binary files /dev/null and b/docs/angular/src/content/en/images/carousel/carousel_do_not2.png differ diff --git a/docs/angular/src/content/en/images/carousel/carousel_do_not2@2x.png b/docs/angular/src/content/en/images/carousel/carousel_do_not2@2x.png new file mode 100644 index 0000000000..e5a6a9d1ac Binary files /dev/null and b/docs/angular/src/content/en/images/carousel/carousel_do_not2@2x.png differ diff --git a/docs/xplat/src/assets/images/carousel/carousel_do1.png b/docs/xplat/src/assets/images/carousel/carousel_do1.png new file mode 100644 index 0000000000..b4f0d0636b Binary files /dev/null and b/docs/xplat/src/assets/images/carousel/carousel_do1.png differ diff --git a/docs/xplat/src/assets/images/carousel/carousel_do1@2x.png b/docs/xplat/src/assets/images/carousel/carousel_do1@2x.png new file mode 100644 index 0000000000..cb4dda5df3 Binary files /dev/null and b/docs/xplat/src/assets/images/carousel/carousel_do1@2x.png differ diff --git a/docs/xplat/src/assets/images/carousel/carousel_do2.png b/docs/xplat/src/assets/images/carousel/carousel_do2.png new file mode 100644 index 0000000000..4a4face6b5 Binary files /dev/null and b/docs/xplat/src/assets/images/carousel/carousel_do2.png differ diff --git a/docs/xplat/src/assets/images/carousel/carousel_do2@2x.png b/docs/xplat/src/assets/images/carousel/carousel_do2@2x.png new file mode 100644 index 0000000000..b723b52381 Binary files /dev/null and b/docs/xplat/src/assets/images/carousel/carousel_do2@2x.png differ diff --git a/docs/xplat/src/assets/images/carousel/carousel_do_not1.png b/docs/xplat/src/assets/images/carousel/carousel_do_not1.png new file mode 100644 index 0000000000..fcab971b8b Binary files /dev/null and b/docs/xplat/src/assets/images/carousel/carousel_do_not1.png differ diff --git a/docs/xplat/src/assets/images/carousel/carousel_do_not1@2x.png b/docs/xplat/src/assets/images/carousel/carousel_do_not1@2x.png new file mode 100644 index 0000000000..eaf2ae7256 Binary files /dev/null and b/docs/xplat/src/assets/images/carousel/carousel_do_not1@2x.png differ diff --git a/docs/xplat/src/assets/images/carousel/carousel_do_not2.png b/docs/xplat/src/assets/images/carousel/carousel_do_not2.png new file mode 100644 index 0000000000..3703918763 Binary files /dev/null and b/docs/xplat/src/assets/images/carousel/carousel_do_not2.png differ diff --git a/docs/xplat/src/assets/images/carousel/carousel_do_not2@2x.png b/docs/xplat/src/assets/images/carousel/carousel_do_not2@2x.png new file mode 100644 index 0000000000..e5a6a9d1ac Binary files /dev/null and b/docs/xplat/src/assets/images/carousel/carousel_do_not2@2x.png differ diff --git a/docs/xplat/src/content/en/components/layouts/carousel.mdx b/docs/xplat/src/content/en/components/layouts/carousel.mdx index b0bf8c22dc..4e4608e8a5 100644 --- a/docs/xplat/src/content/en/components/layouts/carousel.mdx +++ b/docs/xplat/src/content/en/components/layouts/carousel.mdx @@ -1,40 +1,113 @@ --- -title: "{Platform} Carousel | Infragistics" -description: Use {ProductName} Carousel component to navigate through a collection of slides, cards or page-based interfaces with endless programmatic features. Try it now +title: "Carousel | Ignite UI for {Framework}" +description: "Use the {ProductName} Carousel component to show slide-based content with navigation, indicators, animation, and automatic transitions." keywords: "{ProductName}, UI controls, {Platform} widgets, web widgets, UI widgets, {Platform}, Native {Platform} Components Suite, Native {Platform} Controls, Native {Platform} Components Library, {Platform} Carousel component, {Platform} Carousel control" license: MIT -mentionedTypes: ["Carousel"] +mentionedTypes: ["Carousel", "CarouselSlide", "CarouselIndicator", "Icon", "Input", "Button"] +relatedComponents: ["Tabs", "Stepper"] +last_updated: "2026-08-17" llms: - description: "The {ProductName} Carousel is a responsive, lightweight component that provides the most flexible way to create slideshow-like web experience for users who navigate back and forth through a collection of images with text slides, links, and other html elements." + description: "The {ProductName} Carousel is a slide-based layout component for presenting images, cards, or other content with navigation controls and indicators." --- import DocsAside from 'igniteui-astro-components/components/mdx/DocsAside.astro'; import PlatformBlock from 'igniteui-astro-components/components/mdx/PlatformBlock.astro'; import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; +import Anatomy from 'igniteui-astro-components/components/mdx/Anatomy.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; +import Faq from 'igniteui-astro-components/components/mdx/Faq.astro'; +import FaqItem from 'igniteui-astro-components/components/mdx/FaqItem.astro'; +import { Image } from 'astro:assets'; +import carouselAnatomy from '@xplat-images/anatomy-content-light/carousel-lt-a.png'; +import carouselDo1 from '@xplat-images/carousel/carousel_do1.png'; +import carouselDo1_2x from '@xplat-images/carousel/carousel_do1@2x.png'; +import carouselDo2 from '@xplat-images/carousel/carousel_do2.png'; +import carouselDo2_2x from '@xplat-images/carousel/carousel_do2@2x.png'; +import carouselDoNot1 from '@xplat-images/carousel/carousel_do_not1.png'; +import carouselDoNot1_2x from '@xplat-images/carousel/carousel_do_not1@2x.png'; +import carouselDoNot2 from '@xplat-images/carousel/carousel_do_not2.png'; +import carouselDoNot2_2x from '@xplat-images/carousel/carousel_do_not2@2x.png'; +# Carousel Component -# {Platform} Carousel Overview +The {ProductName} Carousel is a slide-based layout component for presenting images, cards, or other content with navigation controls and indicators. -The {ProductName} Carousel is a responsive, lightweight component that provides the most flexible way to create slideshow-like web experience for users who navigate back and forth through a collection of images with text slides, links, and other html elements. +Use the Carousel when users need to browse a small collection of related slides one at a time, with optional animation, custom navigation, and automatic transitions. -The {Platform} Carousel component allows you to use animations, slide transitions, and customization so you can easily tweak the interface and build {Platform} custom carousel. +## Live Demo -## {Platform} Carousel Example -The {Platform} Carousel demo you see below shows slides containing only images. + - + -## Usage + - + + + + + + +## Anatomy + +The Carousel component is composed of a host element, projected slides, navigation controls, and indicators that select the active slide. + + + + -```cmd -npm install {PackageWebComponents} +1. Slides: The content panels that cycle through the carousel, each displaying an image, text, or media.
+2. Navigation Icon Buttons: Navigate previous and next slides.
+3. Indicators: Show the total number of slides and highlight the currently active one. + + + +```text +igc-carousel // host - coordinates slides, navigation, and indicators +|- igc-carousel-slide // slide item +|- igc-carousel-indicator // optional custom indicator for a slide +|- [slot="previous-button"] // optional custom previous navigation content +`- [slot="next-button"] // optional custom next navigation content ``` -You will then need to import the , its necessary CSS, and register its module, like so: + + + + +```text +igx-carousel // host - coordinates slides, navigation, and indicators +|- igx-slide // slide item +|- ng-template[igxCarouselIndicator] // optional custom indicator template +|- ng-template[igxCarouselPrevButton] // optional previous navigation template +`- ng-template[igxCarouselNextButton] // optional next navigation template +``` + + + +## Getting Started + +The {Platform} Carousel requires the carousel component, slide component, and theme stylesheet before you declare slides. + +### Prerequisites and Version Compatibility + +Install {ProductName} and configure the theme from the [Getting Started](../general-getting-started.mdx) topic before adding the Carousel to an application. + + + +Import and register the component and its theme. ```ts import { defineComponents, IgcCarouselComponent } from "igniteui-webcomponents"; @@ -47,13 +120,7 @@ defineComponents(IgcCarouselComponent); -First, you need to the install the corresponding {ProductName} npm package by running the following command: - -```cmd -npm install igniteui-react -``` - -You will then need to import the , its necessary CSS, and register its module, like so: +Import the Carousel wrapper components and the theme stylesheet. ```tsx import { IgrCarousel, IgrCarouselSlide } from 'igniteui-react'; @@ -64,40 +131,63 @@ import 'igniteui-webcomponents/themes/light/bootstrap.css'; -Before using the , you need to register it as follows: +Register the Carousel module and add the theme stylesheet to the application host page. ```csharp // in Program.cs file - builder.Services.AddIgniteUIBlazor(typeof(IgbCarouselModule)); ``` -You will also need to link an additional CSS file to apply the styling to the component. The following needs to be placed in the **wwwroot/index.html** file in a **Blazor Web Assembly** project or the **Pages/_Host.cshtml** file in a **Blazor Server** project: - ```razor ``` -For a complete introduction to the {ProductName}, read the [**Getting Started**](../general-getting-started.mdx) topic. + + +Import the Carousel directives and the Ignite UI theme stylesheet. + +```ts +import { Component } from '@angular/core'; +import { IGX_CAROUSEL_DIRECTIVES } from 'igniteui-angular/carousel'; + +@Component({ + selector: 'app-carousel-sample', + imports: [IGX_CAROUSEL_DIRECTIVES], + template: ` + + + Ignite UI Indigo Design + + + `, +}) +export class CarouselSampleComponent {} +``` + + + +## Usage + +The {Platform} Carousel is configured by placing slide components inside the host and then enabling the navigation, indicator, and transition behavior your layout needs. -Now that you have the {ProductName} Carousel imported, you can start with a basic configuration of the and its slides. +### Slides -Use the selector to wrap your slides. The slides may feature any valid html content inside, including other components. +Use the selector to wrap your slides. The slides may contain images, text, forms, or other components. ```html - + Ignite UI Indigo Design - + Chart preview - + Ignite UI Charts ``` @@ -109,13 +199,13 @@ Use the selector to wrap your slides. The ```tsx - + Ignite UI Indigo Design - + Chart preview - + Ignite UI Charts ``` @@ -127,26 +217,47 @@ Use the selector to wrap your slides. The ```razor - ignite-ui-angular-indigo-design + Ignite UI Indigo Design - slider-image-chart + Chart preview - ignite-ui-angular-charts + Ignite UI Charts ``` -If you want a slide to be active by default, use the attribute: + + +```html + + + Ignite UI Indigo Design + + + Chart preview + + + Ignite UI Charts + + +``` + + + +### Active Slide + + + +Set the property on the slide that should be selected when the Carousel renders. ```html - ... ... @@ -162,7 +273,6 @@ If you want a slide to be active by default, use the -If no active slide is set, the first one will be set by default. If there are multiple active slides on initial rendering or subsequent updates, only the last one will be taken into account. +If no active slide is set, the first one is active by default. If multiple slides are active during initial rendering or later updates, the last active slide is used. -## Examples + + +### Configuration -### Carousel Configuration +Use the Carousel configuration properties to control looping, indicator placement, navigation visibility, and orientation. -By default, the has its property set to **false** (looping occurs when the first slide comes after the last by navigating using the Next action, or when the last slide comes after the first by using the Previous action). The looping behavior can be disabled by setting the value of the property to **true**. + + + + + + + + +The property disables the looping behavior that moves from the last slide to the first slide, or from the first slide to the last slide. @@ -230,7 +349,7 @@ By default, the has its property and assign it to `start`. +Use the property to change where the indicators are positioned. @@ -262,7 +381,7 @@ To keep track of each slide index, the carousel has indicators that are position -By default, the displays its navigation buttons and indicators. Use the property to hide the indicators and the property to hide the navigation buttons. +Use to hide the indicators and to hide the navigation buttons. @@ -294,7 +413,7 @@ By default, the displays its navigation b -The supports vertical mode. Use the property to enable it. +Use the property to display the Carousel in vertical mode. @@ -326,27 +445,67 @@ The supports vertical mode. Use the -### Custom indicators + + + + +Use the input to control whether the Carousel wraps from the last slide to the first slide, or from the first slide to the last slide. + +```html + + ... + +``` + +Use the input to change where the indicators are positioned. + +```html + + ... + +``` -To add {Platform} custom carousel indicators, use the : +Use to hide the indicators and to hide the navigation buttons. + +```html + + ... + +``` + +Use the input to display the Carousel in vertical mode. + +```html + + ... + +``` + + + +### Custom Indicators + + + +Use the component to replace the default indicator content. ```html - 🤍 - ❤️ + Off + On - 🤍 - ❤️ + Off + On - the_red_ice_forest + Red ice forest - yosemite + Yosemite ``` @@ -357,26 +516,20 @@ To add {Platform} custom carousel indicators, use the 🤍 - - ❤️ - - - - 🤍 - - ❤️ - - - - - - - - + + Off + On + + + Off + On + + + Ignite UI Indigo Design + + + Chart preview + ``` @@ -387,29 +540,53 @@ To add {Platform} custom carousel indicators, use the ❤️ + Off + On - 🤍 - ❤️ + Off + On - the_red_ice_forest + Red ice forest - yosemite + Yosemite ``` -The {ProductName} Carousel component allows users to use different elements for the active and inactive states of a single indicator. It is mandatory to provide two elements for each indicator slot (**empty** and **active**) when declaring an indicator, even if they are the same. We recommend using a `` element for symbol or emoji indicators, and an [``](../layouts/icon.mdx) component for icon indicators. +Provide both the default indicator content and the `active` slot content for each custom indicator. -### Custom navigation buttons + -The navigation buttons can also be customized. To achieve this, use the `previous-button` and `next-button` slots: + + +Use the template directive to replace the default indicator content. + +```html + + +
+ + + Ignite UI Indigo Design + + + Chart preview + + +``` + + + +### Custom Navigation Buttons + + + +Use the `previous-button` and `next-button` slots to provide custom navigation button content. @@ -447,11 +624,37 @@ The navigation buttons can also be customized. To achieve this, use the `previou -Just like with the custom indicators, we recommend using a `` element for symbol or emoji navigation buttons, and an [``](../layouts/icon.mdx) component for icon navigation buttons. +Use text, SVG, or content in these slots when the default navigation controls do not fit the design. + + + + + +Use the and template directives to provide custom navigation button content. + +```html + + + + + + + + ... + +``` + + + +### Slide Content -### Slide containing other components +Place forms, images, and other components inside a slide when each step in the Carousel needs richer content. -This carousel is going to contain slides with forms and images: + @@ -459,7 +662,7 @@ This carousel is going to contain slides with forms and images:
- + Sign up
@@ -471,17 +674,6 @@ This carousel is going to contain slides with forms and images:
- -
- -
- - - - Search -
-
- ``` @@ -492,33 +684,20 @@ This carousel is going to contain slides with forms and images: ```tsx -
- -
- - - - - - - - Sign In - -
-
- - -
- -
- - - - - Search - -
-
+
+ Sign up +
+ + + + + + + + Sign In + +
+
``` @@ -531,10 +710,10 @@ This carousel is going to contain slides with forms and images:
- + Sign up
- + @@ -543,35 +722,51 @@ This carousel is going to contain slides with forms and images:
- -
- -
- - - - Search -
-
- ``` -#### Demo + - + + +```html + + +
+ Sign up +
+ + + person + + + + + + password + + + + +
+
+ + +``` -## Animations + + + -Animated slide transitions provide the end-users a nice experience when interacting with the carousel. +### Animations -The carousel is configured to use the `slide` animation by default, but it also supports `fade` as an alternative animation. + -Use the property to change the animation. +Set the property to change the slide transition animation. @@ -603,44 +798,53 @@ Use the property disables the animations. +Set the property to `none` to disable animations. -### Demo + -The demo below demonstrates the different types of animations, which the carousel supports. + - + -## Navigation +Set the input to change the slide transition animation. -Transition and navigation are the most important carousel features. +```html + + ... + +``` -The navigation in the carousel can be handled by the user through navigation buttons, indicators, keyboard navigation and touch interaction on mobile devices. + -### Touch gestures + -By default, the carousel can be used on any touch-enabled device. +### Touch Gestures -The carousel [animations](./carousel.mdx#animations) are fully supported on touch devices, which makes the carousel consistent with any platform and great when used in progressive web applications ([PWA](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps)). +Use the Carousel on touch-enabled devices when swipe navigation should mirror the configured slide transition. -### Keyboard navigation + -- Navigation buttons - - SPACE or ENTER key - navigates to the next/previous slide. -- Indicators - - 🡐 key - navigates to the previous (next in Right-to-Left mode) slide. - - 🡒 key - navigates to the next (previous in Right-to-Left mode) slide. - - HOME key - navigates to the first (last in Right-to-Left mode) slide. - - END key - navigates to the last (first in Right-to-Left mode) slide. +Set the input to `false` when pan gestures should be disabled. -### Automatic transitioning +```html + + ... + +``` -The can be easily configured to change the slides automatically, without any user interaction. This way you can create your own slideshow by only setting a transition interval to the property, which determines the amount of time in milliseconds between slides transition. + + +### Automatic Transitioning + + + +Set the property to create an automatic slideshow. -Hovering the mouse over any carousel content or moving keyboard focus to any of the carousel content pauses automatic transitioning. Automatic transitioning resumes when the mouse moves away from the carousel or when keyboard focus moves out of the carousel content. +Hovering over carousel content or moving keyboard focus into carousel content pauses automatic transitioning. Automatic transitioning resumes when the pointer or keyboard focus leaves the carousel. -This can be prevented by setting property to **true**. + +Set to `true` when automatic transitioning should continue during pointer or keyboard interaction. @@ -672,64 +876,36 @@ This can be prevented by setting -Let's create a fully automated carousel with looping enabled. We will configure the indicators to be a thumbnail representation of each slide. +Set the input to create an automatic slideshow, and set to `false` when transitioning should not pause on interaction. -To achieve this goal, we have to do the following configurations to the carousel: -- enable the property -- enable the property -- enable the property -- add transition -- add custom for each slide +```html + + ... + +``` -Our carousel will look like this in the template: + + +### Thumbnail Indicators + + + +Use custom indicators with thumbnail images when each indicator should preview its corresponding slide. ```html - - - - - - - - - - - - - + - - + Wonderful coast thumbnail + Wonderful coast thumbnail active - - - - - - - - - - - - - - - - - - + Wonderful coast ``` @@ -744,56 +920,32 @@ const images = [ src: "assets/images/carousel/WonderfulCoast.png", alt: "Wonderful Coast", }, - { - src: "assets/images/carousel/CulturalDip.png", - alt: "Cultural Dip", - }, - { - src: "assets/images/carousel/GoldenBeaches.png", - alt: "Golden Beaches", - }, - { - src: "assets/images/carousel/IslandOfHistory.png", - alt: "Island Of History", - }, - { - src: "assets/images/carousel/AmazingBridge.png", - alt: "Amazing Bridge", - }, ]; - - {images.map((image, index) => { - return ( - - - {image.alt} - - - {`${image.alt} - {`${image.alt} - - - ); - })} + + {images.map((image, index) => ( + + + {image.alt} + + + {`${image.alt} + {`${image.alt} + + + ))} ``` @@ -808,89 +960,288 @@ const images = [ Vertical="true" AnimationType="@CarouselAnimationType.Fade"> - - - - - - - - - - - - - - - - - - + Wonderful coast thumbnail + Wonderful coast thumbnail active - - - WonderfulCoast - - - CulturalDip - - - GoldenBeaches - - - IslandOfHistory - - AmazingBridge + Wonderful coast ``` -These configurations will have the following result: + + + + + + +### Synced List Navigation + +Use a linked list when Angular Carousel navigation needs a visible list of slide labels instead of thumbnail indicators. + +```html + + + ... + + +``` + + + + + +### Do/Don't + +**When to use:** Use Carousel when the interface needs to show a compact set of related visual or mixed-content slides that users browse one at a time. + + + +**When not to use:** Do not use Carousel for primary navigation, long sequential workflows, or content users must compare side by side. Use [Tabs](./tabs.mdx) for switching between named sections, or [Stepper](./stepper.mdx) for guided sequential tasks. + + + + + +**When not to use:** Do not use Carousel for primary navigation, long sequential workflows, or content users must compare side by side. Use [Tabs](../tabs.mdx) for switching between named sections, or [Stepper](../stepper.mdx) for guided sequential tasks. + + + +
+ + + + + + + + + + + + + + + + + +
DoDon't
{Platform} Carousel do guidance{Platform} Carousel don't guidance
{Platform} Carousel do guidance with visual slides{Platform} Carousel don't guidance with dense content
+
+ +## Properties + +The following Carousel properties cover the configuration used most often in slide-based layouts. + + + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| | `boolean` | `false` | Marks a slide as active. | +| | `boolean` | `false` | Disables looping between the first and last slides. | +| | `boolean` | See API | Keeps automatic transitioning from pausing on pointer or keyboard interaction. | +| | `boolean` | `false` | Hides the slide indicators. | +| | `boolean` | `false` | Hides the previous and next navigation buttons. | +| | `CarouselIndicatorsOrientation` | See API | Controls where the indicators are positioned. | +| | `number` | See API | Sets the automatic transition interval in milliseconds. | +| | `boolean` | `false` | Displays the Carousel in vertical orientation. | + + + + + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| | `boolean` | `true` | Enables looping between the first and last slides. | +| | `boolean` | `true` | Shows or hides the previous and next navigation buttons. | +| | `boolean` | `true` | Shows or hides the slide indicators. | +| | `string` | See API | Controls where the indicators are positioned. | +| | `number` | See API | Sets the automatic transition interval in milliseconds. | +| | `boolean` | See API | Controls whether automatic transitioning pauses on interaction. | +| | `boolean` | `false` | Displays the Carousel in vertical orientation. | +| | `boolean` | See API | Enables or disables pan gestures. | +| | `string` | See API | Sets the slide transition animation. | + + + +## Styling + +The Carousel can be styled through its exposed parts, custom indicator content, and custom navigation slots. + + + + + + + + - + + + + +### Sass Theming + +Use Sass theming when the Carousel needs theme-level changes that should stay consistent across the application. + +{/*TODO: Add the verified Carousel Sass theme variable table.*/} + +### Parts and Slots + +Use the exposed slots and parts when only a specific Carousel surface needs custom content or local styling. + + + +| Surface | What it customizes | +| --- | --- | +| `previous-button` slot | Replaces the previous navigation button content. | +| `next-button` slot | Replaces the next navigation button content. | +| | Replaces the default slide indicator content. | + + + + + +| Surface | What it customizes | +| --- | --- | +| | Replaces the previous navigation button content. | +| | Replaces the next navigation button content. | +| | Replaces the default slide indicator content. | + + + +### Styling with Tailwind + + + +Use Tailwind utility classes with the {ProductName} Carousel when you need utility-first layout styling together with Ignite UI component tokens. + + + + ## Accessibility -### WAI-ARIA Roles, States, and Properties +The {Platform} Carousel exposes carousel, slide, and indicator semantics for keyboard and assistive technology users. + +### Keyboard Interaction + +| Key | Action | +| --- | --- | +| Space or Enter | Activates the focused navigation button. | +| Arrow Left | Moves indicator focus to the previous slide indicator, or to the next indicator in right-to-left mode. | +| Arrow Right | Moves indicator focus to the next slide indicator, or to the previous indicator in right-to-left mode. | +| Home | Moves indicator focus to the first slide indicator, or to the last indicator in right-to-left mode. | +| End | Moves indicator focus to the last slide indicator, or to the first indicator in right-to-left mode. | + +### Screen Readers / ARIA + +The Carousel provides ARIA roles and state for the host, slides, indicators, and navigation controls. + +| Element | Role or attribute | Purpose | +| --- | --- | --- | +| Carousel host | `role="region"` and `aria-roledescription="carousel"` | Identifies the Carousel as a navigable content region. | +| Slides container | `aria-live="polite"` or `aria-live="off"` | Announces slide changes when automatic playback is not active. | +| Slide | `role="tabpanel"`, `aria-roledescription="slide"`, and `aria-label` | Identifies each slide and its position in the set. | +| Indicator container | `role="tablist"` | Groups the slide indicators. | +| Indicator | `role="tab"`, `aria-label`, and `aria-selected` | Identifies the slide represented by the indicator and whether it is selected. | +| Navigation buttons | `aria-label` | Names the previous and next slide actions. | -- The Carousel base element role is [`region`](https://www.w3.org/TR/wai-aria-1.1/#region) - section containing content that is relevant to specific purpose and users will likely want to be able to navigate easily. -- Carousel indicators are with role [`tab`](https://www.w3.org/TR/wai-aria-1.1/#tab) - grouping label providing a mechanism for selecting the tab content that is to be rendered to the user -- The element that serves as the container for the set of tabs (carousel indicators) is with role [`tablist`](https://www.w3.org/TR/wai-aria-1.1/#tablist). -- Each slide element is set with role [`tabpanel`](https://www.w3.org/TR/wai-aria-1.1/#tabpanel). +### Accessibility Compliance -### ARIA support +Infragistics documents {ProductName} accessibility support for Section 508 and WCAG 2.1 guideline areas in the [Accessibility Compliance](../interactivity/accessibility-compliance.mdx) topic. -#### Carousel component +| Criterion | How the component complies | +| --- | --- | +| [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html) | Navigation buttons and indicators support keyboard operation. | +| [2.1.2 No Keyboard Trap](https://www.w3.org/WAI/WCAG22/Understanding/no-keyboard-trap.html) | Carousel keyboard interaction does not require focus to remain inside the component. | +| [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) | The host, slides, indicators, and navigation controls expose roles, names, and selected state. | -- **Attributes** - - [aria-roledescription](https://www.w3.org/TR/wai-aria-1.1/#aria-roledescription) set to "carousel". - - [aria-live](https://www.w3.org/TR/wai-aria-1.1/#aria-live) - used to set the priority with which screen reader should treat updates to live regions - the possible settings are: **off** and **polite**. The default setting is **polite** and is set to the element that serves as the container for the set of slides. When the option is set and the carousel is in playing state, the **aria-live** attribute would be set to **off**. - - [aria-label](https://www.w3.org/TR/wai-aria/states_and_properties#aria-label) (navigation buttons) - "Previous slide"/"Next slide". +Application authors still need to provide meaningful slide content, image alternative text, and enough contrast for custom indicator or navigation content. -#### Slide component +## Troubleshooting -- **Attributes** - - id - follows the pattern `"igc-carousel-slide-${incremented_number}"`. - - [aria-roledescription](https://www.w3.org/TR/wai-aria-1.1/#aria-roledescription) set to "slide". - - [aria-label](https://www.w3.org/TR/wai-aria/#aria-label) follows the pattern `"${index + 1} of ${total}"`. +Use this section to check content and interaction boundaries before treating Carousel as a general navigation or comparison layout. -#### Indicator component +### Known Limitations -- **Attributes** - - [aria-label](https://www.w3.org/TR/wai-aria/#aria-label) follows the pattern "Slide `${index + 1}`" - - [aria-selected](https://www.w3.org/TR/wai-aria-1.1/#aria-selected) set to **true** or **false** based on the active slide. +The Carousel is intended for a compact set of related slides and can become hard to scan when it contains long, unrelated, or comparison-heavy content. ## API References + +The generated API references list the complete Carousel, slide, indicator, and supporting component APIs. + + + + + + + + + + + + + + + + + + + +## Dependencies + +The Carousel examples rely on the Carousel slide and indicator types, the theme stylesheet, and supporting input, icon, and button components when those components appear inside slides or navigation slots. + ## Additional Resources +Use these resources for broader product support and source information. + - [{ProductName} **Forums**]({ForumsLink}) - [{ProductName} **GitHub**]({GithubLink}) + +## Related Components + +Use these related layout components when Carousel is not the best match for the interaction model. + + + +- [Tabs](./tabs.mdx) - Use Tabs when users need to switch between named sections without slide-style navigation. +- [Stepper](./stepper.mdx) - Use Stepper when users need to complete a guided sequence of steps. + + + + + +- [Tabs](../tabs.mdx) - Use Tabs when users need to switch between named sections without slide-style navigation. +- [Stepper](../stepper.mdx) - Use Stepper when users need to complete a guided sequence of steps. + + + +## FAQ + + + + Use Carousel for a compact set of visual or mixed-content slides. Use Tabs when each section needs a persistent label and direct random access. + + + + Yes. Place forms, images, buttons, and other components inside a slide when each slide needs richer content. + + + + Set the interval property to the number of milliseconds between slide transitions. Use disablePauseOnInteraction when playback should continue during pointer or keyboard interaction. + + diff --git a/docs/xplat/src/content/en/toc.json b/docs/xplat/src/content/en/toc.json index 5839d7ff38..edf9dfa746 100644 --- a/docs/xplat/src/content/en/toc.json +++ b/docs/xplat/src/content/en/toc.json @@ -2234,12 +2234,9 @@ "href": "layouts/card.mdx" }, { - "exclude": [ - "Angular" - ], "name": "Carousel", "href": "layouts/carousel.mdx", - "new": true + "updated": true }, { "exclude": [