Usage

Basically, there are two ways to use Fancybox:

• Declarative
  Make your elements (for example, links) act as trigger elements

• Programmatic
  Launch Fancybox programmatically from anywhere in your code using the API

Declarative

Using Fancybox declaratively means that you create links (or any other HTML element) and Fancybox is launched after the user clicks on them.

Step 1: Create elements

Create your elements and add data-fancybox attribute. Use href or data-src attribute to specify the content source to display in the Fancybox. Optionally, use data-caption attribute to show a caption under the content.

Optional image-specific data attributes:

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

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

Galleries are created by adding the same attribute data-fancybox value to multiple elements. You can mix images, videos and any HTML content in each gallery.

<a href="image-a.jpeg" data-fancybox="gallery" data-caption="Caption #1">
  <img src="thumbnail-a.jpeg" />
</a>

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

Step 2: Add click event handler

The final step is to use the Fancybox.bind() method to add a handler to the click event of the element that launches Fancybox.

Paste this code anywhere on the page after adding the Fancybox JS file:

Fancybox.bind("[data-fancybox]", {
  // Your custom options
});

That is all! Fancybox will now launch after the user clicks on any element that matches the previously used selector [data-fancybox].

JS Bin Example

Tips and tricks

Although Fancybox.bind() method accepts any value supported by JS querySelectorAll method, for example, #gallery a, it is more convenient to use [data-fancybox], because this attribute is also used for grouping.

To set custom options for a specific gallery, simply use the appropriate selector, example:

Fancybox.bind('[data-fancybox="gallery"]', {
  // Your custom options for a specific gallery
});

It is also possible to add a click handler only to a specific container. In the next example, Fancybox will be launched when the user clicks only those elements that are inside the element with ID gallery-wrap and match the selector [data-fancybox].

This technique is useful when building components for frameworks like React, Vue, etc.

Fancybox.bind(document.getElementById("gallery-wrap"), "[data-fancybox]", {
  // Your custom options
});

Programmatic

Launch Fancybox programmatically from anywhere in your code using the API. This is very useful if, for example, you want to show a notification when the user first opens the page (you just have to determine it yourself using cookies or session variables).

Example of how to display simple HTML content:

Fancybox.show(
  [
    {
      html: "<p>Lorem ipsum dolor sit amet.</p>",
    },
  ],
  {
    // Your custom options
  }
);

JS Bin Example

Show image gallery with captions and thumbnails:

Fancybox.show(
  [
    {
      src: "https://lipsum.app/id/1/1800x1200",
      thumbSrc: "https://lipsum.app/id/1/150x100",
      caption: "Sample image #1",
    },
    {
      src: "https://lipsum.app/id/2/1800x1200",
      thumbSrc: "https://lipsum.app/id/2/150x100",
      caption: "Sample image #2",
    },
    {
      src: "https://lipsum.app/id/3/1800x1200",
      thumbSrc: "https://lipsum.app/id/3/150x100",
      caption: "Sample image #3",
    },
  ],
  {
    // Your custom options
  }
);

JS Bin Example

Additional uses

Use delegate element

Sometimes you may need an additional trigger element, such as a button that, when clicked, will open the Fancybox gallery at a specific index. Or, for example, you might want to use additional preview thumbnail.

Simply use the data-fancybox-delegate attribute with the same value as the data-fancybox attribute for other elements. Optionally, use the data-fancybox-index attribute to specify the index of the starting element:

<a href="javascript:;" data-fancybox-delegate="gallery" data-fancybox-index="0">
  <img src="thumbnail.jpg" />
</a>

Launch by specifying a selector or elements

A fairly common request is to run a pre-configured Fancybox after the page loads, when a button is clicked, etc. Use Fancybox.fromSelector() method to launch Fancybox with the selector you used earlier:

Fancybox.fromSelector("[data-fancybox]");

For special use cases, you can use the Fancybox.fromNodes() API method to programmatically launch Fancybox from HTML elements:

Fancybox.fromNodes(Array.from(document.querySelectorAll("[data-fancybox]")), {
  // Your custom options
});