TopBox

TopBox is derived from Nivo Lightbox. I created a stack addon for the RapidWeaver publishing platform (named TopBox) some years ago that made use of Nivo Lightbox. I also added Nivo Lightbox to a number of plugins, themes and client websites. Along the way, I found and fixed several bugs in the original Nivo Lightbox and made improvements of my own. Because Nivo Lightbox is no longer actively maintained, I have made my variant of Nivo Lightbox opensource, under the name of 'TopBox'.

TopBox is MIT licensed, so you are free to download and use it wherever and however you want.

Some of the things that are different in TopBox, compared with the original Nivo Lightbox:

TopBox is used in thousands of websites; ranging from small blogs right-up to fortune 100 companies. A durable and flexible lightbox effect you can depend upon. TopBox is maintained on Github as an opensource project.

Using TopBox

Download the source code files from Github. Click here.

Upload the TopBox files (within the /src/ directory) to your web server.

Add a call to topbox.css stylesheet with the <head> section of your webpage like this:

<link rel="stylesheet" media="screen" href="path/to/topbox.css">

Then add the jQuery Javascript call, topbox.js and your function to the end of your webpage, ideally before the closing </body> tag, like this:

<script src="path/to/jquery-3.3.1.min.js"></script>
<script src="path/to/topbox.js"></script>
<script>
	$(document).ready(function() {
		$('.lightbox').topbox();
	});
</script>

The chances are that your webpage already includes CSS and / or jQuery. You might not need the extra jQuery call. So feel free to take only what you need and merge the TopBox code into your existing website code.

To make a link (like an image) open in TopBox with a title, the HTML markup is as simple as this:
<a href="path/to/my-image.jpg" class="lightbox" title="My Image">Click me!</a>

By default, any link with a class of lightbox will trigger a TopBox. However this can be changed to another selector name. attribute or element type, if you prefer.

Examples

Much like any lightbox or modal window effect, TopBox is best-used in moderation for the sensible display of simple content types. Here are some examples of what it can do:

Landscape Image Portrait Image Hi-Res Image SVG HTML5 Audio Open Street Map Google® Maps YouTube™ Video Vimeo™ Video TED Video Animated GIF Inline HTML Content Dailymotion™ Video Brighteon™ Video WebP Image AJAX Content Scrolling iFrame HTML5 Video PDF Embed Not Found (404)

Other Attributes

Content Types
A couple of content types require some additional attributes on your 'trigger' link or button, to tell TopBox how you want the target content handled:

For example, our iFrame example above has the following markup:

<a href="https://wikipedia.org" class="lightbox" data-lightbox-type="iframe">iFrame</a>

Galleries
The example TopBoxes presented above open and close singular items. By giving two or more items a data-lightbox-gallery data attribute, you can effortlessly 'chain' multiple items together like this, with next and previous buttons:

<a href="path/to/my-image.jpg" class="lightbox" data-lightbox-gallery="gallery1">Click me!</a>
Example Gallery

Retina Display Images
High-resolution images (optimised for retina displays) are supported too. Within your link markup for opening a standard resolution image, add a data-lightbox-gallery data attribute like this:

<a href="path/to/my-image.jpg" data-lightbox-hidpi="path/to/my-image@2x.jpg" class="lightbox">Click me!</a>
A high resolution image continues to be saved in either JPG or PNG format at 72 dpi. However it is typically double height and width of the standard resolution image. The image src is swapped for the high-resolution variant on retina displays.

Touch Device Support

Swipe Support
Swipe support lets the end user navigate through a TopBox gallery using finger swipe gestures on their smartphone or tablet device. Swipe to the right to navigate to the previous gallery item or swipe to the left to navigate to the next gallery item.

Swipe support is already enabled by default; there is nothing further you need to add. We are using the excellent TouchSwipe jQuery Plugin to accomplish this.

On the rare occasions you wish to disable swipe support, remove the TouchSwipe plugin code from the top of your topbox.js file and everything within the 'swipe support' comments towards the bottom of your topbox.js file.

PDF Support
Support for embedded PDF files is historically quite poor on devices like the iPhone and iPad. iOS handles a PDF similar to an image. It will only display the first page of a PDF and will restrict the ability to scroll through a PDF file.

To circumvent these problems, we detect common tablet and mobile devices. The embedded PDF file iFrame will be replaced with a simple text instruction and download button. The message displayed is customisable within the API, using the pdfMessage and pdfButton options (documented below). The button works to simply open the PDF in a new browser tab.

Settings

TopBox continues to reuse many of the former Nivo Lightbox options and hooks. Some new ones have been added too. You can pass these options to the plugin like this:

<script>
$(document).ready(function() {
	$('.lightbox').topbox({
		effect: 'fade',
		skin: 'blue_sky',
		keyboardNav: false
	});
});
</script>

Here is a complete list of the options available to you:

