Fancybox

https://fancyapps.com/fancybox
Admin
Fancybox is a premium JavaScript lightbox library that provides interactive multimedia display with...
Tokens:23,547
Snippets:345
Trust Score:9.8
Update:1 month ago
Show doc for...
Tokens:
Raw
### Manual Installation Files

Source: https://fancyapps.com/fancybox/get-started/installation

Include the locally downloaded script and stylesheet files in your HTML.

```html
<script src="fancybox.umd.js"></script>
<link rel="stylesheet" href="fancybox.css" />
```

--------------------------------

### Install Fancybox via NPM

Source: https://fancyapps.com/fancybox/get-started/installation

Use this command to install the latest version of Fancybox as a project dependency.

```bash
npm install --save @fancyapps/ui
```

--------------------------------

### Hide thumbnails on start

Source: https://fancyapps.com/fancybox/guides/thumbnails

Use the showOnStart option to hide thumbnails initially.

```javascript
Fancybox.bind("[data-fancybox]", {
  Carousel: {
    Thumbs: {
      showOnStart: false,
    },
  },
});
```

--------------------------------

### fromNodes

Source: https://fancyapps.com/fancybox/api/methods

Starts Fancybox using specific HTML elements.

```APIDOC
## fromNodes(nodes: Array<HTMLElement>, options?: Partial<FancyboxOptions>)

### Description
Start Fancybox using HTML elements.

### Parameters
- **nodes** (Array<HTMLElement>) - Required - The elements to display.
- **options** (Partial<FancyboxOptions>) - Optional - Configuration options.

### Returns
- **FancyboxInstance | undefined**
```

--------------------------------

### fromSelector

Source: https://fancyapps.com/fancybox/api/methods

Starts Fancybox using a previously assigned selector.

```APIDOC
## fromSelector(itemSelector: string, userOptions?: Partial<FancyboxOptions>)
## fromSelector(container: HTMLElement | null, itemSelector: string, userOptions?: Partial<FancyboxOptions>)
## fromSelector(groupSelector: string, itemSelector: string, userOptions?: Partial<FancyboxOptions>)
## fromSelector(container: HTMLElement | null, groupSelector: string, itemSelector: string, userOptions?: Partial<FancyboxOptions>)

### Description
Start Fancybox using the previously assigned selector, optionally scoped to a container or group.

### Returns
- **FancyboxInstance | undefined**
```

--------------------------------

### fromEvent

Source: https://fancyapps.com/fancybox/api/methods

Starts Fancybox using a click event.

```APIDOC
## fromEvent(event: MouseEvent)

### Description
Start Fancybox using click event.

### Parameters
- **event** (MouseEvent) - Required - The mouse event triggering the action.

### Returns
- **FancyboxInstance | undefined**
```

--------------------------------

### Fancybox Component Usage

Source: https://fancyapps.com/fancybox/integration/vue

Example of how to use the Fancybox wrapper component to display a gallery of images.

```vue
<Fancybox
  :fancybox-options="{
    // Your custom options
  }"
>
<a data-fancybox="gallery" href="https://lipsum.app/id/60/1600x1200">
    <img src="https://lipsum.app/id/60/200x150" alt="Sample image #1" />
</a>
<a data-fancybox="gallery" href="https://lipsum.app/id/61/1600x1200">
    <img src="https://lipsum.app/id/61/200x150" alt="Sample image #2" />
</a>
<a data-fancybox="gallery" href="https://lipsum.app/id/62/1600x1200">
    <img src="https://lipsum.app/id/62/200x150" alt="Sample image #3" />
</a>
</Fancybox>
```

--------------------------------

### fromTriggerEl

Source: https://fancyapps.com/fancybox/api/methods

Starts Fancybox using a specific trigger element.

```APIDOC
## fromTriggerEl(triggerEl: HTMLElement, userOptions?: Partial<FancyboxOptions>)

### Description
Start Fancybox using an element that matches the previously assigned selector.

### Returns
- **FancyboxInstance | undefined**
```

--------------------------------

### Usage of useFancybox in a React component

Source: https://fancyapps.com/fancybox/integration/react

Example demonstrating how to use the useFancybox hook within a component to enable gallery functionality on images.

```typescript
function App() {
  const [fancyboxRef] = useFancybox({
    // Your custom options
  });

  return (
    <div ref={fancyboxRef}>
      <a data-fancybox="gallery" href="https://lipsum.app/id/60/1600x1200">
        <img src="https://lipsum.app/id/60/200x150" alt="Sample image #1" />
      </a>
      <a data-fancybox="gallery" href="https://lipsum.app/id/61/1600x1200">
        <img src="https://lipsum.app/id/61/200x150" alt="Sample image #2" />
      </a>
      <a data-fancybox="gallery" href="https://lipsum.app/id/62/1600x1200">
        <img src="https://lipsum.app/id/62/200x150" alt="Sample image #3" />
      </a>
    </div>
  );
}
```

--------------------------------

### Declarative Iframe Configuration

Source: https://fancyapps.com/fancybox/guides/iframes

Examples of using data attributes to configure iframes, including auto-sizing, preloading, dynamic content, and PDF display.

```html
<a href="/iframe.html" data-fancybox data-type="iframe">Defaults </a>

<a href="/iframe.html" data-fancybox data-type="iframe" data-autosize="true">
  Auto-sizing is enabled
</a>

<a href="/iframe.html" data-fancybox data-type="iframe" data-preload="true">
  Preloading is enabled
</a>

<a href="data:text/html,<p>Some HTML</p>" data-fancybox data-type="iframe">
  Dynamic iframe content
</a>

<a data-fancybox data-type="pdf" href="your.pdf">PDF file</a>
```

--------------------------------

### Retrieve Fancybox instance reference

Source: https://fancyapps.com/fancybox/api/methods

