Options

Options are added in key-value pairs and passed as an argument to PhotoSwipe constructor, e.g.:

varoptions={index:3,escKey:false,// ui optiontimeToIdle:4000};vargallery=newPhotoSwipe(someElement,PhotoSwipeUI_Default,someItems,options);gallery.init();// Note that options object is cloned during the initialization.// But you can access it via `gallery.options`.// For example, to dynamically change `escKey`:gallery.options.escKey=false;// `options.escKey = false` will not work

Core

indexinteger0

Start slide index. 0 is the first slide. Must be integer, not a string.

getThumbBoundsFnfunctionundefined

Function should return an object with coordinates from which initial zoom-in animation will start (or zoom-out animation will end).

Object should contain three properties: x (X position, relative to document), y (Y position, relative to document), w (width of the element). Height will be calculated automatically based on size of large image. For example if you return {x:0,y:0,w:50} zoom animation will start in top left corner of your page.

Function has one argument - index of the item that is opening or closing.

In non-modal mode, the template's position relative to the viewport should be subtracted from x and y. Look at the FAQ for more information.

Example that calculates position of thumbnail:

getThumbBoundsFn:function(index){// find thumbnail elementvarthumbnail=document.querySelectorAll('.my-gallery-thumbnails')[index];// get window scroll YvarpageYScroll=window.pageYOffset||document.documentElement.scrollTop;// optionally get horizontal scroll// get position of element relative to viewportvarrect=thumbnail.getBoundingClientRect();// w = widthreturn{x:rect.left,y:rect.top+pageYScroll,w:rect.width};// Good guide on how to get element coordinates:// http://javascript.info/tutorial/coordinates}

If dimensions of your small thumbnail don't match dimensions of large image, consider enabling zoom+fade transition. You can do this by adding option showHideOpacity:true (try adding it to above CodePen to test how it looks). Or disable transition entirely by adding hideAnimationDuration:0, showAnimationDuration:0. More info about this in FAQ.

If you want to "hide" small thumbnail during the animation use opacity:0, not visibility:hidden or display:none. Don't force Paint and Layout at the beginning of the animation to avoid lag.

showHideOpacitybooleanfalse

If set to false: background opacity and image scale will be animated (image opacity is always 1).
If set to true: root PhotoSwipe element opacity and image scale will be animated.

To enable just opacity transition (without scale), do not define getThumbBoundsFn option.

showAnimationDurationinteger333

Initial zoom-in transition duration in milliseconds. Set to 0 to disable.
Besides this JS option, you need also to change transition duration in PhotoSwipe CSS file:

If you're using Sass, you just need to change transition-duration variables in _main-settings.scss.

hideAnimationDurationinteger333

The same as the previous option, just for closing (zoom-out) transition. After PhotoSwipe is opened pswp--open class will be added to the root element, you may use it to apply different transition duration in CSS.

bgOpacitynumber1

Background (.pswp__bg) opacity. Should be a number from 0 to 1, e.g. 0.7. This style is defined via JS, not via CSS, as this value is used for a few gesture-based transitions.

spacingnumber0.12

Spacing ratio between slides. For example, 0.12 will render as a 12% of sliding viewport width (rounded).

allowPanToNextbooleantrue

Allow swipe navigation to next/prev item when current item is zoomed. Option is always false on devices that don't have hardware touch support.

getDoubleTapZoomfunction

Function should return zoom level to which image will be zoomed after double-tap gesture, or when user clicks on zoom icon, or mouse-click on image itself. If you return 1 image will be zoomed to its original size.

Default value:

getDoubleTapZoom:function(isMouseClick,item){// isMouseClick - true if mouse, false if double-tap// item - slide object that is zoomed, usually current// item.initialZoomLevel - initial scale ratio of image// e.g. if viewport is 700px and image is 1400px,// initialZoomLevel will be 0.5if(isMouseClick){// is mouse click on image or zoom icon// zoom to originalreturn1;// e.g. for 1400px image:// 0.5 - zooms to 700px// 2 - zooms to 2800px}else{// is double-tap// zoom to original if initial zoom is less than 0.7x,// otherwise to 1.5x, to make sure that double-tap gesture always zooms imagereturnitem.initialZoomLevel<0.7?1:1.5;}}

Function is called each time zoom-in animation is initiated. So feel free to return different values for different images based on their size or screen DPI.

loopbooleantrue

Loop slides when using swipe gesture. If set to true you'll be able to swipe from last to first image. Option is always false when there are less than 3 slides.

This option has no relation to arrows navigation. Arrows loop is turned on permanently. You can modify this behavior by making custom UI.

pinchToClosebooleantrue

Pinch to close gallery gesture. The gallery’s background will gradually fade out as the user zooms out. When the gesture is complete, the gallery will close.

closeOnScrollbooleantrue

Close gallery on page scroll. Option works just for devices without hardware touch support.

closeOnVerticalDragbooleantrue

Close gallery when dragging vertically and when image is not zoomed. Always false when mouse is used.

mouseUsedbooleanfalse

Option allows you to predefine if mouse was used or not. Some PhotoSwipe feature depend on it, for example default UI left/right arrows will be displayed only after mouse is used. If set to false, PhotoSwipe will start detecting when mouse is used by itself, mouseUsed event triggers when mouse is found.

escKeybooleantrue

arrowKeysbooleantrue

Keyboard left or right arrow key navigation. Option can be changed dynamically (yourPhotoSwipeInstance.options.arrowKeys = false;).

historybooleantrue

If set to false disables history module (back button to close gallery, unique URL for each slide). You can also just exclude history.js module from your build.

galleryUIDinteger1

Gallery unique ID. Used by History module when forming URL. For example, second picture of gallery with UID 1 will have URL: http://example.com/#&gid=1&pid=2.

galleryPIDsbooleanfalse

Enables custom IDs for each slide object that are used when forming URL. If option set set to true, slide objects must have pid (picture identifier) property that can be a string or an integer. For example:

errorMsgstring

Error message when image was not loaded. %url% will be replaced by URL of image.

Default value:

<divclass="pswp__error-msg"><ahref="%url%"target="_blank">The image</a> could not be loaded.</div>

preloadarray[1,1]

Lazy loading of nearby slides based on direction of movement. Should be an array with two integers, first one - number of items to preload before current image, second one - after the current image. E.g. if you set it to [1,3], it'll load 1 image before the current, and 3 images after current. Values can not be less than 1.

mainClassstringundefined

String with name of class that will be added to root element of PhotoSwipe (.pswp). Can contain multiple classes separated by space.

getNumItemsFnfunction

Function that should return total number of items in gallery. By default it returns length of slides array. Don't put very complex code here, function is executed very often.

focusbooleantrue

Will set focus on PhotoSwipe element after it's open.

isClickableElementfunction

Default value:

isClickableElement:function(el){returnel.tagName==='A';}

Function should check if the element (el) is clickable. If it is – PhotoSwipe will not call preventDefault and click event will pass through. Function should be as light is possible, as it's executed multiple times on drag start and drag release.

modalbooleantrue

Controls whether PhotoSwipe should expand to take up the entire viewport. If false, the PhotoSwipe element will take the size of the positioned parent of the template. Take a look at the FAQ for more information.

Default UI Options

Options for PhotoSwipeUI_Default (dist/ui/photoswipe-ui-default.js) are added the same way and to the same object as core options.

// Size of top & bottom bars in pixels,// "bottom" parameter can be 'auto' (will calculate height of caption)// option applies only when mouse is used, // or width of screen is more than 1200px// // (Also refer to `parseVerticalMargin` event)barsSize:{top:44,bottom:'auto'},// Adds class pswp__ui--idle to pswp__ui element when mouse isn't moving for 4000mstimeToIdle:4000,// Same as above, but this timer applies when mouse leaves the windowtimeToIdleOutside:1000,// Delay until loading indicator is displayedloadingIndicatorDelay:1000,// Function builds caption markupaddCaptionHTMLFn:function(item,captionEl,isFake){// item - slide object// captionEl - caption DOM element// isFake - true when content is added to fake caption container// (used to get size of next or previous caption)if(!item.title){captionEl.children[0].innerHTML='';returnfalse;}captionEl.children[0].innerHTML=item.title;returntrue;},// Buttons/elementscloseEl:true,captionEl:true,fullscreenEl:true,zoomEl:true,shareEl:true,counterEl:true,arrowEl:true,preloaderEl:true,// Tap on sliding area should close gallerytapToClose:false,// Tap should toggle visibility of controlstapToToggleControls:true,// Mouse click on image should close the gallery,// only when image is smaller than size of the viewportclickToCloseNonZoomable:true,// Element classes click on which should close the PhotoSwipe.// In HTML markup, class should always start with "pswp__", e.g.: "pswp__item", "pswp__caption".// // "pswp__ui--over-close" class will be added to root element of UI when mouse is over one of these elements// By default it's used to highlight the close button.closeElClasses:['item','caption','zoom-wrap','ui','top-bar'],// Separator for "1 of X" counterindexIndicatorSep:' / ',// Share buttons// // Available variables for URL:// {{url}} - url to current page// {{text}} - title// {{image_url}} - encoded image url// {{raw_image_url}} - raw image urlshareButtons:[{id:'facebook',label:'Share on Facebook',url:'https://www.facebook.com/sharer/sharer.php?u={{url}}'},{id:'twitter',label:'Tweet',url:'https://twitter.com/intent/tweet?text={{text}}&url={{url}}'},{id:'pinterest',label:'Pin it',url:'http://www.pinterest.com/pin/create/button/?url={{url}}&media={{image_url}}&description={{text}}'},{id:'download',label:'Download image',url:'{{raw_image_url}}',download:true}],// Next 3 functions return data for share links// // functions are triggered after click on button that opens share modal,// which means that data should be about current (active) slidegetImageURLForShare:function(shareButtonData){// `shareButtonData` - object from shareButtons array// // `pswp` is the gallery instance object,// you should define it by yourself// returnpswp.currItem.src||'';},getPageURLForShare:function(shareButtonData){returnwindow.location.href;},getTextForShare:function(shareButtonData){returnpswp.currItem.title||'';},// Parse output of share linksparseShareButtonOut:function(shareButtonData,shareButtonOut){// `shareButtonData` - object from shareButtons array// `shareButtonOut` - raw string of share link elementreturnshareButtonOut;}