Photobox – CSS3 jQuery image gallery

I wanted 3 things from any image gallery script: first, it to be beautiful and posses a great look & feel. second to be lightweight and not use many assets, and third, I want a script that was built with performance at mind.

I was working on something else entirely when I had to find a nice image gallery script. I wanted one of those that the user would basically click a thumbnail and the larger version of the image would be displayed on top of the page, in a modal window fashion.

So, I opened Google search and type of sorts of things, and looked at many scripts that suppose to do that I wanted. I could say, they all sucked big time in one way or another. some because they were not lightweight which means the code must be horrible or has way too many features I don't need, or either they were lightweight but just ugly to look at, and almost all of them were using horrible javascript animations which are very performance-expensive, and now that we have CSS3 transitions and animations for quite a while I see no room for them to exit.

I saw no choice but to write my own script.

Demo page


  • Both the script & CSS are maximum 10k each (minified script, not gziped)
  • Uses silky-smooth, hardware accelerated, CSS3 transitions and animations (for better performance)
  • Pretty UI and easy UX
  • CSS3 preloader, tailored-made. The only image you need is the arrow.png (soon even not that)
  • Works also on IE8 and above, but clearly not as nice as in normal browsers
  • Uses event-delegation on all thumbnails events
  • Observes DOM changes (if images were added or removed) and adapt accordingly
  • Designed so everything can be changed from the CSS (transitions effects ans so on)
  • Uses HTML5 History so you can copy and send a link with the currently viewable image

So what can this script do?

  • Image can be zoomed in and out with mousewheel and navigated using mousemove to move around
  • Bottom row of thumbnails, navigated by mouse movment
  • Shows the image's 'alt' or 'title' attribute text at the bottom
  • Indicate the index of the current viewed image in relation to the total, like so: (36/100)
  • Supports looping after first and last images
  • Supports keyboard keys for navigation and closing the gallery view

How to use

Put photobox.css and then jQuery in your page (make sure it's not a super old version..) I used 1.8.3 to test this script. Then include this script, and run it on a group of images like so:

<html lang="en">
	<meta charset="utf-8">
	<title>Your website..</title>
	<link rel="stylesheet" href="yourStyles.css">
	<link rel="stylesheet" href="photobox/photobox.css">
	<script src="//"></script>
	<script src='photobox/photobox.js'></script>
	<div id='gallery'>
		<a href="">
			<img src="" alt="photo1 title">
		<a href="">
			<img src="" alt="photo2 title">
		<a href="">
			<img src="" alt="photo3 title">
		<a href="">
			<img src="" alt="photo4 title">
		// or with a fancier selector and some settings, and a callback:
		$('#gallery').photobox('a:first', { thumbs:false, time:0 }, imageLoaded);
		function imageLoaded(){
			console.log('image has been loaded...');


  • history Enable/disable HTML5 history using hash urls. Default: 'true'
  • time The time in miliseconds when autoplaying a gallery. Set as '0' to hide the autoplay button completely.. Default: '3000', minimum 1000ms allowed.
  • autoplay should the gallery autoplay on start or not. Default: 'false'
  • loop Loop back to last image before the first one and to the first image after last one. Default: 'true'
  • thumbs Show thumbs of all the images in the gallery at the bottom. Default: 'true'
  • counter Show the current image index position relative to the whole. Example (3,11). Default: 'true'
  • hideFlash Hide flash instances when viewing an image in the gallery. Default: 'true'
  • keys.close Key codes which close the gallery. Default "27, 88, 67"
  • keys.prev Key codes which change to the previous image. Default "37, 80"
  • Key codes which change to the next image. Default "39, 78"

Changing image transition effects

Advanced CSS users would know this, but for rest, you can just copy the below example code at the end of the photobox.css file:

#pbOverlay .imageWrap img, #pbOverlay.hide .imageWrap img.prepare{ transform:rotateX(90deg); -webkit-transform:rotateX(90deg); -ms-transform:rotateX(90deg); }
#pbOverlay.hide .imageWrap img{ transform:rotateX(-90deg); -webkit-transform:rotateX(-90deg); transform:none\9; opacity:.6; }

Basicly, I'm just playing with the image's style state; before it's appearance and during hiding, so you can do whatever here really.

Demo page   photobox on github