diff --git a/apiMap/WebComponents/webInputs.JS.wc.apiMap.json b/apiMap/WebComponents/webInputs.JS.wc.apiMap.json index 0d3105e54..fd734e7cd 100644 --- a/apiMap/WebComponents/webInputs.JS.wc.apiMap.json +++ b/apiMap/WebComponents/webInputs.JS.wc.apiMap.json @@ -17,6 +17,9 @@ "igc-card-header-module.ts", "igc-card-media-module.ts", "igc-card-module.ts", + "igc-carousel-module.ts", + "igc-carousel-indicator-module.ts", + "igc-carousel-slide-module.ts", "igc-checkbox-base-module.ts", "igc-checkbox-module.ts", "igc-chip-module.ts", @@ -1778,6 +1781,44 @@ {"names":[{"platform": "WebComponents", "mappedType": "boolean", "mappedName": "elevated"}], "originalName": "Elevated"}, {"names":[{"platform": "WebComponents", "mappedType": "method", "mappedName": "setNativeElement"}], "originalName": "SetNativeElement"} ] }, + { + "originalName": "Carousel", + "originalNamespace": "Infragistics.Controls", + "originalBaseTypeNamespace": "Infragistics.Controls", + "originalBaseTypeName": "BaseElement", + "packageName": "igniteui-webinputs", + "names":[{"platform": "WebComponents","fileName": "igc-carousel-component.ts","mappedName": "IgcCarouselComponent"}], + "members":[ + {"names":[{"platform": "WebComponents", "mappedType": "boolean","mappedName": "disableLoop"}], "originalName": "DisableLoop"}, + {"names":[{"platform": "WebComponents", "mappedType": "boolean","mappedName": "hideIndicators"}], "originalName": "HideIndicators"}, + {"names":[{"platform": "WebComponents", "mappedType": "boolean","mappedName": "hideNavigation"}], "originalName": "HideNavigation"}, + {"names":[{"platform": "WebComponents", "mappedType": "boolean","mappedName": "disablePauseOnInteraction"}], "originalName": "DisablePauseOnInteraction"}, + {"names":[{"platform": "WebComponents", "mappedType": "boolean","mappedName": "vertical"}], "originalName": "Vertical"}, + {"names":[{"platform": "WebComponents", "mappedType": "number","mappedName": "interval"}], "originalName": "Interval"}, + {"names":[{"platform": "WebComponents", "mappedType": "number","mappedName": "maximumIndicatorsCount"}], "originalName": "MaximumIndicatorsCount"}, + {"names":[{"platform": "WebComponents", "mappedType": "CarouselIndicatorsOrientation","mappedName": "indicatorsOrientation"}], "originalName": "IndicatorsOrientation"}, + {"names":[{"platform": "WebComponents", "mappedType": "CarouselAnimationType","mappedName": "animationType"}], "originalName": "AnimationType"} ] + }, + { + "originalName": "Slide", + "originalNamespace": "Infragistics.Controls", + "originalBaseTypeNamespace": "Infragistics.Controls", + "originalBaseTypeName": "BaseElement", + "packageName": "igniteui-webinputs", + "names":[{"platform": "WebComponents","fileName": "igc-carousel-slide-component.ts","mappedName": "IgcCarouselSlideComponent"}], + "members":[ + {"names":[{"platform": "WebComponents", "mappedType": "boolean", "mappedName": "active"}], "originalName": "Active"} ] + }, + { + "originalName": "Indicator", + "originalNamespace": "Infragistics.Controls", + "originalBaseTypeNamespace": "Infragistics.Controls", + "originalBaseTypeName": "BaseElement", + "packageName": "igniteui-webinputs", + "names":[{"platform": "WebComponents","fileName": "igc-carousel-indicator-component.ts","mappedName": "IgcCarouselIndicatorComponent"}], + "members":[ + {"names":[{"platform": "WebComponents", "mappedType": "method", "mappedName": "setNativeElement"}], "originalName": "SetNativeElement"} ] + }, { "originalName": "Checkbox", "originalNamespace": "Infragistics.Controls", diff --git a/doc/en/components/layouts/carousel.md b/doc/en/components/layouts/carousel.md new file mode 100644 index 000000000..46f9b1cb8 --- /dev/null +++ b/doc/en/components/layouts/carousel.md @@ -0,0 +1,352 @@ +--- +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 +_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 +mentionedTypes: ["Carousel"] +--- + +# {Platform} Carousel Overview +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. + +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. + +## {Platform} Carousel Example +The {Platform} Carousel demo you see below shows slides containing only images. + +`sample="/layouts/carousel/overview", height="500", alt="{Platform} Carousel Overview Example"` + +## Usage + + +First, you need to install the {ProductName} by running the following command: + +```cmd +npm install {PackageWebComponents} +``` + +You will then need to import the `Carousel`, its necessary CSS, and register its module, like so: + +```ts +import { defineComponents, IgcCarouselComponent } from "igniteui-webcomponents"; +import 'igniteui-webcomponents/themes/light/bootstrap.css'; + +defineComponents(IgcCarouselComponent); +``` + + +For a complete introduction to the {ProductName}, read the [*Getting Started*](../general-getting-started.md) topic. + +Now that you have the {ProductName} Carousel imported, you can start with a basic configuration of the `Carousel` and its slides. + +Use the `Carousel` selector to wrap your slides. The slides may feature any valid html content inside, including other components. + +```html + + + + + + + + + + + +``` + +If you want a slide to be active by default, use the `Active` attribute: + +```html + + ... + + ... + + + ... + + +``` + +>[!NOTE] +>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. + +## Examples + +### Carousel Configuration + +By default, the `Carousel` has its `DisableLoop` 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 `DisableLoop` property to **true**. + +```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 `IndicatorsOrientation` property and assign it to `start`. + +```html + + ... + +``` + +By default, the `Carousel` displays its navigation buttons and indicators. Use the `HideIndicators` property to hide the indicators and the `HideNavigation` property to hide the navigation buttons. + +```html + + ... + +``` + +The `Carousel` supports vertical mode. Use the `Vertical` property to enable it. + +```html + + ... + +``` + +### Custom indicators + +To add {Platform} custom carousel indicators, use the `Indicator`: + +```html + + + 🤍 + ❤️ + + + 🤍 + ❤️ + + + + + + + + + +``` + +The {ProductName} Carousel component allows users to use different elements for the active and inactive state of a single indicator. It is mandatory to provide two elements for each slot (empty and active) when declaring an indicator, even if they are the same. + + +### Custom navigation buttons + +To achieve this, use the `previous-button` and `next-button` slots: + +```html + + + + ... + +``` + +### Slide containing other components + +This carousel is going to contain slides with forms and images: + +```html + + +
+ +
+ + + + + + + Sign In +
+
+ + +
+ +
+ + + + Search +
+
+ + +``` + +#### Demo + +`sample="/layouts/carousel/components", height="600", alt="{Platform} Carousel With Components Example"` + + +## 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. + +Use the `AnimationType` property to change the animation. + +```html + + ... + +``` + +Setting `none` to the `AnimationType` property disables the animations. + +### Demo + +The demo below demonstrates the different types of animations, which the carousel supports. + +`sample="/layouts/carousel/animations", height="650", alt="{Platform} Carousel Animations Example"` + + +## Navigation + +Transition and navigation are the most important carousel features. + +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. + +The carousel [animations](carousel.md#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 `Carousel` 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 `Interval` property, which determines the amount of time in milliseconds between slides transition. + +>[!NOTE] +>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. +This can be prevented by setting `DisablePauseOnInteraction` property to **true**. + +```html + + ... + +``` + +## Advanced Example + +Let's create a fully automated carousel with looping enabled. We will configure the indicators to be a thumbnail representation of each slide. + + +To achieve this goal, we have to do the following configurations to the carousel: + - enable the `DisablePauseOnInteraction` property + - enable the `HideNavigation` property + - enable the `Vertical` property + - add transition `Interval` + - add custom `Indicator` for each slide + +Our carousel will look like this in the template: + +```html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +``` + +These configurations will have the following result: + +`sample="/layouts/carousel/thumbnail", height="600", alt="{Platform} Carousel Thumbnail Example"` + + +## 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) 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). + +### ARIA support +#### Carousel component +* **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 `Interval` 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". + +#### Slide component +* **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}". + +#### Indicator component +* **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. + + +## API References + +- `Carousel` +- `Slide` +- `Indicator` +- `Icon` +- `Input` +- `Button` + +## Additional Resources + +* [{ProductName} **Forums**]({ForumsLink}) +* [{ProductName} **GitHub**]({GithubLink}) diff --git a/docConfig.json b/docConfig.json index be112c8a2..24fe499b5 100644 --- a/docConfig.json +++ b/docConfig.json @@ -440,6 +440,9 @@ "CardHeader", "CardMedia", "CardComponent", + "CarouselComponent", + "CarouselIndicatorComponent", + "CarouselSlideComponent", "CheckboxComponent", "CheckboxBase", "ChipComponent", diff --git a/docfx/en/components/toc.json b/docfx/en/components/toc.json index c7758b3e0..d28c234bf 100644 --- a/docfx/en/components/toc.json +++ b/docfx/en/components/toc.json @@ -1465,6 +1465,12 @@ "name": "Card", "href": "layouts/card.md" }, + { + "exclude": ["Angular", "Blazor", "React"], + "name": "Carousel", + "href": "layouts/carousel.md", + "status": "NEW" + }, { "exclude": ["Angular"], "name": "Dock Manager",