Fancyapps
Return to top
On this page

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

``