PhotoSwipe

https://photoswipe.com
Admin
PhotoSwipe is a JavaScript image gallery and lightbox with touch gesture support, responsive images,...
Tokens:34,297
Snippets:287
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Basic Vanilla JS PhotoSwipe Initialization

Source: https://photoswipe.com/getting-started

A fundamental example of initializing PhotoSwipe using vanilla JavaScript. This setup requires explicit paths to the PhotoSwipe modules and is suitable for direct script inclusion.

```javascript
// Include Lightbox
import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';

const lightbox = new PhotoSwipeLightbox({
  // may select multiple "galleries"
  gallery: '#gallery--getting-started',

  // Elements within gallery (slides)
  children: 'a',

  // setup PhotoSwipe Core dynamic import
  pswpModule: () => import('/photoswipe/photoswipe.esm.js')
});
lightbox.init();

```

--------------------------------

### Initialize PhotoSwipe Lightbox with NPM/Yarn Imports

Source: https://photoswipe.com/getting-started

Import and initialize PhotoSwipe Lightbox after installing it via NPM or Yarn. This example demonstrates importing the necessary modules and CSS directly into your JavaScript.

```javascript
import PhotoSwipeLightbox from 'photoswipe/lightbox';
import 'photoswipe/style.css';

const lightbox = new PhotoSwipeLightbox({
  gallery: '#my-gallery',
  children: 'a',
  pswpModule: () => import('photoswipe')
});
lightbox.init();

```

--------------------------------

### Vue.js App Setup

Source: https://photoswipe.com/vue-image-gallery

This is the main entry point for a Vue.js application. It creates and mounts the root Vue component.

```javascript
const { createApp } = require('vue');
import App from './App.vue';

createApp(App).mount('#app');

```

--------------------------------

### Initialize PhotoSwipe with Array Data Source

Source: https://photoswipe.com/data-sources

Use this setup when you have an array of image data and want to leverage PhotoSwipe's zoom animations. Ensure the `pswpModule` is correctly imported.

```javascript
import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';

const images = [
  { id: 1, src: 'https://dummyimage.com/1500x1000/555/fff/?text=Image+1', width: 1500, height: 1000 },
  { id: 2, src: 'https://dummyimage.com/1500x1000/555/fff/?text=Image+2', width: 1500, height: 1000 },
  { id: 3, src: 'https://dummyimage.com/1500x1000/555/fff/?text=Image+3', width: 1500, height: 1000 },
  { id: 4, src: 'https://dummyimage.com/1500x1000/555/fff/?text=Image+4', width: 1500, height: 1000 },
  { id: 5, src: 'https://dummyimage.com/1500x1000/555/fff/?text=Image+5', width: 1500, height: 1000 },
  { id: 6, src: 'https://dummyimage.com/1500x1000/555/fff/?text=Image+6', width: 1500, height: 1000 },
  { id: 7, src: 'https://dummyimage.com/1500x1000/555/fff/?text=Image+7', width: 1500, height: 1000 },
  { id: 8, src: 'https://dummyimage.com/1500x1000/555/fff/?text=Image+8', width: 1500, height: 1000 },
  { id: 9, src: 'https://dummyimage.com/1500x1000/555/fff/?text=Image+9', width: 1500, height: 1000 },
  { id: 10, src: 'https://dummyimage.com/1500x1000/555/fff/?text=Image+10', width: 1500, height: 1000 },
];
const galleryEl = document.querySelector('#gallery--mixed-source');

const lightbox = new PhotoSwipeLightbox({
  dataSource: images,
  pswpModule: () => import('/photoswipe/photoswipe.esm.js'),
});
lightbox.addFilter('thumbEl', (thumbEl, data, index) => {
  const el = galleryEl.querySelector('[data-id="' + data.id + '"] img');
  if (el) {
    return el;
  }
  return thumbEl;
});
lightbox.addFilter('placeholderSrc', (placeholderSrc, slide) => {
  const el = galleryEl.querySelector('[data-id="' + slide.data.id + '"] img');
  if (el) {
    return el.src;
  }
  return placeholderSrc;
});
lightbox.init();

// expose to use within onclick attribute
window.pswpLightbox = lightbox;
```

--------------------------------

### Listening to PhotoSwipe Content Events

Source: https://photoswipe.com/events

Initialize PhotoSwipe Lightbox and set up event listeners for various content lifecycle events. This example demonstrates how to log events such as contentInit, contentLoad, contentAppend, and more.

