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 ​

Optional object to extend options for main Carousel

Type

Partial<CarouselOptions>

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

dragToClose ​

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

Type

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

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

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

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

{}

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>

on ​

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

User plugins

Type

Plugin[]

Default

[]

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

theme ​

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

Type

"dark" | "light" | "auto"

Default

"dark"

zoomEffect ​

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

Type

boolean

Default

true