diff --git a/docs/components/index.md b/docs/components/index.md index 6f2fdbe44c..5a848693b3 100644 --- a/docs/components/index.md +++ b/docs/components/index.md @@ -22,6 +22,7 @@ documentation. ## C - [Cards](layout-navigation/cards.md) +- [Carousel](layout-navigation/carousel.md) - [Charts](charts/index.md) - [Checkbox](forms-inputs/checkbox.md) - [Circle Chart](charts/circle-chart.md) diff --git a/docs/components/layout-navigation/carousel.md b/docs/components/layout-navigation/carousel.md new file mode 100644 index 0000000000..e0cc6f676a --- /dev/null +++ b/docs/components/layout-navigation/carousel.md @@ -0,0 +1,88 @@ +# Carousel + +The **carousel** displays a set of related content in a horizontal row, +allowing users to cycle through them automatically or with controls. + +## Usage --- + +Use a carousel when users need to browse a small set of related items within limited space, +and each item follows a consistent structure (e.g., same card layout, similar content density). + +![Carousel](images/carousel.png) + +### When to use + +- To surface multiple related items. +- When content can be browsed one page at a time without losing context. +- When space is limited and showing all items at once would overwhelm the layout. +- In unattended display contexts (monitors, presentation screens) using slideshow mode with auto-play. + +### Best practices + +- Keep slides consistent in height and content structure across pages. +- Always show the auto-play control so users can pause the carousel at any time. +- Avoid mixing slides with very different content types in the same carousel. +- Use the carousel for content that is genuinely browsable, where users benefit from seeing one page at a time. +- The pagination displays a minimum of 2 and a maximum of 7 dots at a time, regardless of the total number of slides. + +## Design --- + +### Anatomy + +![Carousel elements](images/carousel-elements.png) + +> 1. Slides, 2. Navigation controls, 3, Pagination, 4. Pause/play + +Except for the slides, **all items are optional**. + +### Slide layout + +All slides within a carousel share the same width and height, + +The carousel always shows one full-width slide. +What goes inside that slot (one card, three cards, a grid, images) can be defined according to the use case. + +![Carousel slide layouts](images/carousel-slide-layouts.png) + +### Auto-play + +When auto-play is enabled, the carousel advances to the next slide after a configurable interval. +A play/pause button is shown alongside the navigation controls so users can stop or resume at any time. + +Auto-play works in both carousel and slideshow modes. + +![Carousel auto-play](images/carousel-auto-play.png) + +### Slideshow mode + +**Slideshow mode** expands the carousel to cover the entire viewport, hiding all application content including the app header. +It is typically used for unattended display (monitors, presentation screens) and is commonly paired with auto-play. + +## Code --- + +The `si-carousel` component uses the `siCarouselItem` directive to mark +each slide. Slides are displayed horizontally with snap-scroll behavior. + +### Usage + +```ts +import { SiCarouselComponent, SiCarouselItemDirective } from '@siemens/element-ng/carousel'; + +@Component({ + imports: [SiCarouselComponent, SiCarouselItemDirective, ...] +}) +``` + +```html + +

Slide 1

+

Slide 2

+

Slide 3

+ +``` + + + + + + diff --git a/docs/components/layout-navigation/images/carousel-auto-play.png b/docs/components/layout-navigation/images/carousel-auto-play.png new file mode 100644 index 0000000000..17b27646a2 Binary files /dev/null and b/docs/components/layout-navigation/images/carousel-auto-play.png differ diff --git a/docs/components/layout-navigation/images/carousel-elements.png b/docs/components/layout-navigation/images/carousel-elements.png new file mode 100644 index 0000000000..a8189f0299 Binary files /dev/null and b/docs/components/layout-navigation/images/carousel-elements.png differ diff --git a/docs/components/layout-navigation/images/carousel-slide-layouts.png b/docs/components/layout-navigation/images/carousel-slide-layouts.png new file mode 100644 index 0000000000..0d90ff592c Binary files /dev/null and b/docs/components/layout-navigation/images/carousel-slide-layouts.png differ diff --git a/docs/components/layout-navigation/images/carousel.png b/docs/components/layout-navigation/images/carousel.png new file mode 100644 index 0000000000..f2a3c1fd60 Binary files /dev/null and b/docs/components/layout-navigation/images/carousel.png differ diff --git a/mkdocs.yml b/mkdocs.yml index 0d76954557..2b7dec6c88 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -108,6 +108,7 @@ nav: - Application header: 'components/layout-navigation/application-header.md' - Breadcrumb: 'components/layout-navigation/breadcrumb.md' - Card: 'components/layout-navigation/cards.md' + - Carousel: 'components/layout-navigation/carousel.md' - Electron titlebar: 'components/layout-navigation/electron-titlebar.md' - Footer: 'components/layout-navigation/footer.md' - Launchpad: 'components/layout-navigation/launchpad.md' diff --git a/projects/element-ng/docs.ts b/projects/element-ng/docs.ts index 85891882dc..9e6063e221 100644 --- a/projects/element-ng/docs.ts +++ b/projects/element-ng/docs.ts @@ -14,6 +14,7 @@ export * from './badge'; export * from './breadcrumb'; export * from './breadcrumb-router'; export * from './card'; +export * from './carousel'; export * from './chat-messages'; export * from './circle-status'; export * from './color-picker';