```javascript
import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';
import PhotoSwipe from '/photoswipe/photoswipe.esm.js';
const lightbox = new PhotoSwipeLightbox({
  gallery: '#gallery--test-content-events',
  children: 'a',
  pswpModule: PhotoSwipe
});
lightbox.on('contentInit', ({ content }) => {
  console.log('contentInit', content);
});
lightbox.on('contentLoad', ({ content, isLazy }) => {
  // content starts to load 
  // can be default prevented  
  // assign elements to `content.element`  
  console.log('contentLoad', content, isLazy);
});
lightbox.on('contentLoadImage', ({ content, isLazy }) => {
  // similar to the previous one, but triggers only for image content  
  // can be default prevented  
  console.log('contentLoadImage', content, isLazy);
});
lightbox.on('loadComplete', ({ content, slide }) => {
  console.log('loadComplete', content);
});
lightbox.on('contentResize', ({ content, width, height }) => {
  // content will be resized  
  // can be default prevented  
  console.log('contentResize', content, width, height);
});
lightbox.on('imageSizeChange', ({ content, width, height, slide }) => {
  // content.element is image  
  console.log('imageSizeChange', content, width, height, slide, slide.index);
});
lightbox.on('contentLazyLoad', ({ content }) => {
  // content start to lazy-load  
  // can be default prevented  
  console.log('contentLazyLoad', content);
});
lightbox.on('contentAppend', ({ content }) => {
  // content is added to dom  
  // can be default prevented  
  // content.slide.container.appendChild(content.element);
  console.log('contentAppend', content);
});
lightbox.on('contentActivate', ({ content }) => {
  // content becomes active (the current slide)  
  // can be default prevented  
  console.log('contentActivate', content);
});
lightbox.on('contentDeactivate', ({ content }) => {
  // content becomes inactive  
  // can be default prevented  
  console.log('contentDeactivate', content);
});
lightbox.on('contentRemove', ({ content }) => {
  // content is removed from DOM  
  // can be default prevented  
  console.log('contentRemove', content);
});
lightbox.on('contentDestroy', ({ content }) => {
  // content will be destroyed  
  // can be default prevented  
  console.log('contentDestroy', content);
});
lightbox.init();
```

--------------------------------

### Install PhotoSwipe via NPM or Yarn

Source: https://photoswipe.com/getting-started

Install PhotoSwipe using a package manager like NPM or Yarn. This is the recommended approach for managing dependencies in modern JavaScript projects.

```bash
npm i photoswipe --save

```

--------------------------------

### Initialize Lightbox with Native Fullscreen

Source: https://photoswipe.com/native-fullscreen-on-open

Configure PhotoSwipe to open in native fullscreen mode by providing a promise that resolves after fullscreen is entered. This example includes a helper function to manage the Fullscreen API and a custom container for the lightbox.

```javascript
import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';

// Simple fullscreen API
const fullscreenAPI = getFullscreenAPI();

// Create custom container
// which will be stretched to fullscreen.
//
// (we can not use PhotoSwipe root element (.pswp),
//  as it is created only after openPromise is resolved)
//
const pswpContainer = getContainer();

function getFullscreenPromise() {
  // Always resolve promise,
  // as wa want to open lightbox 
  // (no matter if fullscreen is supported or not)
  return new Promise((resolve) => {
    if (!fullscreenAPI || fullscreenAPI.isFullscreen()) {
      // fullscreen API not supported, or already fullscreen
      resolve();
      return;
    }

    document.addEventListener(fullscreenAPI.change, (event) => {
      pswpContainer.style.display = 'block';
      // delay to make sure that browser fullscreen animation is finished
      setTimeout(function() {
        resolve();
      }, 300);
    }, { once: true });

    fullscreenAPI.request(pswpContainer);
  });
}

const lightbox = new PhotoSwipeLightbox({
  gallery: '#gallery--native-fs',
  children: 'a',
  pswpModule: () => import('/photoswipe/photoswipe.esm.js'),

  // Add function that returns promise
  openPromise: getFullscreenPromise,
    
  // Append PhotoSwipe to our container
  appendToEl: fullscreenAPI ? pswpContainer : document.body,
  
  // disable opening/closing animations
  showAnimationDuration: 0,
  hideAnimationDuration: 0,
  
  // Add if you're using responsive images
  // since viewport size is unpredictable
  // at initialization
  preloadFirstSlide: false
});
lightbox.on('close', () => {
  pswpContainer.style.display = 'none';
  if (fullscreenAPI && fullscreenAPI.isFullscreen()) {
    fullscreenAPI.exit();
  }
});
lightbox.init();

// Simple fullscreen API helper,
// supports unprefixed and webkit-prefixed versions
function getFullscreenAPI() {
  let api;
  let enterFS;
  let exitFS;
  let elementFS;
  let changeEvent;
  let errorEvent;

  if (document.documentElement.requestFullscreen) {
    enterFS = 'requestFullscreen';
    exitFS = 'exitFullscreen';
    elementFS = 'fullscreenElement';
    changeEvent = 'fullscreenchange';
    errorEvent = 'fullscreenerror';
  } else if (document.documentElement.webkitRequestFullscreen) {
    enterFS = 'webkitRequestFullscreen';
    exitFS = 'webkitExitFullscreen';
    elementFS = 'webkitFullscreenElement';
    changeEvent = 'webkitfullscreenchange';
    errorEvent = 'webkitfullscreenerror';
  }

  if (enterFS) {
    api = {
      request: function (el) {
        if (enterFS === 'webkitRequestFullscreen') {
          el[enterFS](Element.ALLOW_KEYBOARD_INPUT);
        } else {
          el[enterFS]();
        }
      },

      exit: function () {
        return document[exitFS]();
      },

      isFullscreen: function () {
        return document[elementFS];
      },

      change: changeEvent,
      error: errorEvent
    };
  }

  return api;
};

function getContainer() {
  const pswpContainer = document.createElement('div');
  pswpContainer.style.background = '#000';
  pswpContainer.style.width = '100%';
  pswpContainer.style.height = '100%';
  pswpContainer.style.display = 'none';
  document.body.appendChild(pswpContainer);
  return pswpContainer;
}
```

