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.
<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>
Gallery of images
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.
<a
data-fancybox="gallery"
data-src="https://lipsum.app/id/2/1600x1200"
data-caption="Optional caption,<br />that can contain <em>HTML</em> 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>
Gallery with one preview image
To create a gallery with a single preview image, simply create links for each item in the gallery, but only make one visible:
<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>
Initial image size
When launching Fancybox, the image can initially be at any zoom level supported by Panzoom.
const options = {
Images: {
initialSize: "fit",
},
};
Secondary click
Combine contentClick: "iterateZoom"
option with the maxScale
option for the Panzoom instance and you can achieve a secondary zoom level.
const options = {
contentClick: "iterateZoom",
Images: {
Panzoom: {
maxScale: 2,
},
},
};
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.
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:
<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:
Fancybox.bind('[data-fancybox="gallery"]', {
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;
},
},
});
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
- setsrcset
attribute for image element;data-sizes
- setsizes
attribute for image element;data-thumb
- custom thumbnail image;data-width
- custom image width;data-height
- custom image height.
Single image
<a href="image-a.jpeg" data-fancybox>
<img src="thumbnail-a.jpeg" />
</a>
Responsive image with srcset and sizes
<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>
Image gallery with thumbnails:
<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
// 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
(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
{
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"