- Overview
- Documents
FancyBox is a tool that offers a nice and elegant way to add zooming functionality for images, html content and multi-media on your webpages. It is built at the top of the popular JavaScript framework jQuery and is both easy to implement and a snap to customize. Fancybox has a following features Responsive (try resizing window while fancyBox is open),Integrated slideshow,New gallery transitions,Uses CSS3 (shadows, round corners).
Notable changes
- Extendable using helpers
- Responsive (try resizing window while fancyBox is open)
- Integrated slideshow
- New gallery transitions
- Uses CSS3 (shadows, round corners)
1. INCLUDE CSS AND JS FILE
<!-- Add jQuery library --> <script type="text/javascript" src="http://code.jquery.com/jquery-latest.min.js"></script> <!-- Add mousewheel plugin (this is optional) --> <script type="text/javascript" src="/fancybox/lib/jquery.mousewheel-3.0.6.pack.js"></script> <!-- Add fancyBox --> <link rel="stylesheet" href="/fancybox/source/jquery.fancybox.css?v=2.1.5" type="text/css" media="screen" /> <script type="text/javascript" src="/fancybox/source/jquery.fancybox.pack.js?v=2.1.5"></script> <!-- Optionally add helpers - button, thumbnail and/or media --> <link rel="stylesheet" href="/fancybox/source/helpers/jquery.fancybox-buttons.css?v=1.0.5" type="text/css" media="screen" /> <script type="text/javascript" src="/fancybox/source/helpers/jquery.fancybox-buttons.js?v=1.0.5"></script> <script type="text/javascript" src="/fancybox/source/helpers/jquery.fancybox-media.js?v=1.0.6"></script> <link rel="stylesheet" href="/fancybox/source/helpers/jquery.fancybox-thumbs.css?v=1.0.7" type="text/css" media="screen" /> <script type="text/javascript" src="/fancybox/source/helpers/jquery.fancybox-thumbs.js?v=1.0.7"></script>
2. HTML
<a class="fancybox" rel="group" href="big_image_1.jpg"><img src="small_image_1.jpg" alt="" /></a> <a class="fancybox" rel="group" href="big_image_2.jpg"><img src="small_image_2.jpg" alt="" /></a>
3. JAVASCRIPT
$(document).ready(function() { $(".fancybox").fancybox(); });
4. OPTIONS
You can pass these options as key/value object to fancybox() method. It is also possible to modify defaults directly at fancyBox JS file or $.fancybox.defaults
Name | Description |
---|---|
padding |
Space inside fancyBox around content. Can be set as array - [top, right, bottom, left]. Integer, Array; Default value: 15 |
margin |
Minimum space between viewport and fancyBox. Can be set as array - [top, right, bottom, left]. Right and bottom margins are ignored if content dimensions exceeds viewport Integer, Array; Default value: 20 |
width |
Default width for 'iframe' and 'swf' content. Also for 'inline', 'ajax' and 'html' if 'autoSize' is set to 'false'. Can be numeric or 'auto'. Number, String; Default value: 800 |
height |
Default height for 'iframe' and 'swf' content. Also for 'inline', 'ajax' and 'html' if 'autoSize' is set to 'false'. Can be numeric or 'auto' Number, String; Default value: 600 |
minWidth |
Minimum width fancyBox should be allowed to resize to Number; Default value: 100 |
minHeight |
Minimum height fancyBox should be allowed to resize to Number; Default value: 100 |
maxWidth |
Maximum width fancyBox should be allowed to resize to Number; Default value: 9999 |
maxHeight |
Maximum height fancyBox should be allowed to resize to Number; Default value: 9999 |
autoSize |
If true, then sets both autoHeight and autoWidth to true Boolean; Default value: true |
autoHeight |
If set to true, for 'inline', 'ajax' and 'html' type content width is auto determined. If no dimensions set this may give unexpected results Boolean; Default value: false |
autoWidth |
If set to true, for 'inline', 'ajax' and 'html' type content height is auto determined. If no dimensions set this may give unexpected results Boolean; Default value: false |
autoResize |
If set to true, the content will be resized after window resize event Boolean; Default value: !isTouch |
autoCenter |
If set to true, the content will always be centered Boolean; Default value: !isTouch |
fitToView |
If set to true, fancyBox is resized to fit inside viewport before opening Boolean; Default value: true |
aspectRatio |
If set to true, resizing is constrained by the original aspect ratio (images always keep ratio; see this example - if you want to change ratio for other media) Boolean; Default value: false |
topRatio |
Top space ratio for vertical centering. If set to 0.5, then vertical and bottom space will be equal. If 0 - fancyBox will be at the viewport top Number; Default value: 0.5 |
leftRatio |
Left space ratio for horizontal centering. If set to 0.5, then left and right space will be equal. If 0 - fancyBox will be at the viewport left Number; Default value: 0.5 |
scrolling |
Set the overflow CSS property to create or hide scrollbars. Can be set to 'auto', 'yes', 'no' or 'visible' String; Default value: 'auto' |
wrapCSS |
Customizable CSS class for wrapping element (useful for custom styling) string; Default value: |
arrows |
If set to true, navigation arrows will be displayed Boolean; Default value: true |
closeBtn |
If set to true, close button will be displayed Boolean; Default value: true |
closeClick |
If set to true, fancyBox will be closed when user clicks the content Boolean; Default value: false |
nextClick |
If set to true, will navigate to next gallery item when user clicks the content Boolean; Default value: false |
mouseWheel |
If set to true, you will be able to navigate gallery using the mouse wheel Boolean; Default value: true |
autoPlay |
If set to true, slideshow will start after opening the first gallery item Boolean; Default value: false |
playSpeed |
Slideshow speed in milliseconds Integer; Default value: 3000 |
preload |
Number of gallery images to preload Integer; Default value: 3 |
modal |
If set to true, will disable navigation and closing Boolean; Default value: false |
loop |
If set to true, enables cyclic navigation. This means, if you click "next" after you reach the last element, first element will be displayed (and vice versa). Boolean; Default value: true |
ajax |
Options for ajax request Object; Default value: { dataType : 'html', headers : { 'X-fancyBox': true } } |
iframe |
Options for content type "iframe" Object; Default value: { scrolling : 'auto', preload : true } |
swf |
Options for content type "swf" Object; Default value: { wmode: 'transparent', allowfullscreen : 'true', allowscriptaccess : 'always' } |
keys |
Define keyboard keys for gallery navigation, closing and slideshow Object; Default value: { next : { 13 : 'left', // enter 34 : 'up', // page down 39 : 'left', // right arrow 40 : 'up' // down arrow }, prev : { 8 : 'right', // backspace 33 : 'down', // page up 37 : 'right', // left arrow 38 : 'down' // up arrow }, close : [27], // escape key play : [32], // space - start/stop slideshow toggle : [70] // letter "f" - toggle fullscreen } |
direction |
Default navigation direction (for navigation arrows, too) Object; Default value: { { next : 'left', prev : 'right' } } |
scrollOutside |
If true, the script will try to avoid horizontal scrolling for iframes and html content Boolean; Default value: true |
index |
Overrides group start index Integer; Default value: 0 |
type |
Overrides type for content. Supported types are 'image', 'inline', 'ajax', 'iframe', 'swf' and 'html' String; Default value: null |
href |
Overrides content source link String; Default value: null |
content |
Overrides content to be displayed String; Default value: null |
title |
Overrides title content, accepts any HTML String; Default value: null |
tpl |
Object containing various templates Object; Default value: { wrap : '<div class="fancybox-wrap" tabIndex="-1"><div class="fancybox-skin"><div class="fancybox-outer"><div class="fancybox-inner"></div></div></div></div>', image : '<img class="fancybox-image" src="{href}" alt="" />', iframe : '<iframe id="fancybox-frame{rnd}" name="fancybox-frame{rnd}" class="fancybox-iframe" frameborder="0" vspace="0" hspace="0"' + ($.browser.msie ? ' allowtransparency="true"' : '') + '></iframe>', error : '<p class="fancybox-error">The requested content cannot be loaded.<br/>Please try again later.</p>', closeBtn : '<a title="Close" class="fancybox-item fancybox-close" href="javascript:;"></a>', next : '<a title="Next" class="fancybox-nav fancybox-next" href="javascript:;"><span></span></a>', prev : '<a title="Previous" class="fancybox-nav fancybox-prev" href="javascript:;"><span></span></a>' } |
openEffect / closeEffect / nextEffect / prevEffect |
Animation effect ('elastic', 'fade' or 'none') for each transition type String; Default value: 'fade', 'fade', 'elastic', 'elastic' |
openSpeed / closeSpeed / nextSpeed / prevSpeed |
The time it takes (in ms, or "slow", "normal", "fast") to complete transition Integer; Default value: 250 |
openEasing / closeEasing / nextEasing / prevEasing |
Easing method for each transition type. You have numerous choices if easing plugin is included String; Default value: 'swing' |
openOpacity / closeOpacity |
If set to true, transparency is changed for elastic transitions Boolean; Default value: true |
openMethod / closeMethod / nextMethod / prevMethod |
Method from $.fancybox.transitions() that handles transition (you can add custom effects there) String; Default value: 'zoomIn' / 'zoomOut' / 'changeIn' / 'changeOut' |
helpers |
Object containing enabled helpers and options for each of them Object; Default value: { overlay : { closeClick : true, // if true, fancyBox will be closed when user clicks on the overlay speedOut : 200, // duration of fadeOut animation showEarly : true, // indicates if should be opened immediately or wait until the content is ready css : {}, // custom CSS properties locked : true // if true, the content will be locked into overlay }, title : { type : 'float' // 'float', 'inside', 'outside' or 'over' } } |
live |
If set to true, fancyBox uses "live" to assign click event. Set to "false", if you need to apply only to current collection, e.g., if using something like -
$("#page").children().filter('a').eq(0).fancybox(); Boolean; Default value: true |
parent |
Parent element of the container. This is useful for ASP.NET where the top element is "form" -
$(".fancybox").fancybox({ parent: "form:first" // jQuery selector }); String; Default value: body |
5. METHODS
The plugin comes with a number of public functions to help you utilize the plugin in a number of different scenarios. Each of these functions can be called as a property of the $.fancybox object.
To use from inside the iframe - <a href="javascript:parent.$.fancybox.close();">Close me</a>
Name | Description |
---|---|
open |
$.fancybox.open( [group], [options] ) Launch fancyBox, the same as $.fancybox([group], [options])First parameter can be in various types, examples: $.fancybox([ {href : 'img1.jpg', title : 'Title'}, {href : 'img2.jpg', title : 'Title'} ]); - array containing objects $.fancybox( {href : 'image.jpg', title : 'Lorem lipsum'} ); - single object $.fancybox( ['image.jpg', 'image.jpg'] ); - array containing links as strings $.fancybox( 'image.jpg' ); - string as source link $.fancybox( [jQuery object] ); $.fancybox( '<h1>Lorem lipsum</h1>' ); |
cancel |
$.fancybox.cancel() Cancel loading image or abort ajax request |
close |
$.fancybox.close( [force] ) If fancyBox is fully opened (open animation has ended) then start closing animation. If not or closing is forced (e.g. called like $.fancybox.close( true )) than fancyBox is removed immediatly |
play |
$.fancybox.play() Start or stop (if already running) slideshow |
next |
$.fancybox.next() Navigate to next gallery item |
prev |
$.fancybox.prev() Navigate to previous gallery item |
jumpto |
$.fancybox.jumpto( [index] ) Navigate to gallery item by index. Item counting starts from 0, e.g. $.fancybox.jumpto( 0 ); will open the first, e.g. $.fancybox.jumpto( 1 ); will second, etc |
reposition |
$.fancybox.reposition() Will center fancyBox inside viewport and toggle position type to fixed or absolute if needed |
update |
$.fancybox.update() Auto-sizes fancyBox height to match height of content |
toggle |
$.fancybox.toggle() If content is resized to fit inside viewport than it will be expanded to full size (and vice verse) |
showLoading |
$.fancybox.showLoading() Shows loading animation |
hideLoading |
$.fancybox.hideLoading() Hides loading animation |
6. CALLBACK
Name | Description |
---|---|
onCancel |
Called after user triggers canceling. Note: If false is returned by the callback, the canceling will be halted |
beforeLoad |
Called before starting to load content. Note: If false is returned by the callback, the loading will be halted |
afterLoad |
Called after content is loaded. Receives two arguments - upcoming and current object Note: If false is returned by the callback, the content will not be shown. |
beforeShow | Called right before open animations has started |
afterShow | Called after open animations has ended |
beforeClose |
Called right after closing has been triggered but not yet started Note: If false is returned by the callback, the closing will be halted. |
afterClose | Called after closing animation has ended |
onUpdate | Called after window resize, scroll or orientation change events are triggered |
onPlayStart | Called after slideshdow has started |
onPlayEnd | Called after slideshdow has stoped |