Use Fancybox.getInstance() to get a reference to the current instance from anywhere in the code.

```javascript
const fancyboxRef = Fancybox.getInstance();
```

--------------------------------

### Programmatic Map Display

Source: https://fancyapps.com/fancybox/guides/google-maps

Example of displaying a map with custom dimensions using the Fancybox.show method.

```javascript
Fancybox.show([
  {
    src: "https://www.google.com/maps/@51.5039653,-0.1246493,14.12z",
    width: 800,
    height: 600,
  },
]);
```

--------------------------------

### Customizing HTML Plugin Options

Source: https://fancyapps.com/fancybox/guides/iframes

Example of binding Fancybox with custom options for the HTML plugin to enable auto-resizing.

```js
Fancybox.bind("[data-fancybox]", {
  Carousel: {
    Html: {
      autosize: true,
    },
  },
});
```

--------------------------------

### Programmatic single slide caption

Source: https://fancyapps.com/fancybox/guides/captions

Example of showing a single slide with a caption programmatically.

```js
Fancybox.show(
  [
    {
      html: "<p>Lorem ipsum dolor sit amet.</p>",
      caption: "Sample caption",
    },
  ],
  {
    // Your custom options
  }
);
```

--------------------------------

### Import Fancybox in JavaScript

Source: https://fancyapps.com/fancybox/get-started/installation

Import the Fancybox module and its associated CSS file into your project files after installation.

```javascript
import { Fancybox } from "@fancyapps/ui/dist/fancybox/";
import "@fancyapps/ui/dist/fancybox/fancybox.css";
```

--------------------------------

### Supported Google Maps URLs

Source: https://fancyapps.com/fancybox/guides/google-maps

Examples of Google Maps URLs that are automatically recognized by the plugin.

```text
https://www.google.com/maps/place/Googleplex/@37.4220041,-122.0833494,17z/data=!4m5!3m4!1s0x0:0x6c296c66619367e0!8m2!3d37.4219998!4d-122.0840572
https://maps.google.com/?ll=48.857995,2.294297&spn=0.007666,0.021136&t=m&z=16
https://www.google.com/maps/@37.7852006,-122.4146355,14.65z
https://www.google.com/maps/search/Empire+State+Building/
https://www.google.com/maps/search/?api=1&query=centurylink+field
https://www.google.com/maps/search/?api=1&query=47.5951518,-122.3316393
```

--------------------------------

### Use a delegate element

Source: https://fancyapps.com/fancybox/get-started/usage

Use data-fancybox-delegate to trigger a gallery from an external element, optionally specifying the starting index.

```html
<a href="javascript:;" data-fancybox-delegate="gallery" data-fancybox-index="0">
  <img src="thumbnail.jpg" alt="Gallery thumbnail" />
</a>
```

--------------------------------

### HTML Sidebar Content Setup

Source: https://fancyapps.com/fancybox/plugins/sidebar

Define sidebar content using an HTML element with a data-fancybox-caption attribute matching the trigger element's data-fancybox value.

```html
<div data-fancybox-caption="gallery" style="display: none">
  Sidebar content
  <button class="f-button" title="Close" data-fancybox-close>Close</button>
</div>

<a data-fancybox="gallery" href="https://lipsum.app/id/17/1800x1200">
  <img alt="Gallery picture #1" src="https://lipsum.app/id/17/300x200" width="300" height="200" />
</a>
```

--------------------------------

### Launch by selector

Source: https://fancyapps.com/fancybox/get-started/usage

Use Fancybox.fromSelector() to programmatically launch a pre-configured Fancybox instance.

```js
Fancybox.fromSelector("[data-fancybox]");
```

--------------------------------

### show

Source: https://fancyapps.com/fancybox/api/methods

Creates a new Fancybox instance.

```APIDOC
## show(slides?: Partial<CarouselSlide>[], options?: Partial<FancyboxOptions>)

### Description
Create new Fancybox instance with provided options.

### Returns
- **FancyboxInstance | undefined**
```

--------------------------------

### Import Compact Mode files

Source: https://fancyapps.com/fancybox/plugins/compactmode

Include the necessary JavaScript and CSS files for the Compact Mode plugin.

```javascript
import { Compactmode } from "@fancyapps/ui/dist/fancybox/fancybox.compactmode.js";
import "@fancyapps/ui/dist/fancybox/fancybox.compactmode.css";
```

--------------------------------

### Displaying a video gallery with thumbnails

Source: https://fancyapps.com/fancybox/guides/videos

Create a video gallery using Fancybox.show with thumbSrc for thumbnails.

```js
Fancybox.show([
  {
    src: "https://www.youtube.com/watch?v=z2X2HaTvkl8",
    thumbSrc: "http://i3.ytimg.com/vi/z2X2HaTvkl8/hqdefault.jpg",
  },
  {
    src: "https://www.youtube.com/watch?v=dZRqB0JLizw",
    thumbSrc: "http://i3.ytimg.com/vi/dZRqB0JLizw/hqdefault.jpg",
  },
  {
    src: "https://vimeo.com/259411563",
    thumbSrc: "https://f.vimeocdn.com/images_v6/lohp/video1_thumbnail.png",
  },
]);
```

--------------------------------

### Configure download button

Source: https://fancyapps.com/fancybox/guides/toolbar

Add a download button to the toolbar. Use data-download-src to specify the source and data-download-filename for the suggested filename.

```html
<a
  href="https://lipsum.app/id/15/1600x1200/"
  data-fancybox="gallery"
  data-download-src="https://lipsum.app/id/15/3200x2400"
>
  <img src="https://lipsum.app/id/15/200x150" alt="Gallery image" />
</a>
```

