Carousel API
Full surface of oge-carousel: its inputs, methods and outputs, the declarative oge-carousel-slide, the slide template and the config provider.
Properties Methods Events Types
OgeCarousel
oge-carouselProperties 14
| Name | Type | Default | Description |
|---|---|---|---|
items | readonly OgeCarouselItem[] | [] | Data-driven slides, rendered after the declarative oge-carousel-slide children. Fields: key?, image?, imageAlt? (default '' = decorative), title?, description?, thumbnail?, label?. The default template draws the image and a frosted caption. |
selectedIndex | number (model) | 0 | Index of the first visible slide — two-way, clamped to the slides (with several per view, to count - slidesPerView). |
slidesPerView | number | 1 | Slides shown side by side. Above one the picker switches from the APG tab list to a row of buttons, because a picker entry no longer maps to one slide. |
gap | number | string | undefined | 0 (one per view) / 16 (several) | Space between slides — px number or any CSS length. |
height | number | string | undefined | — | Height of the slide viewport (px number or CSS length). Without it the track takes the tallest slide. |
indicators | 'dots' | 'thumbnails' | 'none' | config ?? 'dots' | The picker under the slides. Thumbnails are decorative images (the tab keeps its "Slide N" name); hidden with one reachable position. |
showNavigation | boolean | undefined | config ?? true | The previous / next buttons over the viewport edges. At an end without loop they are aria-disabled (they keep focus) rather than disabled. |
loop | boolean | undefined | config ?? false | Wraps the buttons, the picker keys and swipes from the last slide to the first. The carousel rewinds — it never clones slides, so the accessibility tree always holds the real count. |
autoplay | boolean | false | Rotates the slides and renders the rotation control first in the Tab order (WCAG 2.2.2). Pauses while hovered or while the tab is hidden; keyboard focus entering the carousel stops it until the user restarts it (APG). Rotation always wraps. Starts stopped under prefers-reduced-motion. |
autoplayInterval | number | undefined | config ?? 5000 | Rotation interval in ms (at least 1000). Every manual move restarts the full interval. |
pauseOnHover | boolean | true | Pauses the rotation while a mouse or pen pointer is over the carousel. |
swipeEnabled | boolean | true | Lets touch, pen and mouse drags move between slides on the shared pointer gesture (vertical swipes still scroll the page; Escape cancels a drag). |
locale | string | undefined | config ?? LOCALE_ID | BCP 47 locale the slide numbers are formatted in. |
ariaLabel | string | undefined | — | Accessible name. Set, the host is a named region; unset, a group named by the label message (no unnamed landmark). |
Methods 6
| Name | Type | Description |
|---|---|---|
next() | () => void | Shows the next slide (wraps only with loop). |
previous() | () => void | Shows the previous slide (wraps only with loop). |
goTo(index) | (index: number) => void | Shows slide index (clamped). |
play() | () => void | Starts the rotation (only while autoplay is on); emits autoplayChanged with source: 'api'. |
pause() | () => void | Stops the rotation until the user or play() restarts it. |
focus() | () => void | Focuses the selected picker entry, else the first control. |
Events 3
| Name | Type | Description |
|---|---|---|
selectedIndexChange | number | The banana half of [(selectedIndex)]. |
slideChanged | OgeCarouselSlideChangedEvent | The first visible slide changed: index, previousIndex and source ('next', 'previous', 'picker', 'swipe', 'autoplay', 'api'). |
autoplayChanged | OgeCarouselAutoplayChangedEvent | The rotation was started or stopped: playing and source ('user' — the rotation control or focus entering — or 'api'). Temporary hover / hidden-tab pauses are not reported. |
Types 9
Declarative slides & templates
| Name | Type | Description |
|---|---|---|
OgeCarouselSlide | component <oge-carousel-slide> | One declarative slide; projected content is the body. Inputs: label (the slide name prefix), thumbnail, visible. |
OgeCarouselSlideTemplate | [ogeCarouselSlideTemplate] | Structural directive replacing the image + caption of every items slide. The carousel keeps the slide role, the name and the inert state. |
OgeCarouselSlideTemplateContext | { $implicit: OgeCarouselItem; index: number; count: number; active: boolean } | Context of the slide template. |
Vocabulary
| Name | Type | Description |
|---|---|---|
OgeCarouselItem | interface | One data-driven slide: key?, image?, imageAlt? (default '' = decorative), title?, description?, thumbnail?, label?. |
OgeCarouselIndicators | 'dots' | 'thumbnails' | 'none' | Picker union. |
OgeCarouselPickerMode | 'tabs' | 'buttons' | The APG picker shape (ogeCarouselPickerMode(slidesPerView)). |
OgeCarouselChangeSource | 'next' | 'previous' | 'picker' | 'swipe' | 'autoplay' | 'api' | What moved the carousel. |
OgeCarouselSlideChangedEvent | { index: number; previousIndex: number; source: OgeCarouselChangeSource } | Payload of slideChanged. |
OgeCarouselAutoplayChangedEvent | { playing: boolean; source: 'user' | 'api' } | Payload of autoplayChanged. |
Configuration
Properties 2
provideOgeCarouselConfig()
| Name | Type | Description |
|---|---|---|
messages | OgeCarouselMessages | Every user-facing string: the role descriptions carousel / slide, the fallback label, previous, next, play, pause, picker, and the numbered names slideLabel ({index} of {count}), slideTitleLabel ({title}, {index} of {count}) and goToSlide (Slide {index}). Translated in every @oge-ui/locales pack (layout.carousel). |
indicators / loop / autoplayInterval / showNavigation / locale | — | Defaults for the matching inputs. Pass a function for a live config. |
Types 7
| Name | Type | Description |
|---|---|---|
provideOgeCarouselConfig | (config: OgeCarouselConfigInput | (() => OgeCarouselConfigInput)) => Provider | Application- or component-scoped defaults; a function makes the config live. |
OGE_CAROUSEL_CONFIG | InjectionToken<OgeCarouselConfig> | The resolved config the carousel injects. |
OGE_DEFAULT_CAROUSEL_CONFIG | OgeCarouselConfig | The defaults (from @oge-ui/behavior). |
OGE_DEFAULT_CAROUSEL_MESSAGES | OgeCarouselMessages | The English catalog. |
OgeCarouselConfig | { messages: OgeCarouselMessages; indicators?; loop?; autoplayInterval?; showNavigation?; locale? } | Resolved config shape. |
OgeCarouselConfigInput | Partial<OgeCarouselConfig> with partial messages | What the provider accepts. |
OgeCarouselMessages | { carousel; slide; label; previous; next; play; pause; picker; slideLabel; slideTitleLabel; goToSlide } | The carousel catalog. |