e8-carousel
Updated on Aug 14, 2025 8 minutes to readDisplay images and videos in a swipeable, Instagram-style media carousel.
Overview
e8-carousel renders file IDs or media descriptors as a fixed-size sequence of images and videos. It supports touch and mouse dragging, previous/next controls, animated indicators, looping, fullscreen mode, and download actions.
The carousel calculates its default aspect ratio from the first supported media item. This keeps the container stable when later items have different dimensions. Images and videos are fitted into the resulting area without changing its size.
<e8-carousel :sources="object.files.map(file => file.id)"></e8-carousel>
<!-- Media types of sources unknown: -->
<e8-carousel
:sources="['uuid1', 'uuid2']"
:check-type="true"
></e8-carousel>
<!-- Media types can also be supplied explicitly. This avoids the metadata request required by `check-type`: -->
<e8-carousel
:sources="[
{ id: object.image, mimeType: 'image/jpeg' },
{ id: object.video, mimeType: 'video/mp4' }
]"
></e8-carousel>
đź”˝ Show more
Properties
| Property | Description | Type | Default |
|---|---|---|---|
| allow-upscale | Allows contained images to grow beyond their natural dimensions. When false and fit is contain, small images keep their natural size. | boolean | false |
| alt | Alternate text used for image slides. When omitted, a localized position label is generated. | string | '' |
| aria-label | Accessible label for the carousel region. When omitted, a localized default label is used. | string | '' |
| aspect-ratio | Container aspect ratio used when height is empty. auto starts with 1 / 1 and then locks the container to the first supported image or video's intrinsic ratio. A CSS ratio such as 4 / 5 can be supplied to keep a predefined size. | number | string | 'auto' |
| background | Background shown behind media that does not fill the entire container. | string | '#000' |
| check-type | For string file IDs, requests their metadata in one $files.getInfo(ids) call and detects images/videos by MIME type. Unsupported files are omitted. Media descriptor objects already contain their MIME type and do not require this lookup. | boolean | false |
| fit | Image fitting mode. Supported values are contain and cover. | string | 'contain' |
| height | Fixed CSS height. When provided, it takes precedence over aspect-ratio. | number | string | '' |
| loop | Continues navigation from the last slide to the first and from the first to the last. | boolean | false |
| show-arrows | Shows previous/next controls when navigation in the corresponding direction is available. | boolean | true |
| show-download-all-button | Adds a “download all” action when more than one supported item is present. Browsers download a ZIP archive; the mobile application saves every item separately to the gallery. | boolean | true |
| show-download-button | Adds an action for downloading the current item. In the mobile application, the item is saved to the gallery. | boolean | true |
| show-fullscreen-button | Shows the fullscreen toggle. Browsers use the Fullscreen API when available and use a viewport-sized fallback otherwise. The mobile application always uses fallback fullscreen. | boolean | true |
| show-indicators | Shows animated position indicators. At most five indicators are visible at once; smaller edge indicators show that more slides are available. | boolean | true |
| sources | Files displayed by the carousel. A string is treated as an image when check-type is false. An object must contain id and mimeType; supported values are image/*, video/mp4, video/quicktime, and video/mov. Unsupported entries are skipped and reported in the browser console. | Array<E8CarouselSourceType> | [] |
| value | Zero-based index of the active supported slide. | number | string | 0 |
| width | Carousel CSS width. Percentage values use the width of the parent container. | number | string | '100%' |