```javascript
Fancybox.bind("[data-fancybox]", {
  Carousel: {
    Toolbar: {
      display: {
        left: ["counter"],
        middle: [],
        right: ["download", "thumbs", "close"],
      },
    },
  },
});
```

--------------------------------

### Fancybox.show()

Source: https://fancyapps.com/fancybox/api/options

Programmatically opens a Fancybox instance with a set of items and options.

```APIDOC
## Fancybox.show(items, options)

### Description
Opens a new Fancybox instance programmatically.

### Parameters
- **items** (Array) - Required - Array of gallery items to display.
- **options** (object) - Optional - Configuration object for the instance.
```

--------------------------------

### Compactmode Plugin Configuration

Source: https://fancyapps.com/fancybox/plugins/compactmode

How to import and initialize the Compactmode plugin within the Fancybox constructor.

```APIDOC
import { Compactmode } from "@fancyapps/ui/dist/fancybox/fancybox.compactmode.js";
import "@fancyapps/ui/dist/fancybox/fancybox.compactmode.css";

Fancybox.bind("[data-fancybox]", {
  plugins: { Compactmode },
});
```

--------------------------------

### Displaying MPD files with dash.js

Source: https://fancyapps.com/fancybox/guides/videos

Use data-type="html5video" and data-html5video-format to handle custom sources, then initialize the player via the Carousel.attachSlideEl event.

```html
<a
  href="https://dash.akamaized.net/akamai/bbb_30fps/bbb_30fps.mpd"
  data-fancybox
  data-type="html5video"
  data-html5video-format="application/dash+xml"
>
  <img
    alt="Video poster"
    width="240"
    height="180"
    src="https://reference.dashif.org/dash.js/nightly/samples/lib/img/bbb-1.jpg"
  />
</a>
```

```js
Fancybox.bind("[data-fancybox]", {
  on: {
    "Carousel.attachSlideEl": (fancyboxRef, carouselRef, slide) => {
      const videoEl = slide.el?.querySelector("video");

      if (videoEl && slide.src.endsWith(".mpd")) {
        const player = dashjs.MediaPlayer().create();
        player.initialize(videoEl, slide.src, true);
        player.setMuted(false);
      }
    },
  },
});
```

--------------------------------

### Instance Methods

Source: https://fancyapps.com/fancybox/api/methods

A collection of methods to control and query a Fancybox instance.

```APIDOC
## close()
### Description
Initiate closing the instance.
### Parameters
- **ev** (Event) - Optional - The event that triggered the close.
- **customHideClass** (string) - Optional - A custom CSS class to apply during hiding.
### Returns
- **void**

## destroy()
### Description
Destroy the instance.
### Returns
- **void**

## getCarousel()
### Description
Retrieve reference to the carousel instance.
### Returns
- **CarouselInstance | undefined**

## getContainer()
### Description
Retrieve reference to the instance's main element.
### Returns
- **HTMLElement | undefined**

## getId()
### Description
Retrieve instance ID.
### Returns
- **string | number**

## getOptions()
### Description
Retrieve reference to an instance options object.
### Returns
- **FancyboxOptions**

## getPlugins()
### Description
Retrieve an object containing instance plugin references.
### Returns
- **Partial<FancyboxPlugins>**

## getSlide()
### Description
Retrieve current carousel slide.
### Returns
- **CarouselSlide | undefined**

## getState()
### Description
Retrieve current instance state.
### Returns
- **FancyboxState**

## init(userSlides, userOptions)
### Description
Run instance initialization.
### Parameters
- **userSlides** (Partial<CarouselSlide>[]) - Optional - Initial slides.
- **userOptions** (Partial<FancyboxOptions>) - Optional - Initial options.
### Returns
- **FancyboxInstance | undefined**

## isCurrentSlide(slide)
### Description
Check if the given slide is the current slide in the carousel.
### Parameters
- **slide** (CarouselSlide) - Required - The slide to check.
### Returns
- **boolean**

## isTopMost()
### Description
Check if there is another instance on top of this one.
### Returns
- **boolean**

## localize(str, params)
### Description
Translate text with current language strings.
### Parameters
- **str** (string) - Required - The string to translate.
- **params** (Array<[string, any]>) - Optional - Parameters for translation.
### Returns
- **string**

## off(event, callback)
### Description
Unsubscribe from specific event.
### Parameters
- **event** (FancyboxEvent) - Required - The event name.
- **callback** (Function) - Required - The callback function.
### Returns
- **FancyboxInstance**

## on(event, callback)
### Description
Subscribe to specific event.
### Parameters
- **event** (FancyboxEvent) - Required - The event name.
- **callback** (Function) - Required - The callback function.
### Returns
- **FancyboxInstance**

## toggleIdle(force)
### Description
Toggle idle state.
### Parameters
- **force** (boolean) - Optional - Force a specific state.
### Returns
- **void**
```

--------------------------------

### Fancybox Configuration Options

Source: https://fancyapps.com/fancybox/api/options

A reference of available configuration options for the Fancybox instance.