--------------------------------

### Dynamically Add/Remove/Replace Slides with UI Buttons

Source: https://photoswipe.com/methods

This example shows how to initialize PhotoSwipe with a dataSource and register custom UI buttons to dynamically replace the current slide or add new slides. It utilizes `pswp.refreshSlideContent()` to update the display after modifications.

```javascript
import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';  
const lightbox = new PhotoSwipeLightbox({  
  dataSource: [  
    { src: 'https://dummyimage.com/800x600/555/fff/?text=1', width: 800, height: 600 },  
    { src: 'https://dummyimage.com/800x600/555/fff/?text=2', width: 800, height: 600 },  
    { src: 'https://dummyimage.com/800x600/555/fff/?text=3', width: 800, height: 600 },  
    { src: 'https://dummyimage.com/800x600/555/fff/?text=4', width: 800, height: 600 },  
    { src: 'https://dummyimage.com/800x600/555/fff/?text=5', width: 800, height: 600 },  
  ],  
  pswpModule: () => import('/photoswipe/photoswipe.esm.js')  
});  
lightbox.on('uiRegister', () => {  
  const { pswp }  = lightbox;  
  
  let replacedCount = 0;  
  pswp.ui.registerElement({  
    name: 'replaceCurrentSlide',  
    className: 'pswp__button--test-button',  
    order: 9,  
    isButton: true,  
    html: 'Replace Current Slide',  
    onClick: (event, el) => {  
      replacedCount++;  
      pswp.options.dataSource[pswp.currSlide.index] = {  
        src: 'https://dummyimage.com/800x600/555/fff/?text=New%20Slide%20' + replacedCount, width: 800,   
        height: 600  
      };  
      pswp.refreshSlideContent(pswp.currSlide.index);  
    }  
  });  
  
  let addedCount = 0;  
  pswp.ui.registerElement({  
    name: 'addSlide',  
    className: 'pswp__button--test-button',  
    order: 9,  
    isButton: true,  
    html: 'Add Slide',  
    onClick: (event, el) => {  
      addedCount++;  
      pswp.options.dataSource.push({  
        src: 'https://dummyimage.com/800x600/555/fff/?text=Added%20slide%20' + addedCount, width: 800,   
        height: 600  
      });  
      pswp.refreshSlideContent(pswp.getNumItems() - 1);  
    }  
  });  
});  
lightbox.init();  
  
document.querySelector('#btn-add-remove-test').onclick = () => {  
  lightbox.loadAndOpen(0);  
};  

```

--------------------------------

### Handle PhotoSwipe Opening/Closing Transition Events

Source: https://photoswipe.com/events

Capture the start and end of opening and closing animations. These events fire even if transitions are disabled.

```javascript
import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';
const lightbox = new PhotoSwipeLightbox({
  gallery: '#gallery--test-opening-closing-events',
  children: 'a',
  pswpModule: () => import('/photoswipe/photoswipe.esm.js')
});
lighbox.on('openingAnimationStart', () => {
  console.log('openingAnimationStart');
});
lighbox.on('openingAnimationEnd', () => {
  console.log('openingAnimationEnd');
});
lighbox.on('closingAnimationStart', () => {
  console.log('closingAnimationStart');
});
lighbox.on('closingAnimationEnd', () => {
  console.log('closingAnimationEnd');
});
lighbox.init();
```

--------------------------------

### mainClass Option

Source: https://photoswipe.com/options

A string containing one or more class names, separated by spaces, that will be added to the root element of PhotoSwipe. Refer to the Styling page for examples.

```APIDOC
## mainClass

### Description
String, `undefined`. Class that will be added to the root element of PhotoSwipe, may contain multiple separated by space. Example on Styling page.

### Parameters
* **mainClass** (String) - Optional - CSS class(es) to add to the PhotoSwipe root element.

### Request Example
```javascript
import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';
const lightbox = new PhotoSwipeLightbox({
  gallery: '#gallery--mainClass',
  children: 'a',
  pswpModule: () => import('/photoswipe/photoswipe.esm.js'),
  mainClass: 'pswp--custom-theme'
});
lightbox.init();
```
```

--------------------------------

### Internationalize PhotoSwipe Lightbox with Custom Translations

Source: https://photoswipe.com/options

Initialize the PhotoSwipe Lightbox with custom translation strings for UI elements and messages. This example demonstrates how to override default titles and separators.

```javascript
import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';
const lightbox = new PhotoSwipeLightbox({
  gallery: '#gallery--test-i18n',
  children: 'a',

  closeTitle: 'Close the dialog',
  zoomTitle: 'Zoom the photo',
  arrowPrevTitle: 'Go to the previous photo',
  arrowNextTitle: 'Go to the next photo',

  errorMsg: 'The photo cannot be loaded',
  indexIndicatorSep: ' of ',

  pswpModule: () => import('/photoswipe/photoswipe.esm.js'),
  preloadFirstSlide: false
});
lightbox.init();

```

--------------------------------

### Add Download Button

Source: https://photoswipe.com/adding-ui-elements

