TopBox

TopBox is derived from Nivo Lightbox. I created a stack addon for the RapidWeaver publishing platform (named TopBox) around 2012, which made use of Nivo Lightbox. I also added Nivo Lightbox to a number of plugins, themes and client websites as things progressed. Along the way, I found and fixed several bugs in the original Nivo Lightbox and made improvements of my own. Because Nivo Lightbox is seemingly no longer actively updated, I have released 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. Use the ZIP download option.

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

Add a call to topbox.css stylesheet within 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" aria-haspopup="dialog" 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.

Tip: We add the aria-haspopup="dialog" attribute to our link, to improve webpage accessibility.

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 Wistia Video WebP Image AJAX Content Scrolling Text Content iFrame HTML5 Video PDF Document Embed Not Found (404)

Tip: The HTML5 Video, Vimeo and YouTube examples here use custom controls via the excellent Plyr plugin. Setup of this plugin to work with TopBox is documented here.

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" title="iFrame Content" aria-haspopup="dialog" data-lightbox-type="iframe">iFrame</a>

You may be wondering what's the difference between iframe and video-iframe lightbox types? The latter has its height permanently locked to 56.25% tall (16:9 ratio) making it good to use for embedded video types like Wistia, Vidyard, and others. Some of these video providers require additional code adding to your webpage or verification of your webpage link; hence we don't detect these specific video providers automatically like we do with Brighteon, Dailymotion, YouTube or Vimeo.

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, and swipe support on touch screens:

<a href="path/to/my-image.jpg" class="lightbox" aria-haspopup="dialog" 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. Skins included TopBox include:

Add the call to your CSS file and change the skin option to correspond to the skin name, denoted in brackets, you want to use.

Extras

Basic Copy Protection
You can impose basic copy protection on your TopBox content by means of disabling mouse events with CSS:

.topbox_content {
        pointer-events: none;
}
This will stop the 'save image as' option showing, when a user right-clicks on an image. Obviously this will not stop the user still getting the image via other methods (like screengrabs or from the source code)! Pointer events should not be used for content that requires interaction with, such as video.

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.