```APIDOC
## Fancybox Options

### mainTpl
- **Type**: string | (() => string)
- **Default**: <dialog class="fancybox__dialog">...</dialog>
- **Description**: HTML template for Fancybox main structure.

### modal
- **Type**: boolean
- **Default**: true
- **Description**: If Fancybox should be a true modal window.

### on
- **Type**: Partial<FancyboxEvents>
- **Default**: {}
- **Description**: Event listeners.

### parentEl
- **Type**: HTMLElement | undefined | (() => HTMLElement | undefined)
- **Default**: undefined
- **Description**: Element where container is appended. If no element is specified, container is appended to the document.body.

### placeFocusBack
- **Type**: boolean
- **Default**: true
- **Description**: After closing Fancybox, set the focus back to the trigger element of the active slide.

### plugins
- **Type**: Record<string, FancyboxPlugin>
- **Default**: undefined
- **Description**: Optional user plugins.

### showClass
- **Type**: string | false | ((instance: FancyboxInstance, slide: CarouselSlide) => string | false)
- **Default**: "f-zoomInUp"
- **Description**: Class name to be applied to the content to reveal it.

### startIndex
- **Type**: number
- **Default**: 0
- **Description**: Index of active slide on the start.

### sync
- **Type**: CarouselInstance | undefined
- **Default**: undefined
- **Description**: Reference to a Carousel instance to sync with.

### theme
- **Type**: "dark" | "light" | "auto"
- **Default**: "dark"
- **Description**: Use dark, light color scheme or set based on user preference.

### triggerEl
- **Type**: HTMLElement | undefined
- **Default**: undefined
- **Description**: Element that acts as "trigger" element.

### triggerEvent
- **Type**: MouseEvent | undefined
- **Default**: undefined
- **Description**: Event that triggered the Fancybox, usually the click event on the trigger element.

### wheel
- **Type**: "slide" | "close"
- **Default**: undefined
- **Description**: Optional action to take when a wheel event is detected.

### zoomEffect
- **Type**: boolean
- **Default**: true
- **Description**: Enable zoom animation from the thumbnail to the final image when opening the Fancybox.
```

--------------------------------

### mediaQuery Option

Source: https://fancyapps.com/fancybox/plugins/compactmode

Configuration option to define the media query that triggers compact mode.

```APIDOC
### mediaQuery
- **Type**: string
- **Default**: "(max-width: 578px), (max-height: 578px)"
- **Description**: A string specifying the media query to watch.
```

--------------------------------

### Create a gallery with one preview image

Source: https://fancyapps.com/fancybox/guides/images

Display only one preview image while keeping other gallery items hidden using a container with display:none.

```html
<a href="https://lipsum.app/id/60/1600x1200" data-fancybox="gallery">
  <img
    src="https://lipsum.app/id/60/200x150"
    width="200"
    height="150"
    alt="Sample image #1"
  />
</a>
<div style="display:none">
  <a href="https://lipsum.app/id/61/1600x1200" data-fancybox="gallery">
    <img
      src="https://lipsum.app/id/61/200x150"
      width="200"
      height="150"
      alt="Sample image #2"
    />
  </a>
  <a href="https://lipsum.app/id/62/1600x1200" data-fancybox="gallery">
    <img
      src="https://lipsum.app/id/62/120x80"
      width="200"
      height="150"
      alt="Sample image #3"
    />
  </a>
</div>
```

--------------------------------

### Apply light theme and custom styles

Source: https://fancyapps.com/fancybox/guides/styling

Set the theme option to 'light' and define custom CSS variables and UI behaviors to match specific branding requirements.

```javascript
Fancybox.bind("[data-fancybox]", {
  theme: "light",
  mainStyle: {
    "--f-toolbar-padding": "0",
    "--f-button-svg-stroke-width": "1.5",
    "--f-arrow-svg-stroke-width": "1.75",
    "--f-thumb-width": "82px",
    "--f-thumb-height": "82px",
    "--f-thumb-border-radius": "8px",
    "--f-thumb-selected-shadow": "inset 0 0 0 2px #fff, 0 0 0 1.5px #ff2e00",
  },
  zoomEffect: false,
  fadeEffect: false,
  showClass: "f-fadeIn",
  hideClass: false,
  dragToClose: false,
  Carousel: {
    Toolbar: {
      absolute: false,
      display: {
        left: [""],
        middle: ["counter"],
        right: ["toggleFull", "close"],
      },
    },
    Thumbs: {
      type: "classic",
    },
  },
});
```

--------------------------------

### Launch by nodes

Source: https://fancyapps.com/fancybox/get-started/usage

Use Fancybox.fromNodes() to launch Fancybox from a collection of HTML elements.

```js
Fancybox.fromNodes(Array.from(document.querySelectorAll("[data-fancybox]")), {
  // Your custom options
});
```

--------------------------------

### Default mediaQuery option

Source: https://fancyapps.com/fancybox/plugins/compactmode

The default media query string used to determine when to enable compact mode.

```text
"(max-width: 578px), (max-height: 578px)"
```

--------------------------------

### Initialize Compact Mode

Source: https://fancyapps.com/fancybox/plugins/compactmode

Pass the Compactmode plugin to the Fancybox constructor using the plugins option.

```javascript
Fancybox.bind("[data-fancybox]", {
  plugins: { Compactmode },
});
```

--------------------------------

### Playing MP3 files

Source: https://fancyapps.com/fancybox/guides/videos

Use data-type="html5video" to play audio files and apply custom CSS for styling.

```css
.has-mp3 .f-html,
.has-mp3 video {
  background: transparent;
}
```

```html
<button
  data-src="https://samplelib.com/lib/preview/mp3/sample-3s.mp3"
  data-fancybox
  data-width="400"
  data-height="50"
  data-type="html5video"
  data-html5video-format="audio/mpeg"
  data-class="has-mp3"
>
  Play MP3 file
</button>
```

--------------------------------

### getDefaults

Source: https://fancyapps.com/fancybox/api/methods

Retrieves the default options.

```APIDOC
## getDefaults()

### Description
Retrieve reference to the object containing the Fancybox default options.

### Returns
- **FancyboxOptions**
```

--------------------------------

### Programmatic video with options

Source: https://fancyapps.com/fancybox/guides/videos

Pass options to the Video plugin when using Fancybox.show.

```js
Fancybox.show(
  [
    {
      src: "https://www.youtube.com/watch?v=z2X2HaTvkl8",
      width: 640,
      height: 360,
    },
  ],
  {
    Carousel: {
      Video: {
        autoplay: false,
      },
    },
  }
);
```

--------------------------------