Register a download button that allows users to download the current image. This example shows how to use an SVG icon and set download attributes dynamically.

```javascript
import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';
const options = {
  gallery:'#gallery--with-download-button',
  children:'a',
  pswpModule: () => import('/photoswipe/photoswipe.esm.js')
};
const lightbox = new PhotoSwipeLightbox(options);
lightbox.on('uiRegister', function() {
  lightbox.pswp.ui.registerElement({
    name: 'download-button',
    order: 8,
    isButton: true,
    tagName: 'a',

    html: {
      isCustomSVG: true,
      inner: '<path d="M20.5 14.3 17.1 18V10h-2.2v7.9l-3.4-3.6L10 16l6 6.1 6-6.1ZM23 23H9v2h14Z" id="pswp__icn-download"/>',
      outlineID: 'pswp__icn-download'
    },

    onInit: (el, pswp) => {
      el.setAttribute('download', '');
      el.setAttribute('target', '_blank');
      el.setAttribute('rel', 'noopener');

      pswp.on('change', () => {
        console.log('change');
        el.href = pswp.currSlide.data.src;
      });
    }
  });
});
lightbox.init();
```

```css
button.pswp__button--test-button {
  background: #136912 !important;
  font-size: 20px;
  color: #fff;
}
```

--------------------------------

### Dynamically Generate 1000 Images for PhotoSwipe

Source: https://photoswipe.com/data-sources

Use the `numItems` and `itemData` filters to dynamically generate a large number of slides. This example creates a gallery with 1000 images using dummy image URLs.

```javascript
import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';
const lightbox = new PhotoSwipeLightbox({
  showHideAnimationType: 'none',
  pswpModule: () => import('/photoswipe/photoswipe.esm.js'),
  preload: [1,2],
});
lightbox.addFilter('numItems', (numItems) => {
  return 1000;
});
lightbox.addFilter('itemData', (itemData, index) => {
  return {
    src: 'https://dummyimage.com/100x100/555/fff/?text=' + (index + 1),
    width: 100,
    height: 100
  };
});
lightbox.init();

document.querySelector('#btn-open-pswp-dyn-gen').onclick = () => {
  lightbox.loadAndOpen(0);
};
```

--------------------------------

### React PhotoSwipe Lightbox Integration

Source: https://photoswipe.com/react-image-gallery

This React component initializes PhotoSwipe Lightbox for an image gallery. It dynamically imports the PhotoSwipe module and cleans up the instance on unmount. Ensure you have 'photoswipe' and 'photoswipe/lightbox' installed.

```javascript
import React, { useEffect } from 'react';
import PhotoSwipeLightbox from 'photoswipe/lightbox';
import 'photoswipe/style.css';

export default function SimpleGallery(props) {
  useEffect(() => {
    let lightbox = new PhotoSwipeLightbox({
      gallery: '#' + props.galleryID,
      children: 'a',
      pswpModule: () => import('photoswipe'),
    });
    lightbox.init();

    return () => {
      lightbox.destroy();
      lightbox = null;
    };
  }, []);

  return (
    <div className="pswp-gallery" id={props.galleryID}>
      {/* Your image links will be rendered here */}
    </div>
  );
}
```

--------------------------------

### Registering a Custom UI Element

Source: https://photoswipe.com/adding-ui-elements

This example demonstrates how to register a custom UI element, specifically a navigation indicator (bullets), using the `ui.registerElement` method within the `uiRegister` event.

```APIDOC
## ui.registerElement()

This method allows you to register custom UI elements within PhotoSwipe. It must be called within or after the `uiRegister` event.

### Method Signature

```javascript
pswp.ui.registerElement({
  name: 'string', // Unique name of the UI element
  className: 'string', // Optional: Classname of the element
  order: number, // Optional: Order of the element
  isButton: boolean, // Optional: If element should be rendered as a button
  tagName: 'string', // Optional: Element tag name
  title: 'string', // Optional: Button title
  ariaLabel: 'string', // Optional: Button aria-label attribute
  html: 'string | object', // Optional: HTML string or SVG data
  appendTo: 'bar' | 'wrapper' | 'root', // Optional: Element container
  onInit: function(el, pswp) { ... }, // Optional: Callback before element is added to DOM
  onClick: function(event, el, pswp) { ... } // Optional: Callback when element is clicked
});
```

### Example Usage

```javascript
import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';

const options = {
  gallery: '#gallery--with-bullets',
  children: 'a',
  pswpModule: () => import('/photoswipe/photoswipe.esm.js')
};

const lightbox = new PhotoSwipeLightbox(options);

lightbox.on('uiRegister', function() {
  lightbox.pswp.ui.registerElement({
    name: 'bulletsIndicator',
    className: 'pswp__bullets-indicator',
    appendTo: 'wrapper',
    onInit: (el, pswp) => {
      const bullets = [];
      let bullet;
      let prevIndex = -1;

      for (let i = 0; i < pswp.getNumItems(); i++) {
        bullet = document.createElement('div');
        bullet.className = 'pswp__bullet';
        bullet.onclick = (e) => {
          pswp.goTo(bullets.indexOf(e.target));
        };
        el.appendChild(bullet);
        bullets.push(bullet);
      }

      pswp.on('change', () => {
        if (prevIndex >= 0) {
          bullets[prevIndex].classList.remove('pswp__bullet--active');
        }
        bullets[pswp.currIndex].classList.add('pswp__bullet--active');
        prevIndex = pswp.currIndex;
      });
    }
  });
});

