Facebox

Facebox is a jQuery-based, Facebook-style lightbox which can display images, divs, or entire remote pages.

See it in action.

Download the latest release

Compatibility

This release relies on a lot of advanced CSS techniques (box-shadow, border-radius, RGBA). That being said, it's compatible with many browsers.

• Safari 4
• Webkit Nightlies (Chromium, Chrome) as of 4/17/10
• Firefox 3.5
• IE8 (degraded experience)
• IE7 (degraded experience)
• IE6 - I just don't care
• Opera - I just don't care

Usage

Include jQuery, src/facebox.js and src/facebox.css. Then tell facebox where you've put src/loading.gif and src/closelabel.png

$.facebox.settings.closeImage = '/images/facebox/closelabel.png'
$.facebox.settings.loadingImage = '/images/facebox/loading.gif'

Calling facebox() on any anchor tag will do the trick, it's easier to give your Faceboxy links a rel="facebox" and hit them all onDomReady.

jQuery(document).ready(function($) {
  $('a[rel*=facebox]').facebox()
})

Any anchor links with rel="facebox" with now automatically use facebox:

<a href="#terms" rel="facebox">Terms</a>
  Loads the #terms div in the box

<a href="terms.html" rel="facebox">Terms</a>
  Loads the terms.html page in the box

<a href="terms.png" rel="facebox">Terms</a>
  Loads the terms.png image in the box

Positioning the facebox

The facebox will default to appearing in the middle of the user's current screen view. This can be customized with the positionFn option:

jQuery(document).ready(function($) {
  $('a[rel*=facebox]').facebox({
    positionFn: function(){
      $('#facebox').css({
        top: 200,
        left: 300
      })
    }
  });
});

This example is a little bit clunky. Enter

The anchor method

You can anchor the facebox to any element using the following format:

$('#my-nav-bar').facebox('anchor');

This will anchor the facebox to the element with id='my-nav-bar' (if your selector matched multiple elements this will anchor to the first one) The default is to anchor the top-left of the facebox to the bottom-left of the element. This gets you two objects aligned like this:

---------------------------------------------
-               #my-nav-bar                 -
---------------------------------------------
-                    -
-                    -
-       Facebox      -
-                    -
-                    -
----------------------

The anchor method takes two optional parameters: elementAnchorPoint and faceboxAnchorPoint that need to include vertical: and horizontal: values...

$('#my-nav-bar').facebox('anchor',{
  vertical: 'top',
  horizontal: 'right'
},
{
  vertical: 'top',
  horizontal: 'left'
});

This will set the top-left of the facebox to be anchored to the top-right of the element:

-------------------------------------------------------------------
-               #my-nav-bar                 -                     -
---------------------------------------------                     -
                                            -       Facebox       -
                                            -                     -
                                            -                     -
                                            -----------------------

So back to our positioning example:

jQuery(document).ready(function($) {
  $('a[rel*=facebox]').facebox({
    positionFn: function(){ $('#my-nav-bar').facebox('anchor'); }
  });
});

For an even more relevant example go to the section on Events.

Using facebox programmatically

jQuery.facebox('some html')
jQuery.facebox('some html', 'my-groovy-style')

The above will open a facebox with "some html" as the content.

jQuery.facebox(function($) {
  $.get('blah.html', function(data) { $.facebox(data) })
})

The above will show a loading screen before the passed function is called, allowing for a better ajaxy experience.

The facebox function can also display an ajax page, an image, or the contents of a div:

jQuery.facebox({ ajax: 'remote.html' })
jQuery.facebox({ ajax: 'remote.html' }, 'my-groovy-style')
jQuery.facebox({ image: 'stairs.jpg' })
jQuery.facebox({ image: 'stairs.jpg' }, 'my-groovy-style')
jQuery.facebox({ div: '#box' })
jQuery.facebox({ div: '#box' }, 'my-groovy-style')

Events

Want to close the facebox? Trigger the close.facebox document event:

jQuery(document).trigger('close.facebox')

Facebox also has a bunch of other hooks:

• * beforeLoading.facebox
• * loading.facebox (aliased as afterLoading.facebox)
• * beforeReveal.facebox
• * reveal.facebox (aliased as afterReveal.facebox)
• init.facebox
• afterClose.facebox

Simply bind a function to any of these hooks:

$(document).bind('reveal.facebox', function() { ...stuff to do after the facebox and contents are revealed... })

* Indicates a hook that can be bound to the root document, or to an individual element, for example: jQuery(document).ready(function($){ $('a.some-clicky-link').bind('beforeLoading', function(){ $.facebox.settings.positionFn = function(){ $(this).facebox('anchor', {vertical: 'bottom', :horizontal: 'right'}, {vertical: 'top', :horizontal: 'right'}); }; }); });

This will cause the top-right of the facebox to be anchored to the bottom-right of the element when it is displayed, You may need to reset the positionFn later using the following format (false will cause the facebox to be positioned in the center of the page instead of anchored to another element):

$(document).bind('afterReveal', function(){
  $.facebox.settings.positionFn = false;
});

Customization

You can give the facebox container an extra class (to fine-tune the display of the facebox) with the facebox.class rel syntax.

<a href="remote.html" rel="facebox.bolder">text</a>

Contact & Help

If you have questions, feel free to ask on the Google Groups Mailing List. Alternatively if you find a bug, you can open an issue.