### Fancybox.Plugins.Hash.getInfoFromURL()

Source: https://fancyapps.com/fancybox/plugins/hash

Retrieves information about the current URL hash to determine if a gallery should be opened programmatically.

```APIDOC
## Fancybox.Plugins.Hash.getInfoFromURL()

### Description
Parses the current browser URL to extract hash-related information, such as the gallery slug and the index of the item to display.

### Returns
- **urlHash** (string) - The current hash value from the URL.
- **urlSlug** (string) - The slug associated with the gallery.
- **urlIndex** (number) - The index of the gallery item derived from the URL.
```

--------------------------------

### Configure dynamic toolbar with breakpoints

Source: https://fancyapps.com/fancybox/guides/toolbar

Use the breakpoints option to adjust the toolbar display based on the screen size.

```javascript
Fancybox.bind("[data-fancybox]", {
  Carousel: {
    Toolbar: {
      display: {
        left: ["counter"],
        middle: [],
        right: ["thumbs", "close"],
      },
    },
    breakpoints: {
      "(min-width: 768px)": {
        Toolbar: {
          display: {
            left: ["counter"],
            middle: [
              "zoomIn",
              "zoomOut",
              "toggle1to1",
              "rotateCCW",
              "rotateCW",
              "flipX",
              "flipY",
            ],
            right: ["autoplay", "thumbs", "close"],
          },
        },
      },
    },
  },
});
```

--------------------------------

### Importing Sidebar Plugin

Source: https://fancyapps.com/fancybox/plugins/sidebar

Include the necessary JavaScript and CSS files for the Sidebar plugin.

```js
import { Sidebar } from "@fancyapps/ui/dist/fancybox/fancybox.sidebar.js";
import "@fancyapps/ui/dist/fancybox/fancybox.sidebar.css";
```

--------------------------------

### bind

Source: https://fancyapps.com/fancybox/api/methods

Adds a click handler that launches Fancybox based on selectors and optional containers.

```APIDOC
## bind(itemSelector?: string, userOptions?: Partial<FancyboxOptions>)
## bind(container: HTMLElement | null, itemSelector: string, userOptions?: Partial<FancyboxOptions>)
## bind(groupSelector: string, itemSelector: string, userOptions?: Partial<FancyboxOptions>)
## bind(container: HTMLElement | null, groupSelector: string, itemSelector: string, userOptions?: Partial<FancyboxOptions>)

### Description
Adds a click handler that launches Fancybox after clicking on items that match the provided selector, optionally scoped to a container or group.

### Returns
- **void**
```

--------------------------------

### Programmatic Auto-sizing Configuration

Source: https://fancyapps.com/fancybox/guides/iframes

Passing custom options to the HTML plugin programmatically to enable auto-resizing.

```js
Fancybox.show(
  [
    {
      src: "/iframe.html",
      type: "iframe",
    },
  ],
  {
    Carousel: {
      Html: {
        autosize: true,
      },
    },
  },
);
```

--------------------------------

### Hash Plugin Configuration

Source: https://fancyapps.com/fancybox/plugins/hash

Configuration options for the Hash plugin when initializing Fancybox.

```APIDOC
## Hash Plugin Options

### slug
- **Type**: `string`
- **Default**: `undefined`
- **Description**: Custom URL hash value for the entire gallery instance.
```

--------------------------------

### getInstance

Source: https://fancyapps.com/fancybox/api/methods

Retrieves a specific Fancybox instance.

```APIDOC
## getInstance(id?: number | string)

### Description
Retrieve instance by identifier or the top most instance, if identifier is not provided.

### Returns
- **FancyboxInstance | undefined**
```

--------------------------------

### Create multiple galleries using group and item selectors

Source: https://fancyapps.com/fancybox/guides/grouping

Define galleries based on specific container elements and their children using groupAll.

```html
<p class="gallery">
  <a
    href="https://lipsum.app/id/1/1600x1200"
    data-caption="Optional caption,&lt;br /&gt;that can contain &lt;em&gt;HTML&lt;/em&gt; code"
  >
    <img
      src="https://lipsum.app/id/1/200x150"
      width="200"
      height="150"
      alt="Sample image #1"
    />
  </a>
  <a href="https://lipsum.app/id/2/1600x1200">
    <img
      src="https://lipsum.app/id/2/200x150"
      width="200"
      height="150"
      alt="Sample image #2"
    />
  </a>
</p>
<p class="gallery">
  <a href="https://lipsum.app/id/3/1600x1200">
    <img
      src="https://lipsum.app/id/3/200x150"
      width="200"
      height="150"
      alt="Sample image #3"
    />
  </a>
  <a href="https://lipsum.app/id/4/1600x1200">
    <img
      src="https://lipsum.app/id/4/200x150"
      width="200"
      height="150"
      alt="Sample image #4"
    />
  </a>
</p>
```

```javascript
Fancybox.bind(".gallery", "a", {
  groupAll: true,
});
```

--------------------------------

### Displaying a single video programmatically

Source: https://fancyapps.com/fancybox/guides/videos

Use Fancybox.show to display a single video programmatically.

```js
Fancybox.show([
  {
    src: "https://www.youtube.com/watch?v=z2X2HaTvkl8",
    width: 640,
    height: 360,
  },
]);
```

--------------------------------

### Create a gallery with data-fancybox

Source: https://fancyapps.com/fancybox/guides/images

Create a gallery by assigning the same data-fancybox attribute value to multiple anchor elements.