Name Type Default Description
effect String 'fade' The opening and closing CSS transition effect. Can be one of fade, fadeScale, slideLeft, slideDown, slideUp or fall.
backgroundBlur Boolean false Blurring takes the contents of the page body and wraps them inside a new topbox_blur_wrapper divisional container. A skin is able to blur or change the opacity of this content using CSS filters, when the lightbox is opened. This can have performance implications in certain setups, so please use with care.
skin String 'darkroom' Name of the skin (theme) to use.
keyboardNav Boolean true If enabled, a person can navigate through the lightbox using their keyboard left, right and escape keys.
clickImgToClose Boolean false Closes the lightbox when the image is clicked or tapped.
clickOverlayToClose Boolean true Makes the lightbox close when its window shade is clicked or tapped.
closeToolTip String 'Close' Title tooltip text displayed on the lightbox close button.
previousToolTip String 'Previous' Title tooltip text displayed on the lightbox previous arrow button.
nextToolTip String 'Next' Title tooltip text displayed on the lightbox next arrow button.
titleSource String 'title' The attribute to use for your titles. Can be a simple title attribute or an HTML5 data attribute like data-lightbox-title if you want something different.
loadingMessage String 'Loading...' Message displayed while the content is loading. Mostly used by images and video.
pdfMessage String 'View the PDF in a new window:' The message displayed on touch devices, where embedded PDF files are not supported.
pdfButton String 'Tap Here' The button label for the PDF button, displayed on touch devices.
errorMessage String 'The requested content cannot be loaded. Please try again later.' Message displayed if the content cannot be loaded.

TopBox also has a number of hooks. Code you place between the opening and closing braces will be run, when the lightbox is in that particular state:

Hooks are added in the same way you add options. They can perform various tasks during different states of the lightbox like this:
<script>
$(document).ready(function() {
	$('.lightbox').topbox({
		effect: 'fade',
		skin: 'blue_sky',
		keyboardNav: false,
		afterShowLightbox: function(lightbox){
			$("form").submit(function(){
				$('.topbox_close').trigger('click');
			});
		}
	});
});
</script>

Skins

Skins (or themes) offer a quick method towards restyling TopBox. By its nature, TopBox is extensively customisable. If you know the basics of CSS, then you are already well on your way towards designing your own lightbox styling!

The default skin used by TopBox is called 'Darkroom'. As the name suggests, this offers a light-on-dark colour scheme. By taking the CSS for Darkroom (towards the end of topbox.css) you can use this as a basis for creating your own skin. The name of our new skin can be passed via the TopBox function (see API for details).

The /src/skins/ directory (within the TopBox source code download) provides a few ready-made lightbox styles to experiment with or modify. Add the call to your CSS file and change the skin option to correspond to the skin name you want to use.

Extras

Change the lightbox size
TopBox makes use of simple and modern CSS markup to control content sizing. We use a mixture of CSS Flexbox, transforms and viewport units of measurement. In essence, the markup to control lightbox sizing is as simple as this:

.topbox_content {
	width: 80vw;
	height: 80vh;
}
As you can see, we use viewport units of measurement (viewport width and viewport height). This provides us a perfectly flexible box and avoids content clashing with lightbox navigation controls or titles. Through this configuration, our completed lightbox is completely fluid on different screen sizes, it responds to the screen changing size or orientation, and there is unlimited space reserved for the lightbox titles of any length. Single images and video scale proportionally to fit. If content (like iFrames, Inline or AJAX) does not fit within the viewable area, they will display scroll bars. Media breakpoints could potentially be used too.

Disable on mobile
Lightboxes serve little purpose on mobile. Disable their triggers below a certain breakpoint width, with simple CSS like this:

@media screen and (max-width: 460px) {
	.lightbox {
		pointer-events: none;
	}
}
In this instance, thumbnail images continue to show but won't do anything when clicked or tapped on screens less-than 460px wide.

Disable scrolling
You can prevent the page background scrolling when the lightbox is open, using some CSS like this:

body.topbox_open {
	overflow: hidden;
}
When the lightbox is opened, the webpage will no longer scroll. Scrolling resumes again, when the lightbox is closed.

Trigger from a URL hash
Make a TopBox open on page load via a 'hash' in the page URL. Add this jQuery within your (document).ready handler:

if(window.location.hash) {
	var hashValue = location.hash.replace(/^#/, '');
	$("." +hashValue).click();
}
For example, https://example.com/#mountain would do a 'virtual' click on the TopBox link that has a class of mountain applied to itself.

Custom video controls
Content types like HTML5 Video, YouTube and Vimeo support custom player controls, using a plugin like Plyr. You may choose to use custom video controls, to give your embedded video's a bit more professionalism. Per the setup instructions for Plyr, add a CSS call to the top of your page:

<link rel="stylesheet" href="path/to/plyr.css">
Then before your TopBox Javascript code at the bottom of the page, call your Plyr script:
<script src="path/to/plyr.js"></script>
The final stage is to initiate the Plyr plugin, when TopBox is opened. This is done by passing the Plyr initialisation through our afterShowLightbox hook, like this:
$(document).ready(function() {
	$('.lightbox').topbox({
		skin: 'darkroom',
		afterShowLightbox: function(lightbox){
			const player = new Plyr('#player', {
				/* Player options */
				autoplay: true
			});
		}
	});
});
Now you should find that HTML5, YouTube and Vimeo video are shown with customisable player controls. Other video types (like Dailymotion, Brighteon and TED) are not supported by Plyr, and we'll display their standard player controls, as normal.

Downloads

Like the sound of TopBox? You can download the source code for TopBox from Github and follow the setup instructions provided on this page.

I also have plugin versions of it compiled and setup ready for use in RapidWeaver, Blocs App and Wordpress. Install these addons, per the normal procedures.

I am a strong advocate of free and opensource software. The source code for TopBox is a free download and provided under the MIT license. Donations via PayPal are welcomed and I am also available for hire as a freelance full-stack web developer.