Home

Awesome

Darkbox Gallery

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

<hr>

NPM version Downloads PRs Welcome

Darkbox logo

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

NameTypeRequiredDescription
imagesImage[]trueList of images displayed in Darkbox
configurationConfigurationfalsesee Advanced Configuration
loadMoreImagesEventsObservable<void>falseInput to handle click events from the outside world

Image

NameTypeRequiredDescription
identifierstringfalseAn id to identify the image in events. This is not used by the library itself
urlstringtrueURL of the full sized image
thumbnailUrlstringtrueURL of the thumbnail image
captionstringfalseA short caption that can be shown under the image in darkbox
altTextstringfalseThe 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:

NameTypeDescription
imageClickedImageSignals that a single image was clicked. The clicked images is being emitted
thumbnailLoadedImageSignals that a single thumbnail was loaded. The image containing the thumbnail is being emitted
allThumbnailsLoadedbooleanSignals that all thumbnails currently displayed have bean loaded
allImagesInDombooleanSignals that all images provided from the input are displayed in the DOM. This does not mean that all thumbnails/images are completely loaded
darkboxClosedbooleanSignals that the lightbox/Darkbox was closed by the user
darkboxNextbooleanSignals that the user clicked the next image button
darkboxPrevbooleanSignals that the user clicked the previous image button
darkboxImageLoadedImageSignals that the full sized images was loaded. The loaded images is being emitted

Browser support

BrowserSupported versions
Chromelatest
Firefoxlatest and extended support release (ESR)
Edge2 most recent major versions
IENo. It's dead, Jim.
Safari2 most recent major versions
iOS2 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.