```html
<a
  href="https://lipsum.app/id/1/1600x1200"
  data-fancybox="gallery"
  data-caption="Optional caption,&lt;br /&gt;that can contain &lt;em&gt;HTML&lt;/em&gt; code"
>
  <img
    src="https://lipsum.app/id/1/200x150"
    width="200"
    height="150"
    alt="Sample image #1"
  />
</a>
<a href="https://lipsum.app/id/2/1600x1200" data-fancybox="gallery">
  <img
    src="https://lipsum.app/id/2/200x150"
    width="200"
    height="150"
    alt="Sample image #2"
  />
</a>
<a href="https://lipsum.app/id/3/1600x1200" data-fancybox="gallery">
  <img
    src="https://lipsum.app/id/3/200x150"
    width="200"
    height="150"
    alt="Sample image #3"
  />
</a>
```

--------------------------------

### Instance Methods

Source: https://fancyapps.com/fancybox/api/methods

Instance methods are used to control a specific Fancybox instance after obtaining a reference.

```APIDOC
## Instance Methods

### Description
Methods called on a specific Fancybox instance reference.

### Usage
1. Obtain instance: `const fancyboxRef = Fancybox.getInstance();`
2. Call method: `fancyboxRef.close();`
```

--------------------------------

### Group all elements with groupAll

Source: https://fancyapps.com/fancybox/guides/grouping

Create a gallery from all matching elements regardless of attributes by using the groupAll option.

```html
<div id="gallery">
  <a href="image-a1.jpeg" data-caption="Image #1">
    <img src="thumbnail-a1.jpeg" alt="Image 1" />
  </a>

  <a href="image-a2.jpeg" data-caption="Image #2">
    <img src="thumbnail-a2.jpeg" alt="Image 2" />
  </a>
</div>
```

```javascript
Fancybox.bind("#gallery a", {
  groupAll: true,
});
```

--------------------------------

### Configuring Sidebar Options

Source: https://fancyapps.com/fancybox/plugins/sidebar

Pass custom options to the Sidebar plugin using its name as the key.

```js
Fancybox.bind("[data-fancybox]", {
  plugins: { Sidebar },
  Sidebar: {
    showOnStart: false,
  },
});
```

--------------------------------

### Implementing Programmatic Hash Navigation

Source: https://fancyapps.com/fancybox/plugins/hash

Use the slug option to set a custom hash for programmatically opened galleries and monitor hash changes to sync state with the browser URL.

```js
const galleryItems = [
  {
    src: "https://lipsum.app/id/32/1600x1200",
    thumb: "https://lipsum.app/id/32/200x150",
  },
  {
    src: "https://lipsum.app/id/22/1600x1200",
    thumb: "https://lipsum.app/id/22/200x150",
  },
  {
    src: "https://lipsum.app/id/23/1600x1200",
    thumb: "https://lipsum.app/id/23/200x150",
  },
];

const galleryOptions = {
  startIndex: 0,
  Hash: {
    slug: "gallery",
  },
};

document
  .getElementById("trigger-fancybox")
  ?.addEventListener("click", function () {
    Fancybox.show(galleryItems, galleryOptions);
  });

function startFancyboxFromUrl() {
  const HashPlugin = Fancybox.Plugins.Hash;

  if (HashPlugin && !Fancybox.getInstance()) {
    const { urlHash, urlSlug, urlIndex } = HashPlugin.getInfoFromURL();

    if (urlHash && urlSlug === galleryOptions.Hash.slug) {
      Fancybox.show(galleryItems, {
        ...galleryOptions,
        startIndex: urlIndex - 1,
      });
    }
  }
}

window.addEventListener("hashchange", startFancyboxFromUrl, false);

startFancyboxFromUrl();
```

--------------------------------

### Customizing Video plugin options

Source: https://fancyapps.com/fancybox/guides/videos

Pass options to the Video plugin to configure behavior like autoplay.

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

--------------------------------

### Configure mainTpl HTML template

Source: https://fancyapps.com/fancybox/api/options

Defines the HTML structure for the Fancybox main container.

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

--------------------------------

### Call instance methods

Source: https://fancyapps.com/fancybox/api/methods

Once an instance reference is obtained, you can call instance-specific methods such as close().

```javascript
fancyboxRef.close();
```

--------------------------------

### Sidebar Configuration Options

Source: https://fancyapps.com/fancybox/plugins/sidebar

Configuration options for the Sidebar plugin, including default caption handling, initial visibility, and layout templates.

```APIDOC
### Options

- **defaultCaption** (string | (instance: FancyboxInstance) => string) - Default content to display in the sidebar if the active slide has no caption. Default: "<em>{{NO_CAPTION}}</em>"
- **mainTpl** (string) - HTML template for Fancybox main structure.
- **showOnStart** (boolean) - If the sidebar should be visible after launching Fancybox. Default: true
```

--------------------------------

### Programmatic thumbnail configuration

Source: https://fancyapps.com/fancybox/guides/thumbnails

Define thumbnail properties directly within the Fancybox.show method using thumbSrc, thumbAlt, and thumbClass keys.

```js
Fancybox.show(
  [
    {
      src: "https://lipsum.app/id/1/1800x1200",
      caption: "Sample image #1",
      thumbSrc: "https://lipsum.app/id/1/150x100",
      thumbAlt: "My custom description #1",
      thumbClass: "my_custom_thumb_class",
    },
    {
      src: "https://lipsum.app/id/2/1800x1200",
      caption: "Sample image #2",
      thumbSrc: "https://lipsum.app/id/2/150x100",
      thumbAlt: "My custom description #2",
      thumbClass: "my_custom_thumb_class2",
    },
    {
      src: "https://lipsum.app/id/3/1800x1200",
      caption: "Sample image #3",
      thumbSrc: "https://lipsum.app/id/3/150x100",
      thumbAlt: "My custom description #3",
      thumbClass: "my_custom_thumb_class3",
    },
  ],
  {
    // Your custom options
  },
);
```

--------------------------------

### Bind click event handler

Source: https://fancyapps.com/fancybox/get-started/usage

