a css-only lightbox implementation for compass
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Compass CSS Lightbox

These lightboxes work in all modern browsers with pure CSS. Additional support for Internet Explorer and older browsers is made possible with a small amount of JavaScript.


From the command line:

(sudo) gem install css-lightbox --pre

Add to a project:

// rails: compass.config, other: config.rb
require 'css-lightbox'

// command line
compass install css-lightbox

Or create a new project:

compass -r css-lightbox -f css-lightbox project_directory


The basic CSS-Lightbox works with a combination of internal links, z-index, positioning and the css3 :target selector. Javascript bootstrapping simply interupts the link action, and applys active or inactive classes to the boxes.

Each lightbox contains three important elements:

- Container
    - Box
    - Link to close the box (href="#")

The container gives you extra positioning options, and acts as an optional modal overlay for the page. You can write the HTML to your liking, but here is one example:

<aside id="about-us" class="container">
  <div class="box">
    <!-- Your Lightbox Content -->
    <a href="#" title="close the 'about' lightbox">close</a> <!-- Link to close -->

To open your lightbox, all you need is a link from somewhere else on the page that points at your lightbox:

<a href="#about-us">a link to the about-us lightbox</a>

For a quick, pre-styled lightbox simply apply the lightbox-with-default-styles mixin to your lightbox containers.

.container {
  @include lightbox-with-default-styles;

lightbox-with-default-styles takes three optional arguments, each with defaults that you can override globaly for your project.

  • The first argument is a (relative) selector for the box, and defaults to "> div".
  • The second is a fade-speed using CSS transitions. This defaults to false for no fade.
  • The third defines the JS fallback "active" selector that you are using. It defaults to .active.

Use them like so:

.container {
  @include lightbox-with-default-styles('> div', '300ms', '.visible');

Javascript Bootstrapping

For Javascript bootstrapping in IE (using jQuery), simply link the included lightbox.js and make any needed changes to the HTML-related variables that it uses:

// "lightboxes" should point to the lightbox containers on your page
var lightboxes = $('#lightboxes aside');

// "closeLinks" should point at the links used to close boxes
var closeLinks = $('#lightboxes a[title*="close"]');

// "showClass" is the class to use for active lightboxes
// "hideClass" is used for inactive lightboxes
var showClass = 'active'
var hideClass = 'hidden'

The function is called simply, and the variables can be overridden on each call as needed:

  lightboxBootstrap(lightboxes, closeLinks, showClass, hideClass);

Advanced Lightboxes

But why would you use my styles when you can create your own? For simple lightboxes without any styling at all, you can use the simple lightbox mixin:

.container {
  @include lightbox;

I'll warn you, it's ugly until you add some style, but adding style isn't hard. By default absolute positioning is used on the containers to place them in the top left. You can override that by changing the positioning of your container as you like. You'll find that each solution has advantages and disadvantages.

Available Defaults and Mixins


// Set this to a selector for the inner box.
$lightbox-box-to-style: "> div";

// Set the default fade time, or leave false for no fade
$lightbox-fade: false;

// Set the active selector to be used by the JS fallback
$lightbox-active: ".active";


  • What makes a lightbox inactive


  • What makes a lightbox active


  • Initiallizes lightbox styles, and hides them to be revealed later


  • Shows a lightbox when it should be active

    lightbox-show( $active: $lightbox-active );

  • Set up your lightboxes by applying to each container

    lightbox( $active: $lightbox-active );

  • Set a lightbox to fade

    lightbox-fade( $fade-speed: $lightbox-fade or 500ms );

  • Apply default styles to the lightbox container

    lightbox-default-container-styles( $fade-speed: $lightbox-fade );

  • Apply default styles to the box


  • Apply default styles to the container and box in one fell swoop

    lightbox-default-styles( $style : $lightbox-box-to-style, $fade-speed : $lightbox-fade );

  • Create and style a lightbox all at once

    lightbox-with-default-styles( $style : $lightbox-box-to-style, $fade-speed : $lightbox-fade, $active : $lightbox-active );