Upgrading #

v5 is a major rewrite of the project. It's not just a migration to Typescript, it was designed to be able to implement most feature requests. As a result, v5 contains breaking changes that affect almost everything.

The following are the notable changes from v4.

Overall #

• All CSS class names are prefixed with f- in order not to confuse with other projects. Except for Fancybox, having the same fancybox- prefixes.
• SASS support is dropped and the project is now focused on CSS variable use.
• It is now easier to include translations when using UMD build.

Panzoom #

• Zooming content first fills the container.
• Supports mouse movement for panning.
• Supports more linear animations.
• Supports content rotation and flipping transformations.
• Supports custom controls.
• New zoom levels.
• More API options and methods.
• Toolbar plugin is rewritten, supports more buttons.
• New Pins plugin.
• Added loading icon.

Carousel #

• Added transitions between slides.
• Added breakpoints option.
• Added RTL support.
• New API methods to add/remove slides.
• Supports vertical navigation.
• Supports nested carousels.
• Supports adaptive height.
• New thumbnails plugin with two types - modern and classic.
• Dots plugin has dynamic mode.
• Loading icon for lazy loading images.

Fancybox #

• Auto-bind is removed for two reasons:
  • if there's been a delay between applying the custom code and the user clicking, Fancybox starts with the default settings, which creates confusion;
  • auto-bind applied the same settings to all elements on the page, and that caused problems with frameworks like React to have different settings per component.
• Fancybox.bind() method now has overload that accepts DOM element as first parameter, this makes it easier to integrate into frameworks like React.
• A significant change is that Fancybox no longer tries to hide the Carousel instance, instead you have to directly interact with the carousel slides and pass parameters to it directly.
• Thumbs plugin has been rewritten to integrate Carousel's thumbnail plugin.
• Toolbar plugin has been rewritten to be easier to use and to support Panzoom's new features.
• Image plugin has been renamed to Images to avoid confusion with the native constructor, it has been rewritten to enable Panzoom's new features.
• The slideshow functionality has been moved to a new plugin.
• New idle mode.
• New compact mode, it is similar to mobile mode in v3.
• Automatically sync with a Carousel without additional code.
• Better handles full screen (still waiting for Safari to fully implement the Fullscreen API).
• Fancybox can properly handle a gallery with scrollable HTML content on mobile devices. It is also possible to include a carousel in the slides.

Example of configuration option changes:

Fancybox.bind("[data-fancybox]", {
  infinite: false,
  slideshow: {
    autoStart: true,
    delay: 3000,
  },
  Toolbar: {
    display: ["slideshow", "close"],
  },
  Image: {
    zoom: false,
  },
});

Fancybox.bind("[data-fancybox]", {
  Carousel: {
    infinite: false,
  },
  Slideshow: {
    playOnStart: true,
    timeout: 3000,
  },
  Toolbar: {
    display: {
      left: [],
      middle: [],
      right: ["slideshow", "close"],
    },
  },
  Images: {
    zoom: false,
  },
});