Getting Started #

Since Fancybox is written in vanilla JS, it's easy to integrate anywhere. You don't need jQuery or any other dependencies!

These are general usage instructions. React, Vue and Angular integration samples are also available.

Installation #

Package manager #

Installing from the NPM package registry and using a build tool is the recommended approach for most users.

# Usage with NPM
$ npm install --save @fancyapps/ui

# and with Yarn
$ yarn add @fancyapps/ui

Once installed, you can include Fancybox as an ES module:

import { Fancybox } from "@fancyapps/ui";
import "@fancyapps/ui/dist/fancybox/fancybox.css";

Stackblitz Example

CDN #

If you prefer installing from a content delivery network:

<script src="https://cdn.jsdelivr.net/npm/@fancyapps/[email protected]/dist/fancybox/fancybox.umd.js"></script>
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@fancyapps/[email protected]/dist/fancybox/fancybox.css"
/>

JSFiddle Example (UMD)
JSFiddle Example (ESM)

Manually #

If you want to download the files and manually upload them to your web server, you can use the CDN links above to download them. The latest code is also always available on GitHub (distribution files will be found in the dist folder).

<script src="fancybox.umd.js"></script>
<link rel="stylesheet" href="fancybox.css" />

Note that the downside to this approach is that you'll have to do this every time you want to update your files to the latest version.

Therefore the recommended way is to use package managers like NPM or use CDN links which will automatically use the latest patch version without affecting your code.

Usage #

Basically, there are two ways to use Fancybox.

Option 1: Declarative #

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

1/2 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.

<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>

2/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
});

JSFiddle 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
});

JSFiddle Example

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
});

JSFiddle Example

Option 2: 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).

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

JSFiddle Example

Additional uses #

Launch by specifying a selector or elements #

A fairly common request is to launch Fancybox on page load or when a button is clicked. Use Fancybox.fromSelector() method to launch Fancybox with the selector you used earlier:

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

JSFiddle Example

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="gallery"]')),
  {
    // Your custom options
  }
);

JSFiddle Example

Use the trigger 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-trigger 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-trigger="gallery" data-fancybox-index="0">
  <img src="https://lipsum.app/id/1/400x300" />
</a>

JSFiddle Example

Localization #

Use l10n option to provide translations.

Translations are already available for some languages. You can view them and provide a new one using an existing one as a template - https://github.com/fancyapps/ui/tree/main/l10n/Fancybox

ESM module #

First, load translations from the corresponding JS file. For example, German (de):

import { de } from '@fancyapps/ui/dist/fancybox/l10n/de.esm.js';

Specify translations like this:

Fancybox.bind("[data-fancybox]", {
  l10n: de,
});

Stackblitz Example
Codesandbox Example (TypeScript)

UMD module #

First, load the corresponding JS file. For example, German (de):

<script src="https://cdn.jsdelivr.net/npm/@fancyapps/[email protected]/dist/fancybox/l10n/de.umd.js"></script>

The translations will then be loaded into the Fancybox.l10n.de object:

Fancybox.bind("[data-fancybox]", {
  l10n: Fancybox.l10n.de,
});

JSFiddle Example

Troubleshooting #

Use the browser tools to check if there are any errors showing up in the console. Keep in mind that any JavaScript error on your page may prevent further code execution.

To verify your installation, simply include in your code, for example, console.log(Fancybox);. If you get an undefined error, Fancybox is not loading successfully and you should double-check your setup.

If you are unfortunately stuck, ask for help on StackOverflow (use tags fancybox or fancyapps), our GitHub repository, or join our community on Discord.