Fancyapps

Options ​

Fancybox has many options that allow for easy customization. Several options accept a method and use a return value. This allows, for example, to set options like wheel depending on whether the user is using a touchpad mouse device.

Declarative Usage ​

Use the Fancybox.bind() method to launch Fancybox with custom options when the user clicks on the matching element.

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

If you're having trouble setting the options, make sure the selector actually returns your elements, e.g. check the return value of document.querySelectorAll(your_selector):

js
document.querySelectorAll("[data-fancybox]");

Programmatic Usage ​

You can pass a set of options as a second parameter into a Fancybox constructor.

js
new Fancybox(
  // Array containing gallery items
  [
    // Gallery item
    {
      src: "image-a.jpeg",
      thumb: "thumbnail-a.jpeg",
    },
  ],
  // Gallery options
  {
    hideScrollbar: false,
  }
);

Global Options ​

You might want to set options that are common to all instances. Use Fancybox.defaults static property to change default options:

js
Fancybox.defaults.showClass = "f-scaleIn";

If you want to change several values at the same time:

js
Fancybox.defaults = {
  ...Fancybox.defaults,
  showClass: "f-scaleIn",
  hideClass: "f-scaleOut",
};

Component Hierarchy ​

Fancybox is built around the Carousel component, you can customise it using Carousel option. This example disables infinite navigation:

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

JSFiddle Example

This example shows how to change the animations:

js
Fancybox.bind("[data-fancybox]", {
  // Transition effect when changing gallery items
  Carousel: {
    transition: "slide",
  },
  // Disable image zoom animation on opening and closing
  Images: {
    zoom: false,
  },
  // Custom CSS transition on opening
  showClass: "f-fadeIn",
});

JSFiddle Example

Since Carousel component is built around the Panzoom component, you can use Panzoom option to, for example, speed up the swipe animation:

js
Fancybox.bind("[data-fancybox]", {
  Carousel: {
    Panzoom: {
      decelFriction: 0.5,
    },
  },
});

JSFiddle Example

Available Options ​

TIP

See the corresponding plugin page for additional customization options. For example, Images plugin for images, HTML plugin for HTML content, iframes, videos, etc.

animated ​

Should backdrop and UI elements fade in/out on start/close

Type

boolean

Default

true

autoFocus ​

Set focus on first focusable element after displaying content

Type

boolean

Default

true

backdropClick ​

The action to perform when the user clicks on the backdrop

Type

js
ClickAction | ((any?: any) => ClickAction | void)

Default

"close"

Note

js
type ClickAction =
  | "toggleZoom"
  | "toggleCover"
  | "toggleMax"
  | "zoomToFit"
  | "zoomToMax"
  | "iterateZoom"
  | false
  | "close"
  | "next"
  | "prev";

caption ​

Change caption per slide

Type

js
| string
| HTMLElement
| false
| ((
    instance: Fancybox,
    slide: slideType,
    caption?: string | HTMLElement
  ) => string | HTMLElement | false)

Default

``

Optional object to extend options for main Carousel

Type

Partial<CarouselOptionsType>

Default

{}

closeButton ​

If true, a close button will be created above the content

Type

"auto" | boolean

Default

"auto"

closeExisting ​

If true, previously opened instance will be closed

Type

boolean

Default

false

commonCaption ​

If true, only one caption element will be used for all slides

Type

boolean

Default

false

compact ​

If compact mode needs to be activated

Type

boolean | ((instance: Fancybox) => boolean)

Default