lightbox.init();
```

### CSS Styling Example

```css
.pswp__bullets-indicator {
  display: flex;
  flex-direction: row;
  align-items: center;
  position: absolute;
  bottom: 30px;
  left: 50%;
  transform: translate(-50%, 0);
}
.pswp__bullet {
  width: 30px;
  height: 30px;
  border-radius: 50%;
  background: #fff;
  margin: 0 5px;
}
.pswp__bullet--active {
  background: green;
}
```

### Notes

- You can find more examples in the `/src/js/ui/` folder within the repository.
- For overriding or adjusting existing buttons, use the `uiElement` filter.
- `registerElement` is a convenient shortcut; you can also append elements manually.
```

--------------------------------

### Register Custom UI Element with ui.registerElement() API

Source: https://photoswipe.com/adding-ui-elements

This example demonstrates how to register a custom UI element using the `pswp.ui.registerElement()` method. It shows various configuration options like `name`, `className`, `order`, `isButton`, `tagName`, `title`, `ariaLabel`, `html`, `appendTo`, `onInit`, and `onClick`. This method is a shortcut for adding custom elements and must be called within or after the `uiRegister` event.

```javascript
pswp.ui.registerElement({
  // Unique name of the UI element,
  name: 'test123',

  // Classname of the element. 
  // Optional, if not defined - name will be used 
  // in format pswp__button--name, or pswp__name
  className: undefined,

  // Order of element, default order elements:
  // counter - 5, zoom button - 10, info - 15, close - 20.
  order: 9,

  // If element should be   
  // rendered as button
  isButton: true,

  // Element tag name,
  // Optional, if not defined - button or div will be used
  tagName: 'a',

  // Button title, optional
  title: 'Button title',   

  // Button aria-label attribute,
  // if not defined - title will be used
  ariaLabel: undefined,
    
  // html string, will be added inside button, optional 
  // can also be an object with svg data
  html: 'Test',   

  // Element container, possible values:
  // - 'bar'  (top toolbar, .pswp__top-bar, default value),   
  // - 'wrapper' (scroll viewport wrapper, .pswp__scroll-wrap),
  // - 'root' (root element of the dialog, .pswp)   
  // If you add a text inside 'wrapper' - it won't be selectable, 
  // as PhotoSwipe intersects all touch events there.  
  appendTo: 'bar',

  // callback is triggered right before   
  // corresponding element is added to DOM  
  // (while dialog is opening/creating)
  onInit: function(el, pswp) {
    // el - reference to your DOM element
    // pswp - PhotoSwipe object
    // You may modify element here, for example:
    el.classList.add('my-test-class');
  },   

  // when user clicks or taps on element
  onClick: function (event, el, pswp) {
    console.log('clicked element:', el);
  }
});

```

--------------------------------

### Custom Viewport Size Function

Source: https://photoswipe.com/options

Provide a `getViewportSizeFn` function to dynamically calculate slide viewport dimensions. This example subtracts 200px from the client width.

```javascript
import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';
const lightbox = new PhotoSwipeLightbox({
  gallery: '#gallery--test-getViewportSizeFn',
  children: 'a',
  pswpModule: () => import('/photoswipe/photoswipe.esm.js'),
  getViewportSizeFn: function(options, pswp) {
    return {
      x: document.documentElement.clientWidth - 200,
      y: window.innerHeight
    };
  }
});
lightbox.init();

```

--------------------------------

### Initial and Secondary Zoom Levels Equal

Source: https://photoswipe.com/adjusting-zoom-level

Sets both initial and secondary zoom levels to 'fill', with a max zoom level of 3. This configuration ensures images start and transition to a filled state.

```javascript
import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';

const lightbox = new PhotoSwipeLightbox({
  gallery:'#gallery--zoom-levels-equal',
  children: 'a',
  mouseMovePan: true,

  initialZoomLevel: 'fill',
  secondaryZoomLevel: 'fill',
  maxZoomLevel: 3,

  pswpModule: () => import('/photoswipe/photoswipe.esm.js')
});
lightbox.init();
```

--------------------------------

### Add Custom Last Slide with Lightbox

Source: https://photoswipe.com/data-sources

This example shows how to add a custom last slide to a PhotoSwipe gallery initialized with the Lightbox module. It uses `numItems` and `itemData` filters to modify the total number of slides and define the content of the last slide.

```javascript
import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';
const lightbox = new PhotoSwipeLightbox({
  gallery: '#gallery--custom-last-slide',
  children: 'a',
  pswpModule: () => import('/photoswipe/photoswipe.esm.js'),

});
lightbox.addFilter('numItems', (numItems) => {
  return ++numItems;
});
lightbox.addFilter('itemData', (itemData, index) => {
  if (index === lightbox.getNumItems() - 1) {
    return {
      html: '<div class="custom-html-slide">This is custom HTML slide. <a href="http://example.com" target="_blank" rel="nofollow">Link</a>.</div>',
    };
  }
  return itemData;
});
lightbox.init();

```

--------------------------------

### itemData Filter

