@tbmaestro/ngx-picture-carousel

ngx-picture-carousel

Convenient library for displaying image carousels with custom configuration and full-screen mode.

CarouselComponent

Base component for carousel integration in any Angular template. Just create an element as so:

<ngx-picture-carousel [images]="images"
                      [config]="config"
                      [fullScreenConfig]="fullScreenConfig"
                      (ready)="onCarouselReady($event)">
</ngx-picture-carousel>

The following inputs are available:

• images: array of Image type objects. See Image.
• config: carousel's configuration. See CarouselConfig.
• fullScreenConfig: carousel's configuration to use in full-screen mode.
• currentImageId: ID of the image to be displayed first.

The component can emit the following events:

• ready: event emitted once the carousel is loaded.
• clickClose: event emitted when the user clicks on the native close button, if present.
• showImage: event emitted each time a new picture is displayed.

All outputs emit a Carousel object that acts as an API to control the carousel. See Carousel.

CarouselService

Sometimes one may not want to display a carousel in the application's UI but rather only use the full-screen feature. In that case, call the CarouselService to open a custom carousel that overlays the application.

this.carouselService.openCarousel(images, config, currentIndex).subscribe();

openCarousel(images, config, currentImageIndex)

Displays an overlaying carousel given a list of images and a configuration. Returns an Observable that will emit once the carousel is ready. The returned value is a Carousel object that can be used to control the carousel.

• images: array of Image type objects. See Image.
• config: carousel's configuration. See CarouselConfig.
• currentImageIndex: Index of the image to be displayed first.

closeCarousel(carouselId)

Closes an already open carousel, given its id. Does nothing if no carousel with the provided ID is currently open.

• carouselId: ID of carousel to close.

carouselClosed$(carouselId)

Listen for a carousel closing. Returns an Observable that will emit after a carousel is closed.

• carouselId: ID of carousel to listen for closing event.

Library utils

Carousel

The Carousel class is a util class that one can use as an API to control a carousel's content. Events raised by the CarouselComponent and after a call to openCarousel in the CarouselService will emit a Carousel object that is linked to the UI carousel so that it can be controlled after being opened.

images

Array of images displayed in the carousel. It can be changed by code to affect the carousel's content immediately. See Image.

currentIndex

Index of the image that is currently displayed within the images list. Setting this value will immediately affect the currently displayed image.

The value is not constrained by the images array's length. You may pass a number greater than the array's actual size, or even a negative number.

carousel.showImage(3); // Goes to the fourth image in the carousel.
carousel.showImage(-1); // Goes to the last image in the carousel.

currentImage

Currently displayed image. See Image.

showImage()

Returns an Observable that will emit each time an image is displayed in the carousel, either by pressing Previous/Next, an image's miniature or dot or by programmatically setting the carousel's current image. The emitted value is an Image object representing the displayed image. See Image.

nextImage()

Displays the next image following the order in which the images array is sorted. If the last image in the array is being displayed, goes back to the first image.

previousImage()

Displays the previous image following the order in which the images array is sorted. If the first image in the array is being displayed, goes to the last image.

Image

This is a wrapper interface representing an image in the carousel.

id

A unique ID to be used for identifying an image among others.

url

The URL to the image file.

alt

Fill this field with the alt attribute you'd like to be applied to the DOM's image.

CarouselConfig

Use this interface for configuring the carousel.

width

The carousel's width. May be any CSS size value. Defaults to 900px.

height

The carousel's height. May be any CSS size value. Defaults to 600px.

background

The carousel's background. May be any CSS color value. Defaults to black.

buttonsColor:

The carousel's UI color. May be any CSS color value. Defaults to white.

hideThumbnails

Whether the thumbnails bar at the bottom of the carousel is hidden. Defaults to false.

hideDots

Whether the dots bar overlaying the carousel is hidden. Defaults to false.

hideArrows

Whether the arrow controls are hidden. Defaults to false.

buttonsConfig

List of buttons to be displayed in the top-right corner of the carousel. By default, a CarouselComponent features only a full-screen button and any full-screen carousel has only a close button. See ButtonConfig.

ButtonConfig

There are two types of buttons that may be added to a carousel's buttonConfig: native buttons and custom buttons. Native buttons don't need to be manually configured and can be added simply by specifying their name in the button configuration. There are three native buttons available at the moment:

• fullscreen: switch to full-screen mode.
• close: close the carousel.
• download: download the current image's file.

You may also need to add buttons with custom actions. This can be done using the CustomButtonConfig interface which requires the following attributes:

• label: custom label for the button.
• iconClass: CSS class to apply to the button element. You should match this class in your CSS so that the button uses your icon of choice.
• onClick: callback that will be executed when the button is clicked. The callback may take a Carousel as an argument.

Example of valid button configuration featuring download, delete and full-screen buttons:

[
  'download', // Native button
  { // Custom config
    label: 'delete',
    iconClass: 'mdi mdi-delete',
    onClick: (carousel) => {
      carousel.images = carousel.images.filter(image => image.id != carousel.currentImage?.id);
    }
  },
  'fullscreen' // Native button
]