Skip to content

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

License

Notifications You must be signed in to change notification settings

failed-successfully/ngx-darkbox-gallery-library

Repository files navigation

Darkbox Gallery

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


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

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.