DimBox JavaScript library

DimBox is a lightweight and dependency free JavaScript library for displaying images, videos and other content on a web page. It is similar to the original Lightbox and dozens of others out there but does not require any additional libraries like jQuery to function. It also supports long captions in which many others fail miserably.

Installation

DimBox can be used by old school script linking or more modern way by installing via npm.

Old school manual installation

Download DimBox package from DimBox GitHub page. Unzip it to a desired location and link the minified css and js files from dist directory:

It is recommended to put the script element to the end of your HTML document body, although it can be put anywhere inside body or head.

Install with npm

Install DimBox with npm and then just import in in your js:

Remember to include styles as well, either old school by linking the stylesheet or using the DimBox SCSS which gives you the option to set your own values for some variables:

Usage

After including the DimBox js file you can create DimBox links with data-dimbox attribute:

All links having the same value for data-dimbox will be shown in the same gallery. If you wish to have individual images only, you may leave data-dimbox attribute value empty or use unique value for each link.

Setting custom options

You can override default configuration by passing custom options to setConfig method:

See full list of available options.

Options

Data attribute options

Attribute	Notes
`data-dimbox`	All links having the same value for `data-dimbox` will be shown in the same gallery. If you wish to have individual images only, you may leave `data-dimbox` attribute value empty or use unique value for each link.
`data-dimbox-caption`	Caption text to be displayed below the content.
`data-dimbox-ratio`	Iframe aspect ratio. Supported values are `16x9`, `4x3`, `1x1` and `9x16`. Overrides config setting.
`data-dimbox-type`	Type of the content. Valid values are `image`, `video`, `iframe`, `inline` and `ajax`. All other types except `ajax` can be detected automatically.

Configuration options

Name	Type	Default	Notes
`ajaxTemplate`	String	`<div class="dimbox-ajax-container"><div class="dimbox-ajax-content">{{content}}</div><div class="dimbox-caption">{{caption}}</div></div>`	-
`closeOnOverlayClick`	Boolean	`true`	-
`imageTemplate`	String	`<figure class="dimbox-figure"><img src="{{src}}" class="dimbox-image" alt="{{alt}}" /><figcaption class="dimbox-caption">{{caption}}</figcaption></figure>`	-
`iframeRatio`	String	`16x9`	Iframe aspect ratio. Supported values are `16x9`, `4x3`, `1x1` and `9x16`. This setting can be overriden with data attribute `data-dimbox-ratio`.
`iframeTemplate`	String	`<div class="dimbox-iframe-container"><iframe src="{{src}}" class="dimbox-iframe"></iframe><div class="dimbox-caption">{{caption}}</div></div>`	-
`inlineTemplate`	String	`<div class="dimbox-inline-container"><div class="dimbox-inline-content">{{content}}</div><div class="dimbox-caption">{{caption}}</div></div>`	-
`onAfterClose`	Function	`null`	-
`onAfterInit`	Function	`null`	-
`onAfterOpen`	Function	`null`	-
`onAfterUpdateContent`	Function	`null`	-
`onBeforeClose`	Function	`null`	-
`onBeforeInit`	Function	`null`	-
`onBeforeOpen`	Function	`null`	-
`onBeforeUpdateContent`	Function	`null`	-
`onContentLoaded`	Function	`null`	-
`onDownload`	Function	`null`	-
`onXhrComplete`	Function	`null`	-
`selector`	String	`a[data-dimbox]`	-
`sequenceTemplate`	String	`<span class="dimbox-sequence-current">{{current}}</span> / <span class="dimbox-sequence-total">{{total}}</span>`	-
`showDownloadButton`	Boolean	`true`	-
`svgCloseButton`	String	`<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16"><path d="M2.146 2.854a.5.5 0 1 1 .708-.708L8 7.293l5.146-5.147a.5.5 0 0 1 .708.708L8.707 8l5.147 5.146a.5.5 0 0 1-.708.708L8 8.707l-5.146 5.147a.5.5 0 0 1-.708-.708L7.293 8 2.146 2.854Z"/></svg>`	-
`svgDownloadButton`	String	`<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16"><path d="M.5 9.9a.5.5 0 0 1 .5.5v2.5a1 1 0 0 0 1 1h12a1 1 0 0 0 1-1v-2.5a.5.5 0 0 1 1 0v2.5a2 2 0 0 1-2 2H2a2 2 0 0 1-2-2v-2.5a.5.5 0 0 1 .5-.5z"/><path d="M7.646 11.854a.5.5 0 0 0 .708 0l3-3a.5.5 0 0 0-.708-.708L8.5 10.293V1.5a.5.5 0 0 0-1 0v8.793L5.354 8.146a.5.5 0 1 0-.708.708l3 3z"/></svg>`	-
`svgPrevNextButton`	String	`<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M4.646 1.646a.5.5 0 0 1 .708 0l6 6a.5.5 0 0 1 0 .708l-6 6a.5.5 0 0 1-.708-.708L10.293 8 4.646 2.354a.5.5 0 0 1 0-.708z"/></svg>`	This is the next button image (chevron right) which is used also for the previous button but flipped horizontally.
`theme`	String	`'dark'`	Built in themes are `'dark'` and `'light'`.
`videoAutoplay`	Boolean	`true`	-
`videoControls`	Boolean	`true`	-
`videoLoop`	Boolean	`false`	-
`videoTemplate`	String	`<div class="dimbox-video-container"><video src="{{src}}" class="dimbox-video"></video><div class="dimbox-caption">{{caption}}</div></div>`	-
`videoVolume`	Number	`null`	Video initial volume level `0-1`. For example value `0.5` equals to `50%` volume.
`xhrResponseType`	String	`'json'`	-

Methods

DimBox can also be controlled programmatically without user interaction via public methods:

Method	Example	Notes
`close()`	`dimbox.close();`	Closes DimBox.
`init()`	`dimbox.init();`	Re-initializes DimBox. This can be used for example when the DOM has changed after DimBox load.
`next()`	`dimbox.next();`	Changes to next item if available.
`open(el)`	`var myAElement = document.getElementById('myAElement'); dimbox.open(myAElement);`	Opens DimBox as it would by clicking the a element.
`previous()`	`dimbox.previous();`	Changes to previous item if available.
`setConfig(options)`	`dimbox.setConfig({ closeOnOverlayClick: false, theme: 'light' });`	Overrides default config with given options.