Carousel specification

Carousel specification

• Carousel specification
  • Owned By
    • Requires approval from:
    • Signed off by:
    • Revision history
  • Overview
    • Terms
    • Acceptance criteria
  • User stories
    • End-user stories
    • Developer stories
  • Functionality
    • End-user experience
    • Behaviors
    • Localization
    • Keyboard navigation
  • API
    • IgcCarouselComponent
      • Properties
      • Methods
      • Events
      • Slots
      • CSS Shadow Parts
    • IgcCarouselSlide
      • Properties
      • Methods
      • Events
      • Slots
      • CSS Shadow Parts
    • IgcCarouselIndicatorComponent
      • Properties
      • Methods
      • Events
      • Slots
      • CSS Shadow Parts
  • Test scenarios
    • Automation
      • Rendering and initialization
      • Attributes and properties
      • Behaviors
  • Accessibility
    • ARIA
      • IgcCarouselComponent intrinsic ARIA properties
      • IgcCarouselSlideComponent intrinsic ARIA properties
      • IgcCarouselIndicatorComponent intrinsic ARIA properties
      • References
    • RTL
  • Assumptions and limitations

Owned By

Team Name: Astrea + Design and Web Development

Developer name: Riva Ivanova

Designer name: Silvia Ivanova

Requires approval from:

• Damyan Petev
• Svilen Dimchevski

Signed off by:

• Simeon Simeonov
• Radoslav Mirchev: 2024

Revision history

Version	Author	Date	Notes
-	Radoslav Karaivanov	2024-06-10	Initial draft - user stories and API
1	Radoslav Karaivanov	2024-09-19	Finalize v1 specification
1.1	Radoslav Karaivanov	2024-09-20	Additional ARIA customizations

Overview

An igc-carousel component presents a set of items, referred to as slides, by sequentially displaying a subset of one or more slides. Typically, one slide is displayed at a time, and users can activate a next or previous slide control that hides the current slide and "rotates" the next or previous slide into view. While a slide may contain any type of content, image carousels where each slide contains nothing more than a single image are common.

Terms

The following terms are used to describe components of a carousel.

Slide A single content container within a set of containers that the content to be presented by the carousel. In the current implementation, that role is fulfilled by the igc-carousel-slide component.

Next Slide Control An interactive element, often styled as an arrow, that displays the next slide in the rotation sequence.

Previous Slide Control An interactive element, often styled as an arrow, that displays the previous slide in the rotation sequence.

Slide Picker Controls A group of elements, often styled as small dots, that enable the user to pick a specific slide in the rotation sequence to display.

Acceptance criteria

The igc-carousel must:

• show a set of igc-carousel-slide components one at a time.
• render controls for navigating the carousel and its slides.
• expose a way to change the current "active" (shown) slide.
• be WAI-ARIA compliant.

User stories

End-user stories

As an end-user I expect to be able to:

• pause/resume automatic rotation of the slides in the carousel.
• navigate through the set of slides via the rendered slide controls.
• navigate through the set of slides via the rendered slide indicator controls.
• navigate through the set of slides via keyboard interaction.
• have an indication of the current active slide and/or the total number of slides.

Developer stories

As a developer I expect to be able to:

• declaratively provide the slides which will be displayed in the carousel component.
• declaratively provide the content of the slides.
• have default navigation controls as well as the ability to hide said controls.
• show additional slide picker control (dots) where the user can pick and show a specific slide from the set.
• align the carousel navigation/indicators as well as the direction of the slide animation either horizontally or vertically.
• control the default time interval between switching the current active slide.
• enable/disable looping of the slides.
• set initial active slide.
• programmatically control which slide should be shown.
• programmatically control the state of the carousel (playing/paused).
• customize the look and feel of the navigation buttons and the slides picker control

Functionality

End-user experience

Design Handoff

Behaviors

• Unless disablePauseOnInteraction is set, any interaction with the carousel and its content will pause any currently playing loop. This includes focus (both keyboard and pointer initiated) and hover.
• The carousel support swipe gestures interaction - it is enabled on touch-based devices only.
• If there is no active slide on initial render, the first slide becomes active by default.
• If there are several active slides on initial render, the last one will become the active slide.

Localization

No specific implementation is needed.

Keyboard navigation

Following the general WAI-ARIA recommendations, the carousel has a maximum of 3 logical tab stops if all its navigation/indicator elements are shown.

When focus in on the indicators container of the carousel, navigation is done as follows:

Key	Behavior
Arrow Left	Navigates to the previous indicator and sets the active slide to its index.
Arrow Right	Navigates to the next indicator and sets the active slide to its index.
Home	Navigates to the first indicator and sets the the first slide to active.
End	Navigates to the last indicator and sets the the last slide to active.

API

IgcCarouselComponent

Properties

Property	Attribute	Reflected	Type	Default	Description
disableLoop	disable-loop	Yes	Boolean	false	Whether the carousel should loop back to the first slide after it reaches the last.
disablePauseOnInteraction	disable-pause-on-interaction	Yes	Boolean	false	Whether the carousel should ignore user interactions and not pause on them.
hideNavigation	hide-navigation	Yes	Boolean	false	Whether the carousel should render the navigation buttons.
hideIndicators	hide-indicators	Yes	Boolean	false	Whether the carousel should render the indicator controls (dots).
vertical	vertical	Yes	Boolean	false	Whether the carousel has vertical alignment.
indicatorsLabelFormat	indicators-label-format	No	string	Slide {0}	The format used to set the aria-label on the carousel indicators. Instances of '{0}' will be replaced with the index of the corresponding slide.
slidesLabelFormat	slides-label-format	No	string	{0} of {1}	The format used to set the aria-label on the carousel slides and the text displayed when the number of indicators is greater than tha maximum indicator count. Instances of '{0}' will be replaced with the index of the corresponding slide. Instances of '{1}' will be replaced with the total amount of slides.
indicatorsOrientation	indicators-orientation	No	start | end	end	Sets the position of the indicator controls (dots).
interval	interval	No	number	-	The duration in milliseconds between changing the active slide.
maximumIndicatorsCount	maximum-indicators-count	No	number	10	Controls the maximum indicator controls (dots) that can be shown.
animationType	animation-type	No	slide | fade | none	slide	The type of animation to play when switching between slides.
slides	-	No	Array	[]	The slides of the carousel.
total	-	No	number	-	The total number of slides.
current	-	No	number	-	The index of the current active slide.
isPlaying	-	No	Boolean	false	Whether the carousel is in playing state.
isPaused	-	No	Boolean	false	Whether the carousel in in paused state.