Source: https://photoswipe.com/filters

Modify slide item data. Example on Data sources page.

```APIDOC
lightbox.addFilter('itemData', (itemData, index) => {
  return itemData;
});

```

--------------------------------

### numItems Filter

Source: https://photoswipe.com/filters

Modify the total amount of slides. Example on Data sources page.

```APIDOC
lightbox.addFilter('numItems', (numItems, dataSource) => {
  return numItems;
});

```

--------------------------------

### thumbBounds Filter

Source: https://photoswipe.com/filters

Modify the thumbnail bounds from which the opening zoom animation starts or ends.

```APIDOC
lightbox.addFilter('thumbBounds', (thumbBounds, itemData, index) => {
  return thumbBounds;
});

```

--------------------------------

### Initialize PhotoSwipe with Array Data (Using Lightbox)

Source: https://photoswipe.com/data-sources

This snippet demonstrates initializing PhotoSwipe using the Lightbox module with an array of slide data. It requires dynamically loading the core PhotoSwipe module via `pswpModule`.

```javascript
import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';

const options = {
  dataSource: [

    // simple image
    {
      src: 'https://dummyimage.com/1620x1080/555/fff/?text=1620x1080',
      width: 1620,
      height: 1080,
      alt: 'test image 1'
    },

    {
      src: 'https://dummyimage.com/1950x1300/555/fff/?text=1950x1300',
      width: 1950,
      height: 1300,
      alt: 'test image 2'
    },

    // responsive image
    {
      srcset: 'https://dummyimage.com/1500x1000/555/fff/?text=1500x1000 1500w, https://dummyimage.com/1200x800/555/fff/?text=1200x800 1200w, https://dummyimage.com/600x400/555/fff/?text=600x400 600w',
      src: 'https://dummyimage.com/1500x1000/555/fff/?text=1500x1000',
      width: 1500,
      height: 1000,
      alt: 'test image 3',
    },

    // HTML slide
    {
      html: '<div class="custom-html-slide">This is custom HTML slide. <a href="http://example.com" target="_blank" rel="nofollow">Test Link</a>.</div>'
    }

  ],
  showHideAnimationType: 'none',
  pswpModule: () => import('/photoswipe/photoswipe.esm.js'),
};
const lightbox = new PhotoSwipeLightbox(options);
lightbox.init();

document.querySelector('#btn-open-pswp-from-arr-lightbox').onclick = () => {
  lightbox.loadAndOpen(0); // defines start slide index
};

```

--------------------------------

### thumbEl Filter

Source: https://photoswipe.com/filters

Modify the thumbnail element from which the opening zoom animation starts or ends.

```APIDOC
lightbox.addFilter('thumbEl', (thumbnail, itemData, index) => {
  return thumbnail;
});

```

--------------------------------

### init()

Source: https://photoswipe.com/methods

Initializes the PhotoSwipe Lightbox instance, binding events and allowing for preloading of images. This method must be called once per instance.

```APIDOC
## init()

### Description
Initializes the lightbox, must be called once for each instance. It does not open the dialog, only binds events that would open it (by default just `click`). It also allows preloading images before the dialog is opened.

### Usage
```javascript
const lightbox = new PhotoSwipeLightbox({
  // options
});

/* you may bind events here */

lightbox.init();
```
```

--------------------------------

### Initialize PhotoSwipe with Dynamic Import

Source: https://photoswipe.com/getting-started

This approach dynamically imports the PhotoSwipe module, which can be beneficial for performance if PhotoSwipe is not a primary feature. The `pswpModule` option accepts a function that returns a Promise resolving to the PhotoSwipe module.

```javascript
import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';
const options = {
  gallery: '#gallery--individual a',
  pswpModule: () => import('/photoswipe/photoswipe.esm.js')
};
const lightbox = new PhotoSwipeLightbox(options);
lightbox.init();

```

```javascript
import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';
const options = {
  gallery: '#gallery--responsive-images',
  children: 'a',
  pswpModule: () => import('/photoswipe/photoswipe.esm.js')
};
const lightbox = new PhotoSwipeLightbox(options);
lightbox.init();

```

--------------------------------

### domItemData Filter

Source: https://photoswipe.com/filters

Modify slide item data when it's parsed from a DOM element. Example on Data sources page.

```APIDOC
lightbox.addFilter('domItemData', (itemData, element, linkEl) => {
  return itemData;
});

```

--------------------------------

### Initialize PhotoSwipe Lightbox and Access Instance

Source: https://photoswipe.com/properties

Initialize the PhotoSwipe Lightbox with custom gallery and children selectors. Access the PhotoSwipe Core instance via `lightbox.pswp` within event listeners to interact with its options and elements.

```javascript
import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';
const lightbox = new PhotoSwipeLightbox({
  gallery: '#gallery--custom-bg',
  children: 'a',
  pswpModule: () => import('/photoswipe/photoswipe.esm.js')
});
lightbox.init();

lightbox.on('beforeOpen', () => {
  console.log('PhotoSwipe Core instance:', lightbox.pswp);

  const { pswp } = lightbox;
  console.log('Options (read-only):', pswp.options);
});
lightbox.on('afterInit', () => {
  const { pswp } = lightbox;
  // Elements:
  console.log('Root element', pswp.element);
  console.log('Background element', pswp.bg);
  console.log('Scroll wrapper element', pswp.scrollWrap);
});
lightbox.on('change', () => {
  const { pswp } = lightbox;
  console.log('Slide index', pswp.currIndex);
  console.log('Slide object', pswp.currSlide);
  console.log('Slide object data', pswp.currSlide.data);
});

```

