@failed-successfully/ngx-darkbox-gallery

Darkbox Gallery

Darkbox Gallery is a highly configurable lightbox themed gallery library for Angular applications using the ivy engine (Angular 15+).

---

Why?

There are many, many lightbox themed gallery libraries out there for Angular. Some of them are fairly useable, but most lack a good configuration and adaptability. Therefore the philosophy of Darkbox Gallery (Darkbox for short) is to provide good configuration options so you do not need to write extra logic to adapt Darkbox to your needs. While doing so every configuration has useful defaults so the entry barrier for using Darkbox is as low as possible. So come to the dark side of galleries; we don't keep 🍪🍪.

What does it even look like?

If you are not sure what you can expect from Darkbox please have a look at the current version of our live demo.

How?

Installation

Install npm package for Angular version 12+:

npm i @failed-successfully/ngx-darkbox-gallery

Import the module into your app.module.ts

...
import { NgxDarkboxGalleryModule } from '@failed-successfully/ngx-darkbox-gallery';

@NgModule({
  ...,
  imports: [
    ...,
    NgxDarkboxGalleryModule
  ],
  ...
})
export class AppModule { }

Usage

The simplest way of using Darkbox is to include the component with its default configuration as shown below.

Inclusion in the desired .html file

<darkbox-gallery [images]="images"></darkbox-gallery>

View of the corresponding .ts file

import { Component } from '@angular/core';
import { Image } from '@failed-successfully/ngx-darkbox-gallery';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.scss']
})
export class AppComponent {
  images: Image[] = [{
        url: 'https://picsum.photos/seed/3000/2000',
        thumbnailUrl: 'https://picsum.photos/300/200'
  }];
}

For an example of a more advanced Darkbox configuration have a look at our examples.

Darkbox inputs

Name	Type	Required	Description
images	Image[]	true	List of images displayed in Darkbox
configuration	Configuration	false	see Advanced Configuration
loadMoreImagesEvents	Observable	false	Input to handle click events from the outside world

Image

Name	Type	Required	Description
identifier	string	false	An id to identify the image in events. This is not used by the library itself
url	string	true	URL of the full sized image
thumbnailUrl	string	true	URL of the thumbnail image
caption	string	false	A short caption that can be shown under the image in darkbox
altText	string	false	The alternative text shown when the image can not be loaded

Advanced configuration

Please have a look at all available Darkbox configurations in our complete configuration documentation.

Available events

Almost everything that happens in Darkbox triggers an event. Therefore it is easy for you to know what happened when. It is your choice to react to the provides event (e.g. using it to provide statistics). Currently Darkbox exposes the following events:

Name	Type	Description
imageClicked	Image	Signals that a single image was clicked. The clicked images is being emitted
thumbnailLoaded	Image	Signals that a single thumbnail was loaded. The image containing the thumbnail is being emitted
allThumbnailsLoaded	boolean	Signals that all thumbnails currently displayed have bean loaded
allImagesInDom	boolean	Signals that all images provided from the input are displayed in the DOM. This does not mean that all thumbnails/images are completely loaded
darkboxClosed	boolean	Signals that the lightbox/Darkbox was closed by the user
darkboxNext	boolean	Signals that the user clicked the next image button
darkboxPrev	boolean	Signals that the user clicked the previous image button
darkboxImageLoaded	Image	Signals that the full sized images was loaded. The loaded images is being emitted

Browser support

Browser	Supported versions
Chrome	latest
Firefox	latest and extended support release (ESR)
Edge	2 most recent major versions
IE	No. It's dead, Jim.
Safari	2 most recent major versions
iOS	2 most recent major versions

Found a bug 🐛/🐞?

If you find a bug in Darkbox please open an issue here so we can fix it and make Darkbox better for you and everyone else.