js
() =>
    window.matchMedia("(max-width: 578px)

contentClick ​

The action to perform when the user clicks on the content

Type

js
ClickAction | ((any?: any) => ClickAction | void)

Default

"toggleZoom"

Note

js
type ClickAction =
  | "toggleZoom"
  | "toggleCover"
  | "toggleMax"
  | "zoomToFit"
  | "zoomToMax"
  | "iterateZoom"
  | false
  | "close"
  | "next"
  | "prev";

contentDblClick ​

The action to take when the user double-clicks on the content

Type

js
ClickAction | ((any?: any) => ClickAction | void)

Default

false

Note

js
type ClickAction =
  | "toggleZoom"
  | "toggleCover"
  | "toggleMax"
  | "zoomToFit"
  | "zoomToMax"
  | "iterateZoom"
  | false
  | "close"
  | "next"
  | "prev";

defaultDisplay ​

The default value of the CSS display property for hidden inline elements

Type

js
"flex" | "block" | string;

Default

"flex"

defaultType ​

Default content type

Type

js
"image" | "iframe" | "youtube" | "vimeo" | "inline" | "html" | "ajax";

Default

"image"

dragToClose ​

Enable drag-to-close gesture - drag content up/down to close instance

Type

boolean

Default

true

Fullscreen ​

If Fancybox should start in full-screen mode

Type

js
{
  autoStart: boolean;
}

Default

js
{
  autoStart: false;
}

groupAll ​

If true, all matching elements will be grouped together in one group

Type

boolean

Default

false

groupAttr ​

The name of the attribute used for grouping

Type

string

Default

"data-fancybox"

height ​

Change content height per slide

Type

js
| "auto"
| number
| ((instance: Fancybox, slide: slideType) => "auto" | number)

Default

``

hideClass ​

Class name to be applied to the content to hide it.
Note: If you disable image zoom, this class name will be used to run the image hide animation.

Type

string | false

Default

"f-fadeOut"

hideScrollbar ​

If browser scrollbar should be hidden

Type

boolean

Default

true

id ​

Custom id for the instance

Type

number | string

Default

``

idle ​

Timeout in milliseconds after which to activate idle mode

Type

number | false

Default

3500

keyboard ​

Keyboard events

Type

keyboardType

Default

js
{
    Escape: "close",
    Delete: "close",
    Backspace: "close",
    PageUp: "next",
    PageDown: "prev",
    ArrowUp: "prev",
    ArrowDown: "next",
    ArrowRight: "next",
    ArrowLeft: "prev",
}

l10n ​

Localization of strings

Type

Record<string, string>

Default

en

mainClass ​

Custom class name for the container

Type

string

Default

``

on ​

Optional event listeners

Type

Partial<Events>

Default

{}

parentEl ​

Element where container is appended
Note. If no element is specified, container is appended to the document.body

Type

HTMLElement | null

Default

null

placeFocusBack ​

Set focus back to trigger element after closing Fancybox

Type

boolean

Default

true

showClass ​

Class name to be applied to the content to reveal it.
Note: If you disable image zoom, this class name will be used to run the image reveal animation.

Type

string | false

Default

"f-zoomInUp"

src ​

Change source per slide

Type

js
| string
| HTMLElement
| ((instance: Fancybox, slide: slideType) => string | HTMLElement)

Default

``

startIndex ​

Index of active slide on the start

Type

number

Default

0

tpl ​

HTML templates for various elements

Type

js
{
  // Close button icon
  closeButton?: string;

  // Main structure of Fancybox
  main?: string;
}

Default

js
{
  closeButton:
    '<button data-fancybox-close class="f-button is-close-btn" title="{{CLOSE}}"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" tabindex="-1"><path d="M20 20L4 4m16 0L4 20"/></svg></button>',
  main: `<div class="fancybox__container" role="dialog" aria-modal="true" aria-label="{{MODAL}}" tabindex="-1">
  <div class="fancybox__backdrop"></div>
  <div class="fancybox__carousel"></div>
  <div class="fancybox__footer"></div>
</div>`,
}

trapFocus ​

Trap focus inside Fancybox

Type

boolean

Default

true

wheel ​

Mouse wheel event listener

Type

js
| "zoom"
| "pan"
| "close"
| "slide"
| false
| ((
    instance: Fancybox,
    event: MouseEvent
  ) => "zoom" | "pan" | "close" | "slide" | false)

Default

"zoom"

width ​

Change content width per slide

Type

js
| "auto"
| number
| ((instance: Fancybox, slide: slideType) => "auto" | number)

Default

``