Skip to content
On this page

Getting Started

Since Fancybox is written in vanilla JS, it's easy to integrate anywhere. These are general usage instructions, React and Vue integration samples are also available.

Installation

Package manager

sh
# 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:

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

Stackblitz Example

CDN

If you prefer installing from a content delivery network:

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

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.

NOTE

Unlike previous versions, you have to call "Fancybox.bind()" method to enable Fancybox.

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.

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

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

Add click event handler

The final step is to add a handler to the element's click event. Paste this code anywhere on the page after adding the Fancybox JS file:

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

THAT'S IT!

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

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

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

It is also possible to add a click handler only to a specific container. In this 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]:

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

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

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

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

Additional uses

Sometimes you can have multiple links pointing to the same source and this creates duplicates in the gallery. To avoid this, 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:

html
<a href="javascript:;" data-fancybox-trigger="gallery" data-fancybox-index="0">
  <img src="https://lipsum.app/id/1/400x300" />
</a>

JSFiddle Example

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

js
Fancybox.fromNodes(
  Array.from(document.querySelectorAll('[data-fancybox="gallery"]'))
);

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

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

Specify translations like this:

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

Stackblitz Example

UMD module

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

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

js
Fancybox.bind('[data-fancybox="gallery"]', {
  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're stuck, ask for help on StackOverflow (use tags fancybox or fancyapps), our GitHub repository, or join our community on Discord.