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" alt="Gallery picture #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

<a
  href="https://lipsum.app/id/1/1800x1200"
  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/300x200" alt="Gallery picture #1" />
</a>

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

JS Bin Example

Change type

The default thumbnail type is "modern". Here’s how to change it to "classic":

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

JS Bin Example

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

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

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

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

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