Fancyapps

Options ​

Fancybox has many options that allow for easy customization. Several options accept a method and use a return value. This allows you to, for example, set options depending on screen size, device capabilities, number of items in the gallery, etc.

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

If you are having trouble setting options, make sure your selector is actually returning the elements you want, e.g. check the return value of document.querySelectorAll():

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

Programmatic Usage ​

You can pass a set of options as a second parameter to Fancybox.show() method:

js
Fancybox.show(
  [
    // Array of gallery items
  ],
  {
    // Your custom options
  }
);

Global Options ​

You may want to set options that are common to all instances. Use the API method Fancybox.getDefaults() to access and change the default options. Example:

js
Fancybox.getDefaults().zoomEffect = false;

Available Options ​

ajax ​

Ajax request body

Type

Document | XMLHttpRequestBodyInit | null

Default

null

Optional object to extend options for main Carousel

Type

Partial<CarouselOptions>

Default

{}

backdropClick ​

The action to perform when the user clicks on the backdrop

Type

"close" | false

Default

"close"

closeButton ​

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

Type

"auto" | boolean

Default

"auto"

closeButtonTpl ​

Close button template created above content

Type

string

Default

html
<button class="f-button" title="{{CLOSE}}" data-fancybox-close>
  <svg tabindex="-1" width="24" height="24" viewBox="0 0 24 24">
    <path d="M19.286 4.714 4.714 19.286M4.714 4.714l14.572 14.572" />
  </svg>
</button>

closeExisting ​

If true, previously opened instance will be closed

Type

boolean

Default

false

delegateEl ​

Element that acts as "delegate" element

Type

HTMLElement | undefined

Default

undefined

dragToClose ​

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

Type

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

Default

true

fadeEffect ​

Enable fade animation for interface elements when opening/closing

Type

boolean

Default

true

groupAll ​

If true, all matching elements will be grouped together in one group regardless of the value of data-fancybox attribute

Type

boolean

Default

false

groupAttr ​

The name of the attribute used for grouping

Type

false | string

Default

"data-fancybox"

hideClass ​

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

Type

string | false | ((instance: FancyboxInstance, slide: CarouselSlide) => 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 | undefined | (() => number | string | undefined)

Default

undefined

idle ​

Timeout in milliseconds after which to activate idle mode

Type

false | number

Default

false

keyboard ​

Keyboard events

Type

FancyboxKeyboardType

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

Default localization strings from Fancybox.l10n.en_EN

mainClass ​

Custom class name for the main container

Type

string

Default

""

mainStyle ​

Custom style attributes for the main container

Type

Record<string, string>

Default

{}

mainTpl ​

HTML template for Fancybox main structure

Type

string | (() => string)

Default

html
<dialog class="fancybox__dialog">
  <div class="fancybox__container" tabindex="0" aria-label="{{MODAL}}">
    <div class="fancybox__backdrop"></div>
    <div class="fancybox__carousel"></div>
  </div>
</dialog>

If Fancybox should be true modal window

Type

boolean

Default

true

on ​

Event listeners

Type

Partial<FancyboxEvents>

Default

{}

parentEl ​

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

Type

HTMLElement | undefined | (() => HTMLElement | undefined)

Default

undefined

placeFocusBack ​

After closing Fancybox, set the focus back to the trigger element of the active slide

Type

boolean

Default

true

plugins ​

Optional user plugins

Type

Record<string, FancyboxPlugin>

Default

undefined

showClass ​

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

Type

string | false | ((instance: FancyboxInstance, slide: CarouselSlide) => string | false)

Default

"f-zoomInUp"

startIndex ​

Index of active slide on the start

Type

number

Default

0

sync ​

Reference to a Carousel instance to sync with

Type

CarouselInstance | undefined

Default

undefined

theme ​

Use dark, light color scheme or set based on user preference

Type

"dark" | "light" | "auto"

Default

"dark"

triggerEl ​

Element that acts as "trigger" element

Type

HTMLElement | undefined

Default

undefined

triggerEvent ​

Event that triggered the Fancybox, usually the click event on the trigger element

Type

MouseEvent | undefined

Default

undefined

wheel ​

Optional action to take when a wheel event is detected

Type

"slide" | "close"

Default

undefined

zoomEffect ​

Enable zoom animation from the thumbnail to the final image when opening the Fancybox

Type

boolean

Default

true