Fancyapps
Return to top
On this page

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"