--------------------------------

### Initialize PhotoSwipe with Static Import

Source: https://photoswipe.com/getting-started

Use this method when PhotoSwipe is a primary feature of your page. Ensure PhotoSwipe and the lightbox module are imported directly.

```javascript
import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';
import PhotoSwipe from '/photoswipe/photoswipe.esm.js';

const lightbox = new PhotoSwipeLightbox({
  gallery: '#gallery--no-dynamic-import',
  children: 'a',
  pswpModule: PhotoSwipe
});

lightbox.init();

```

--------------------------------

### Initialize PhotoSwipe Lightbox with ES Modules

Source: https://photoswipe.com/getting-started

Use this snippet to initialize the PhotoSwipe Lightbox using ES modules. Ensure you include the CSS file separately. This method dynamically loads the PhotoSwipe Core.

```html
<script type="module">
  import PhotoSwipeLightbox from 'photoswipe/dist/photoswipe-lightbox.esm.js';
  const lightbox = new PhotoSwipeLightbox({
    gallery: '#my-gallery',
    children: 'a',
    pswpModule: () => import('photoswipe/dist/photoswipe.esm.js')
  });
  lightbox.init();
</script>
```

```html
<link rel="stylesheet" href="photoswipe/dist/photoswipe.css">

```

--------------------------------

### Specify Append Element

Source: https://photoswipe.com/options

Use `appendToEl` to define the DOM element where the PhotoSwipe dialog will be appended when opened. This example appends to an element with the ID '__docusaurus'.

```javascript
import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';
const lightbox = new PhotoSwipeLightbox({
  gallery: '#gallery--test-appendToEl',
  children: 'a',
  pswpModule: () => import('/photoswipe/photoswipe.esm.js'),
  appendToEl: document.querySelector('#__docusaurus')
});
lightbox.init();

```

--------------------------------

### Initialize PhotoSwipe with Dynamic Import

Source: https://photoswipe.com

Use this snippet to initialize PhotoSwipe as an ES module, supporting dynamic imports for better page rendering performance. Ensure the paths to `photoswipe-lightbox.esm.js` and `photoswipe.esm.js` are correct.

```html
<script type="module">
import Lightbox from './photoswipe-lightbox.esm.js';
const lightbox = new Lightbox({
  gallery: '#my-gallery',
  children: 'a',
  pswpModule: () => import('./photoswipe.esm.js')
});
lightbox.init();
</script>
```

--------------------------------

### Initialize PhotoSwipe Lightbox

Source: https://photoswipe.com/events

Basic initialization of the PhotoSwipe lightbox. Ensure this is called after the DOM is ready.

```javascript
const lightbox = new PhotoSwipeLightbox({
  // options...
});
lightbox.init();
```

--------------------------------

### Configure PhotoSwipe with Permanent Preloader

Source: https://photoswipe.com/styling

Initialize PhotoSwipe with a main class that can be used to style the preloader, ensuring it's always visible for debugging purposes.

```javascript
import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';  
const lightbox = new PhotoSwipeLightbox({  
  gallery: '#gallery--perma-preloader',  
  children: 'a',  
  pswpModule: () => import('/photoswipe/photoswipe.esm.js'),  
  mainClass: 'pswp-with-perma-preloader',  
});  
lightbox.init();  


```

--------------------------------

### Initialize PhotoSwipe Lightbox

Source: https://photoswipe.com/methods

Initialize the lightbox instance. This must be called once per instance to bind events like click for opening the dialog and to enable preloading.

```javascript
const lightbox = new PhotoSwipeLightbox({
  // options
});

/* you may bind events here */

lightbox.init();
```

--------------------------------

### Provide PhotoSwipe Core Module Directly

Source: https://photoswipe.com/options

Configure the PhotoSwipe Lightbox by providing the PhotoSwipe Core module directly, instead of using dynamic import. This is suitable when the module is already available in the scope.

```javascript
import PhotoSwipeLightbox from 'photoswipe/dist/photoswipe-lightbox.esm.js';
import PhotoSwipe from 'photoswipe/dist/photoswipe.esm.js';

const lightbox = new PhotoSwipeLightbox({
  pswpModule: PhotoSwipe
  // ...
});

```

--------------------------------

### Initialize PhotoSwipe with Array Data (No Lightbox)

Source: https://photoswipe.com/data-sources

Use this snippet to initialize PhotoSwipe core directly with an array of image or HTML slide data. Ensure the `dataSource` array contains objects with properties like `src`, `width`, `height`, `srcset`, or `html`.