Methods

Name	Type signature	Description
play	(): void	Resumes playing of the carousel slides.
pause	(): void	Pauses the carousel rotation of slides.
next	(): Promise<boolean>	Switches to the next slide running any animations and returns if the operation was a success.
prev	(): Promise<boolean>	Switches to the previous slide running any animations and returns if the operation was a success.
select	(slide: IgcCarouselSlide, direction?: 'next' | 'prev'): Promise<boolean>	Switches the passed in slide running any animations and returns if the operation was a success.

Events

Name	Cancellable	Description
igcSlideChanged	No	Emitted when the current active slide is changed either by user interaction or by the interval callback.
igcPlaying	No	Emitted when the carousel enters playing state by a user interaction.
igcPaused	No	Emitted when the carousel enters paused state by a user interaction.

Slots

Name	Description
default	Default slot for the carousel. Any projected igc-carousel-slide components should be projected here.
previous-button	Renders content inside the carousel previous navigation button.
next-button	Renders content inside the carousel next navigation button.

CSS Shadow Parts

Part	Description
navigation	The wrapper container of each carousel navigation button.
previous	The wrapper container of the carousel previous navigation button.
next	The wrapper container of the carousel next navigation button.
dot	The carousel dot indicator container.
active	The carousel active dot indicator container.
label	The label container of the carousel indicators.
start	The wrapping container of all carousel indicators when indicators-orientation is set to start.

IgcCarouselSlide

Properties

Property	Attribute	Reflected	Type	Default	Description
active	active	Yes	Boolean	false	The current active slide for the carousel component.

Methods

None applicable.

Events

None applicable.

Slots

Name	Description
default	Default slot for the carousel slide.

CSS Shadow Parts

Part	Description
base	The base wrapper of the carousel slide.

IgcCarouselIndicatorComponent

Properties

Property	Attribute	Reflected	Type	Default	Description
active	-	No	Boolean	false	Whether the indicator is in active state.

Methods

None applicable.

Events

None applicable.

Slots

Name	Description
default	Default slot for projected inactive indicator
active	Default slot for projected active indicator.

CSS Shadow Parts

Part	Description
indicator	The wrapping container of the carousel indicator.
inactive	The wrapping container of the inactive carousel indicator.
active	The wrapping container of the active carousel indicator.

Test scenarios

Automation

Rendering and initialization

• passes the default WAI-ARIA automation.
• is initialized without errors.
• is initialized with appropriate default state.
• is initialized with projected slides.
• should set the first slide as active if none are initially active.
• should set the active slide to be the last one if there are multiple active on initialization.
• should correctly slot user provided content in previous/next button slots.
• should correctly slot user provided content for indicators.

Attributes and properties

• should not render indicators if hideIndicators is set.
• should not render navigation buttons if hideNavigation is set.
• should render a label in the indicators container if the slide count is greater than maximumIndicatorsCount.
• should not render a label in the indicators container if the slide count is greater than maximumIndicatorsCount and hideIndicators is set.
• invoking prev() works.
• invoking next() works.
• invoking select() works.

Behaviors

• it should change the active slide when clicking on the next slide button.
• it should change the active slide when clicking on the previous slide button.
• it should change the active slide when clicking on a given indicator.
• it should change the active slide when pressing SpaceBar/Enter on the next slide button.
• it should change the active slide when pressing SpaceBar/Enter on the next previous button.
• it should change the active slide when pressing ArrowLeft/ArrowRight on an indicator.
• it should change the active slide when pressing Home/End on an indicator.
• it should change the active slide when swiping in the context of a touch-based device, both horizontally and vertically.
• it should not change the active slide when swiping in the context of a non-touch-based device, both horizontally and vertically.
• it should pause automatic rotation on a hover when disablePauseOnInteraction is not set.
• it should not pause automatic rotation on a hover when disablePauseOnInteraction is set.
• it should pause automatic rotation on a keyboard interaction when disablePauseOnInteraction is not set.
• it should not pause automatic rotation on a keyboard interaction when disablePauseOnInteraction is set.

Accessibility

ARIA

IgcCarouselComponent intrinsic ARIA properties

role: region

aria-roledescription: carousel

---

IgcCarouselSlideComponent intrinsic ARIA properties

role: tabpanel

aria-roledescription: slide

aria-label: The formatted value from slidesLabelFormat. By default that is: {Index of slide} of {Total slides}

---

IgcCarouselIndicatorComponent intrinsic ARIA properties

role: tab

aria-label: The formatted value of indicatorsLabelFormat. By default that is: Slide {index of corresponding slide}

---

References

https://www.w3.org/WAI/ARIA/apg/patterns/carousel/examples/carousel-1-prev-next/

https://www.w3.org/WAI/ARIA/apg/patterns/carousel/examples/carousel-2-tablist/?moreaccessible=false

RTL

The component should work in a Right-To-Left context without additional setup or configuration.

Assumptions and limitations

None applicable.