Use Fancybox.bind() to initialize Fancybox on elements matching the provided selector.

```js
Fancybox.bind("[data-fancybox]", {
  // Your custom options
});
```

--------------------------------

### Declarative Map Implementation

Source: https://fancyapps.com/fancybox/guides/google-maps

Basic usage of the plugin by adding the data-fancybox attribute to an anchor tag.

```html
<a
  href="https://www.google.com/maps/search/?api=1&query=Westminster+Bridge%2C+London&query_place_id=ChIJoaH8k8YEdkgRnmDd5iuUl9Y"
  data-fancybox
>
  Show map
</a>
```

--------------------------------

### Set initial image size

Source: https://fancyapps.com/fancybox/guides/images

Configure the initial zoom level to cover the screen while disabling zoom effects and carousel dragging.

```javascript
Fancybox.bind("[data-fancybox]", {
  zoomEffect: false,
  Carousel: {
    gestures: false,
    Zoomable: {
      Panzoom: {
        startPos: {
          scale: "cover",
        },
      },
    },
  },
});
```

--------------------------------

### Create a gallery of elements

Source: https://fancyapps.com/fancybox/get-started/usage

Assign the same data-fancybox value to multiple elements to group them into a gallery.

```html
<a href="image-a.jpeg" data-fancybox="gallery" data-caption="Caption #1">
  <img src="thumbnail-a.jpeg" alt="Gallery image 1" />
</a>

<a href="image-b.jpeg" data-fancybox="gallery" data-caption="Caption #2">
  <img src="thumbnail-b.jpeg" alt="Gallery image 2" />
</a>
```

--------------------------------

### Customizing video dimensions with CSS

Source: https://fancyapps.com/fancybox/guides/videos

Control video dimensions using CSS classes.

```css
.has-html5video .f-html,
.has-youtube .f-html,
.has-vimeo .f-html {
  max-width: 640px;
  max-height: 360px;
}
```

--------------------------------

### Listen to Fancybox close event

Source: https://fancyapps.com/fancybox/api/events

Demonstrates how to hook into the close event using the on option during Fancybox binding.

```javascript
Fancybox.bind("[data-fancybox]", {
  on: {
    close: () => {
      console.log("Fancybox is closing!");
    },
  },
});
```

--------------------------------

### Static Methods

Source: https://fancyapps.com/fancybox/api/methods

Static methods can be invoked globally to control all Fancybox instances or access the carousel.

```APIDOC
## Static Methods

### Description
Global methods that can be called from anywhere in the code.

### Methods
- `Fancybox.close()`: Closes all active Fancybox instances.
- `Fancybox.getCarousel()`: Retrieves the current carousel instance.
- `Fancybox.getInstance()`: Retrieves a reference to the current Fancybox instance.
```

--------------------------------

### Static methods for global control

Source: https://fancyapps.com/fancybox/api/methods

Static methods can be called from anywhere to perform actions like closing all instances or executing plugin commands.

```javascript
// Close all instances
Fancybox.close();

// Zoom in on the image on the current slide
Fancybox.getCarousel()?.getPlugins()?.Zoomable?.execute("zoomIn");
```

--------------------------------

### Configure transformation controls

Source: https://fancyapps.com/fancybox/guides/toolbar

Use the Panzoom component's transformation buttons within the toolbar display configuration.

```javascript
Fancybox.bind("[data-fancybox]", {
  Carousel: {
    Toolbar: {
      display: {
        left: ["counter"],
        middle: [
          "zoomIn",
          "zoomOut",
          "toggle1to1",
          "rotateCCW",
          "rotateCW",
          "flipX",
          "flipY",
          "reset",
        ],
        right: ["autoplay", "thumbs", "close"],
      },
    },
  },
});
```

--------------------------------

### Programmatic Fancybox.show usage

Source: https://fancyapps.com/fancybox/api/options

Pass an array of gallery items and a custom options object to the Fancybox.show method.

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

--------------------------------

### Bind custom options to multiple galleries

Source: https://fancyapps.com/fancybox/guides/grouping

Apply specific configuration options to individual galleries identified by their data-fancybox attribute.

```javascript
Fancybox.bind('[data-fancybox="gallery-a"]', {
  // Custom options for the first gallery
});

Fancybox.bind('[data-fancybox="gallery-b"]', {
  // Custom options for the second gallery
});
```

--------------------------------

### Load German translations with UMD build

Source: https://fancyapps.com/fancybox/guides/localization

Include the translation script via CDN and reference the loaded object in the l10n option.

```html
<script src="https://cdn.jsdelivr.net/npm/@fancyapps/ui@6.1/dist/fancybox/l10n/de_DE.umd.js"></script>
```

```javascript
Fancybox.bind("[data-fancybox]", {
  l10n: Fancybox.l10n.de_DE,
});
```

--------------------------------

### destroy

Source: https://fancyapps.com/fancybox/api/methods

Immediately destroys all instances and cleans up resources.

```APIDOC
## destroy()

### Description
Immediately destroy all instances (without closing animation) and clean up.

### Returns
- **void**
```

--------------------------------

### Create custom toolbar buttons

Source: https://fancyapps.com/fancybox/guides/toolbar

Define custom toolbar items using the items option, providing a tpl for the HTML template and a click method for execution.