```javascript
import PhotoSwipe from '/photoswipe/photoswipe.esm.js';

const options = {
  dataSource: [

    // simple image
    {
      src: 'https://dummyimage.com/1620x1080/555/fff/?text=1620x1080',
      width: 1620,
      height: 1080,
      alt: 'test image 1'
    },

    {
      src: 'https://dummyimage.com/1950x1300/555/fff/?text=1950x1300',
      width: 1950,
      height: 1300,
      alt: 'test image 2'
    },

    // responsive image
    {
      srcset: 'https://dummyimage.com/1500x1000/555/fff/?text=1500x1000 1500w, https://dummyimage.com/1200x800/555/fff/?text=1200x800 1200w, https://dummyimage.com/600x400/555/fff/?text=600x400 600w',
      src: 'https://dummyimage.com/1500x1000/555/fff/?text=1500x1000',
      width: 1500,
      height: 1000,
      alt: 'test image 3',
    },

    // HTML slide
    {
      html: '<div class="custom-html-slide">This is custom HTML slide. <a href="http://example.com" target="_blank" rel="nofollow">Test Link</a>.</div>'
    }

  ],
  showHideAnimationType: 'none'
};

document.querySelector('#btn-open-pswp-from-arr').onclick = () => {
  options.index = 0; // defines start slide index
  const pswp = new PhotoSwipe(options);
  pswp.init(); // initializing PhotoSwipe core adds it to DOM
};

```

--------------------------------

### Handle PhotoSwipe Initialization Events

Source: https://photoswipe.com/events

Listen for events during PhotoSwipe initialization. Use these to modify the DOM or initial state before PhotoSwipe fully opens.

```javascript
import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';
const lightbox = new PhotoSwipeLightbox({
  gallery: '#gallery--test-init-events',
  children: 'a',
  pswpModule: () => import('/photoswipe/photoswipe.esm.js')
});
lightbox.on('beforeOpen', () => {
  console.log('beforeOpen');
  // photoswipe starts to open
});

lighbox.on('firstUpdate', () => {
  console.log('firstUpdate');
  // photoswipe keeps opening
  // you may modify initial index or basic DOM structure
});

lighbox.on('initialLayout', () => {
  console.log('initialLayout');
  // photoswipe measures size of various elements
  // if you need to read getBoundingClientRect of something - do it here
});

lighbox.on('change', () => {
  // triggers when slide is switched, and at initialization
  console.log('change');
});

lighbox.on('afterInit', () => {
  console.log('afterInit');
  // photoswipe fully initialized and opening transition is running (if available)
});

lighbox.on('bindEvents', () => {
  console.log('bindEvents');
  // photoswipe binds DOM events (such as pointer events, wheel, etc)
});
lighbox.init();
```

--------------------------------

### HTML Structure for WebP Demo

Source: https://photoswipe.com/custom-content

This HTML sets up a gallery for the WebP demo. Each link (`<a>`) represents a slide and includes `href` for the default image, `data-pswp-width` and `data-pswp-height` for dimensions, and `data-pswp-webp-src` for the WebP image source. The `<img>` tag inside the `<a>` is for fallback or preview.

```html
<div class="pswp-gallery" id="gallery--webp-demo">
    <a    
      href="https://cdn.photoswipe.com/photoswipe-demo-images/photos/1/img-2500.jpg"   
      data-pswp-width="1875"   
      data-pswp-height="2500"   
      data-pswp-webp-src="https://cdn.photoswipe.com/photoswipe-demo-images/photos/1/img-2500.webp"  
      target="_blank">
      <img src="https://cdn.photoswipe.com/photoswipe-demo-images/photos/1/img-200.jpg" alt="" />
    </a>

    <a    
      href="https://cdn.photoswipe.com/photoswipe-demo-images/photos/3/img-2500.jpg"   
      data-pswp-width="2500"   
      data-pswp-height="1666"   
      target="_blank">
      <img src="https://cdn.photoswipe.com/photoswipe-demo-images/photos/3/img-200.jpg" alt="" />
    </a>

    <a    
      href="https://cdn.photoswipe.com/photoswipe-demo-images/photos/4/img-2500.jpg"   
      data-pswp-width="2500"   
      data-pswp-height="1667"   
      target="_blank">
      <img src="https://cdn.photoswipe.com/photoswipe-demo-images/photos/4/img-200.jpg" alt="" />
    </a>
    
</div>

```

--------------------------------

### Customize HTML Markup with Custom Data Attributes

Source: https://photoswipe.com/data-sources

Override default HTML requirements by using the `domItemData` filter. This example uses custom data attributes (`data-my-size`, `data-thumb-src`) and sets thumbnail as a background image.

```javascript
import PhotoSwipeLightbox from '/photoswipe/photoswipe-lightbox.esm.js';

const lightbox = new PhotoSwipeLightbox({
  gallery: '#gallery--custom-html-markup',
  children: 'a',

  // Adjust thumbnail selector,
  // (for opening/closing zoom transition)
  thumbSelector: 'a',

  pswpModule: () => import('/photoswipe/photoswipe.esm.js')
});

lightbox.addFilter('domItemData', (itemData, element, linkEl) => {
  if (linkEl) {
    const sizeAttr = linkEl.dataset.mySize;

    itemData.src = linkEl.href;
    itemData.w = Number(sizeAttr.split('x')[0]);
    itemData.h = Number(sizeAttr.split('x')[1]);
    itemData.msrc = linkEl.dataset.thumbSrc;
    itemData.thumbCropped = true;
  }

  return itemData;
});

lightbox.init();
```
Tokens:
Raw