Thumbnails

The Carousel Thumbs plugin adds a thumbnail preview. Here are examples of how to use and customize it for Fancybox.

Basic usage

Declarative

By default, the first image found in the trigger element will be used as the source for the thumbnail:

<a href="https://lipsum.app/id/1/1800x1200" data-fancybox="gallery">
  <img
    src="https://lipsum.app/id/1/300x200"
    width="300"
    height="200"
    alt="Sample image #1"
  />
</a>

A different source can be set using the data-thumb-src attribute. Here is a list of supported data attributes:

Name	Description
data-thumb-src	Custom thumbnail source
data-thumb-alt	Custom alt attribute value for thumbnail
data-thumb-class	Custom class name for a carousel slide containing a thumbnail

Usage example:

<a
  href="https://lipsum.app/id/1/1600x1200"
  data-fancybox="gallery"
  data-thumb-src="https://lipsum.app/id/1/150x100"
  data-thumb-alt="My custom description #1"
  data-thumb-class="my_custom_thumb_class"
>
  <img
    src="https://lipsum.app/id/1/200x150"
    width="200"
    height="150"
    alt="Sample image #1"
  />
</a>

JS Bin Example

Programmatic

Supported slide keys correspond to declarative usage data attributes:

Name	Type
thumbSrc	string | HTMLImageElement
thumbAlt	string
thumbClass	string

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

JS Bin Example

Changing the type

The Thumbs plugin supports three thumbnail types, controlled via the type option:

Type	Description
"modern"	(Default) Apple Photos-style thumbnail strip rendered as a carousel. Thumbnail dimensions and spacing are fully customizable via CSS variables.
"classic"	A draggable carousel of thumbnails, similar to traditional lightbox galleries. Supports vertical orientation and navigation arrows.
"scrollable"	A flat, scrollable list of thumbnails — no carousel instance is created. Useful when you want a vertically scrollable sidebar of thumbnails.

Fancybox.bind("[data-fancybox]", {
  Carousel: {
    Thumbs: {
      type: "classic", // "modern" | "classic" | "scrollable"
    },
  },
});

JS Bin Example

Adding arrows

You can add navigation arrows to the thumbnail carousel by importing the Carousel Arrows plugin and passing it via plugins to the Carousel option of the Thumbs plugin:

import { Arrows } from "@fancyapps/ui/dist/carousel/carousel.arrows.js";
import "@fancyapps/ui/dist/carousel/carousel.arrows.css";

Fancybox.bind("[data-fancybox]", {
  Carousel: {
    Thumbs: {
      type: "classic",
      Carousel: {
        plugins: { Arrows },
      },
    },
  },
});

Here is an example of CSS that resizes the thumbnail viewport:

.fancybox__thumbs {
  --f-arrow-pos: 10px;
  --f-thumbs-padding-x: 80px;

  width: 460px;
  max-width: 100%;
  align-self: center;
}

.fancybox__thumbs .f-thumbs__viewport {
  overflow: hidden;
}

Scrollable thumbnails

With a little CSS, you can easily change the appearance of "scrollable" thumbnails - change the number of columns, thumbnail sizes, spacing, etc. Here is an example of how to make it the same as Fancybox3:

.fancybox__container:has(.fancybox__thumbs.is-scrollable) {
  flex-direction: row;
}

.fancybox__thumbs.is-scrollable {
  --f-thumbs-cols: 1;
  --f-thumbs-gap: 4px;
  --f-thumbs-bg: #ddd;

  --f-thumbs-padding-x: 2px;
  --f-thumbs-padding-y: 2px;
  --f-thumbs-viewport-padding-x: 2px;
  --f-thumbs-viewport-padding-y: 2px;

  --f-thumb-width: 100px;
  --f-thumb-height: 75px;
  --f-thumb-bg: rgba(0, 0, 0, 0.1);
  --f-thumb-focus-shadow: inset 0 0 0 5px rgba(255, 82, 104, 0.5);
  --f-thumb-selected-shadow: inset 0 0 0 5px rgb(255, 82, 104);
  --f-thumb-border-radius: 0;

  --f-scrollbar-track-bg: #fff;
  --f-scrollbar-thumb-bg: #2a2a2a;
}

@media (min-width: 576px) {
  .fancybox__thumbs.is-scrollable {
    --f-thumbs-cols: 2;
  }
}

JS Bin Example

Vertical thumbnails

If you want to display thumbnails vertically, you have two options: use "scrollable" thumbnails, which create a vertically scrollable list, or use "classic" thumbnails with a vertically oriented carousel.

This snippet will change the "classic" thumbnails to vertical and align the thumbnails to the top when they fit in the available area:

Fancybox.bind("[data-fancybox]", {
  Carousel: {
    Thumbs: {
      type: "classic",
      Carousel: {
        vertical: true,
        center: (ref) => {
          return ref.getTotalSlideDim() > ref.getViewportDim();
        },
      },
    },
  },
});

It is also recommended to use the carousel breakpoints option to change the carousel direction depending on the screen size. Example:

Fancybox.bind("[data-fancybox]", {
  Carousel: {
    Thumbs: {
      type: "classic",
      Carousel: {
        center: (ref) => {
          return (
            !ref.isVertical() || ref.getTotalSlideDim() > ref.getViewportDim()
          );
        },
        vertical: false,
        breakpoints: {
          "(min-width: 640px)": {
            vertical: true,
          },
        },
      },
    },
  },
});

JS Bin Example

Hide thumbnails

Hide initially using the Carousel Thumbs plugin's showOnStart option:

Fancybox.bind("[data-fancybox]", {
  Carousel: {
    Thumbs: {
      showOnStart: false,
    },
  },
});

JS Bin Example

If you want to not show them at all, then disable the Thumbs plugin:

Fancybox.bind("[data-fancybox]", {
  Carousel: {
    Thumbs: false,
  },
});

JS Bin Example