```javascript
Fancybox.bind("[data-fancybox]", {
  Carousel: {
    Toolbar: {
      items: {
        facebook: {
          tpl: '<button class="f-button"><svg><path d="M18 2h-3a5 5 0 0 0-5 5v3H7v4h3v8h4v-8h3l1-4h-4V7a1 1 0 0 1 1-1h3z"/></svg></button>',
          click: () => {
            window.open(
              "https://www.facebook.com/sharer/sharer.php?u=" +
                encodeURIComponent(window.location.href) +
                "&t=" +
                encodeURIComponent(document.title),
              "",
              "left=0,top=0,width=600,height=300,menubar=no,toolbar=no,resizable=yes,scrollbars=yes",
            );
          },
        },
        twitter: {
          tpl: '<button class="f-button"><svg><path stroke="none" d="M0 0h24v24H0z"/><path d="M22 4.01c-1 .49-1.98.689-3 .99-1.121-1.265-2.783-1.335-4.38-.737S11.977 6.323 12 8v1c-3.245.083-6.135-1.395-8-4 0 0-4.182 7.433 4 11-1.872 1.247-3.739 2.088-6 2 3.308 1.803 6.913 2.423 10.034 1.517 3.58-1.04 6.522-3.723 7.651-7.742a13.84 13.84 0 0 0 .497-3.753c0-.249 1.51-2.772 1.818-4.013z"/></svg></button>',
          click: () => {
            window.open(
              "http://twitter.com/share?url=" +
                encodeURIComponent(window.location.href) +
                "&text=" +
                encodeURIComponent(document.title),
              "",
              "left=0,top=0,width=600,height=300,menubar=no,toolbar=no,resizable=yes,scrollbars=yes",
            );
          },
        },
      },
      display: {
        left: ["infobar"],
        middle: [],
        right: ["twitter", "facebook", "close"],
      },
    },
  },
});
```

--------------------------------

### Default Caption Template

Source: https://fancyapps.com/fancybox/plugins/sidebar

The default string used when no caption is provided.

```text
"<em>{{NO_CAPTION}}</em>"
```

--------------------------------

### Customizing thumbnails with data attributes

Source: https://fancyapps.com/fancybox/guides/thumbnails

Use data attributes like data-thumb-src, data-thumb-alt, and data-thumb-class to customize the thumbnail source, description, and CSS class.

```html
<a
  href="https://lipsum.app/id/1/1600x1200"
  data-fancybox="gallery"
  data-thumb-src="https://lipsum.app/id/1/150x100"
  data-thumb-alt="My custom description #1"
  data-thumb-class="my_custom_thumb_class"
>
  <img
    src="https://lipsum.app/id/1/200x150"
    width="200"
    height="150"
    alt="Sample image #1"
  />
</a>
```

--------------------------------

### Fancybox.getDefaults()

Source: https://fancyapps.com/fancybox/api/options

Accesses and modifies the global default options for all Fancybox instances.

```APIDOC
## Fancybox.getDefaults()

### Description
Returns the global default options object, allowing for modification of settings that apply to all instances.
```

--------------------------------

### Resize thumbnail viewport with CSS

Source: https://fancyapps.com/fancybox/guides/thumbnails

Use CSS to adjust the dimensions and padding of the thumbnail container.

```css
.fancybox__thumbs {
  --f-arrow-pos: 10px;
  --f-thumbs-padding-x: 80px;

  width: 460px;
  max-width: 100%;
  align-self: center;
}

.fancybox__thumbs .f-thumbs__viewport {
  overflow: hidden;
}
```

--------------------------------

### Keyboard option default configuration

Source: https://fancyapps.com/fancybox/api/options

The default mapping of keyboard keys to Fancybox actions.

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

--------------------------------

### Enable image protection with Panzoom

Source: https://fancyapps.com/fancybox/guides/images

Use the protected option within the Panzoom configuration to prevent right-click image downloads.

```javascript
Fancybox.bind("[data-fancybox]", {
  Carousel: {
    Zoomable: {
      Panzoom: {
        protected: true,
      },
    },
  },
});
```

--------------------------------

### Configure vertical classic thumbnails

Source: https://fancyapps.com/fancybox/guides/thumbnails

Set vertical to true and define a center function to align thumbnails to the top when they fit the available area.

```javascript
Fancybox.bind("[data-fancybox]", {
  Carousel: {
    Thumbs: {
      type: "classic",
      Carousel: {
        vertical: true,
        center: (ref) => {
          return ref.getTotalSlideDim() > ref.getViewportDim();
        },
      },
    },
  },
});
```

--------------------------------

### Main Structure Template

Source: https://fancyapps.com/fancybox/plugins/sidebar

The default HTML structure for the Fancybox main container.

```html
<dialog class="fancybox__dialog">
  <div class="fancybox__container" tabindex="0" aria-label="{{MODAL}}">
    <div class="fancybox__backdrop"></div>
    <div class="fancybox__carousel">
      <div class="fancybox__grid">
        <div class="fancybox__column with-viewport">
          <div class="fancybox__viewport"></div>
        </div>
        <div class="fancybox__column with-sidebar">
          <div class="fancybox__sidebar"></div>
        </div>
      </div>
    </div>
  </div>
</dialog>
```

--------------------------------

### Iframe Map Implementation

Source: https://fancyapps.com/fancybox/guides/google-maps

Using a direct link to an embedded iframe with custom dimensions.

```html
<a
  href="https://www.google.com/maps/embed?pb=!1m14!1m12!1m3!1d10500.902039411158!2d2.2913514905137315!3d48.85391001859112!2m3!1f0!2f0!3f0!3m2!1i1024!2i768!4f13.1!5e0!3m2!1slv!2slv!4v1622011463926!5m2!1slv!2slv"
  data-fancybox
  data-type="iframe"
  data-width="640"
  data-height="480"
>
  Show map
</a>
```

--------------------------------

### Listen to all events with wildcard

Source: https://fancyapps.com/fancybox/api/events

Uses the * wildcard to listen to every event emitted by Fancybox, including those from the Carousel and its plugins.

```javascript
Fancybox.bind("[data-fancybox]", {
  on: {
    "*": (fancyboxRef, eventName) => {
      console.log(`Fancybox eventName: ${eventName}`);
    },
  },
});
```
Tokens:
Raw