Fancyapps

Images ​

This built-in plugin adds support for images. Creates <img> or <picture> element, initializes the Panzoom instance, manages the initial scale and zoom in/out animations.

Examples ​

Single images ​

If you don't want to create a gallery, use an empty data-fancybox attribute.

html
<a
  data-fancybox
  data-src="https://lipsum.app/id/1/1600x1200"
  data-caption="Hello world"
>
  <img src="https://lipsum.app/id/1/200x150" width="200" height="150" alt="" />
</a>

JSFiddle Example

Galleries are created by adding the same attribute data-fancybox value to multiple elements. For example, adding data-fancybox="gallery" attribute to multiple elements, will create a gallery from all these elements.

html
<a
  data-fancybox="gallery"
  data-src="https://lipsum.app/id/2/1600x1200"
  data-caption="Optional caption,&lt;br /&gt;that can contain &lt;em&gt;HTML&lt;/em&gt; code"
>
  <img src="https://lipsum.app/id/2/200x150" width="200" height="150" alt="" />
</a>

<a data-fancybox="gallery" data-src="https://lipsum.app/id/3/1600x1200">
  <img src="https://lipsum.app/id/3/200x150" width="200" height="150" alt="" />
</a>

<a data-fancybox="gallery" data-src="https://lipsum.app/id/4/1600x1200">
  <img src="https://lipsum.app/id/4/200x150" width="200" height="150" alt="" />
</a>

JSFiddle Example

To create a gallery with a single preview image, simply create links for each item in the gallery, but only make one visible:

html
<a data-fancybox="gallery" href="https://lipsum.app/id/60/1600x1200">
  <img src="https://lipsum.app/id/60/200x150" width="200" height="150" alt="" />
</a>

<div style="display:none">
  <a data-fancybox="gallery" href="https://lipsum.app/id/61/1600x1200">
    <img src="https://lipsum.app/id/61/120x80" />
  </a>
  <a data-fancybox="gallery" href="https://lipsum.app/id/62/1600x1200">
    <img src="https://lipsum.app/id/62/120x80" />
  </a>
  <a data-fancybox="gallery" href="https://lipsum.app/id/63/1600x1200">
    <img src="https://lipsum.app/id/63/120x80" />
  </a>
</div>

JSFiddle Example
JSFiddle Example (using data attributes)

Initial image size ​

When launching Fancybox, the image can initially be at any zoom level supported by Panzoom.

js
const options = {
  Images: {
    initialSize: "fit",
  },
};
Try it out

Mouse panning ​

Use Panzoom's panMode option to enable "mouse panning". The mouseMoveFriction option controls the speed of the animation, but mouseMoveFactor specifies how much the mouse should be moved for the image to reach the border of the screen.

Play around with the contentClick option to see what works best for you.

js
const options = {
  contentClick: "toggleCover",
  Images: {
    Panzoom: {
      panMode: "mousemove",
      mouseMoveFactor: 1.1,
      mouseMoveFriction: 0.12,
    },
  },
};
Panning picture #1Panning picture #2Panning picture #3Panning picture #4

JSFiddle Example

Secondary click ​

Combine contentClick: "iterateZoom" option with the maxScale option for the Panzoom instance and you can achieve a secondary zoom level.

js
const options = {
  contentClick: "iterateZoom",
  Images: {
    Panzoom: {
      maxScale: 2,
    },
  },
};

JSFiddle Example

Image protection ​

Use protected option to enable basic image protection against image downloads using the right mouse button. You can also add watermark by setting the background to .fancybox-protected element.

JSFiddle Example

Using <picture> element ​

If you want to provide responsive images and/or multiple image formats, you can create a <picture> element to suit your needs.

Exactly how you create the <picture> element, how you define the sources, is up to your imagination. Here is just one example that uses additional data attributes for links:

html
<a
  href="https://lipsum.app/id/1/800x600"
  data-fancybox="gallery"
  data-media="(max-width: 799px);(min-width: 800px)"
  data-sources="https://lipsum.app/id/1/800x600;https://lipsum.app/id/1/1200x900"
>
  <img src="https://lipsum.app/id/1/200x150" />
</a>

Then use the Images.content option, the return value can be either a <picture> or <img> element. For convenience, it is also possible to return a string to be used as a template:

js
Fancybox.bind("[data-fancybox]", {
  Images: {
    content: (_ref, slide) => {
      let rez = "<picture>";

      const media = slide.media.split(";");

      slide.sources.split(";").map((source, index) => {
        rez += `<source
          media="${media[index] || ""}"
          srcset="${source}"
        />`;
      });

      rez += `<img src="${slide.src}" alt="" />`;

      rez += "</picture>";

      return rez;
    },
  },
});

JSFiddle Example

Usage ​

Declarative ​

The standard way of using Fancybox is with a number of thumbnail images that link to larger images. The data-src (or href) attribute is used to specify the path to the larger version of the image.

Optional image-specific data attributes:

  • data-srcset - set srcset attribute for image element;
  • data-sizes - set sizes attribute for image element;
  • data-thumb - custom thumbnail image;
  • data-width - custom image width;
  • data-height - custom image height.

Single image ​

html
<a href="image-a.jpeg" data-fancybox>
  <img src="thumbnail-a.jpeg" />
</a>

Responsive image with srcset and sizes ​

html
<a
  data-fancybox
  data-src="image-a.jpeg"
  data-srcset="image-a-xl.jpeg 480w, image-a-2xl.jpeg 800w"
  data-sizes="(max-width: 600px) 480px, 800px"
>
  <img src="thumbnail-a.jpeg" />
</a>
html
<a href="image-a.jpeg" data-fancybox="gallery">
  <img src="thumbnail-a.jpeg" />
</a>

<a href="image-b.jpeg" data-fancybox="gallery">
  <img src="thumbnail-b.jpeg" />
</a>

<a href="image-c.jpeg" data-fancybox="gallery">
  <img src="thumbnail-c.jpeg" />
</a>

Programmatic ​

js
// Single image
Fancybox.show([
  {
    src: "image-a.jpeg",
    thumb: "thumbnail-a.jpeg",
  },
]);

// Image gallery with thumbnails
Fancybox.show([
  {
    src: "image-a.jpeg",
    thumb: "thumbnail-a.jpeg",
  },
  {
    src: "image-b.jpeg",
    thumb: "thumbnail-b.jpeg",
  },
  {
    src: "image-c.jpeg",
    thumb: "thumbnail-c.jpeg",
  },
]);

Options ​

content ​

Set custom content per slide

Type

js
(instance: Images, slide: slideType) =>
  string | HTMLElement | HTMLPictureElement;

Default

``

initialSize ​

Initial image zoom level, see Panzoom documentation for more information.

Type

"fit" | "cover" | "full" | "max"

Default

fit

Panzoom ​

Custom options for Panzoom instance, see Panzoom documentation for more information.

Type

Partial<PanzoomOptionsType>

Default

js
{
  maxScale: 1,
}

protected ​

If the image download needs to be prevented

Type

boolean

Default

false

zoom ​

If animate an image with zoom in/out animation when launching/closing Fancybox

Type

boolean

Default

true

zoomOpacity ​

If zoom animation should animate the opacity when launching/closing Fancybox

Type

"auto" | boolean

Default

"auto"