Fancyapps

Options ​

Panzoom 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 maxScale depending on the screen size.

All friction values are inside [0, 1) interval, where 0 would change instantly, but 0.99 would update extremely slowly.

Constructor Options ​

You can pass a set of options as a parameter into a Panzoom constructor:

js
const container = document.getElementById("myPanzoom");
const options = { click: "toggleCover" };

new Panzoom(container, options);

Global Options ​

If you have multiple instances, you might want to set options that are common to all of them. Use Panzoom.defaults static property to change default options:

js
Panzoom.defaults.extraZoomFactor = 2;

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

js
Panzoom.defaults = {
  ...Panzoom.defaults,
  extraZoomFactor: 2,
  click: "toggleCover",
};

Available Options ​

bounce ​

Bounce after hitting the edge

Type

boolean

Default

true

bounds ​

Content x/y boundaries

Type

"auto" | ((...any: any) => Bounds)

Default

"auto"

Note

js
type Bounds = {
  x: {
    min: number,
    max: number,
  },
  y: {
    min: number,
    max: number,
  },
};

classes ​

Class names for DOM elements

Type

classesType

Default

js
{
    content: "f-panzoom__content",
    isLoading: "is-loading",
    canZoomIn: "can-zoom_in",
    canZoomOut: "can-zoom_out",
    isDraggable: "is-draggable",
    isDragging: "is-dragging",
    inFullscreen: "in-fullscreen",
    htmlHasFullscreen: "with-panzoom-in-fullscreen",
}

click ​

Add click event listener

Type

ClickAction | ((...any: any) => ClickAction)

Default

"toggleZoom"

Note

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

content ​

Specify the content element. If no content is specified, it will be assumed that the content is the first child element

Type

Element | null | ((...any: any) => Element | null)

Default

null

dblClick ​

Add double click event listener

Type

ClickAction | ((...any: any) => ClickAction)

Default

false

Note

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

decelFriction ​

Friction while decelerating after drag end

Type

number

Default

0.05

dragFriction ​

Friction while panning/dragging

Type

number

Default

0.35

dragMinThreshold ​

Minimum touch drag distance to start panning content;
it can help detect click events on touch devices

Type

number

Default

3

friction ​

Default friction for animations, the value must be in the interval [0, 1)

Type

number

Default

0.25

height ​

Content height

Type

"auto" | number | ((...any: any) => "auto" | number)

Default

"auto"

infinite ​

Force to ignore boundaries boundar; always or only when the drag is locked on the axis

Type

boolean | "x" | "y"

Default

false

l10n ​

Localization of strings

Type

Record<string, string>

Default

en

lockAxis ​

Lock axis while dragging

Type

"x" | "y" | "xy" | false

Default

false

maxScale ​

The maximum zoom level the user can zoom.
If, for example, it is 2, then the user can zoom content to 2x the original size

Type

number | ((...any: any) => number)

Default

2

maxVelocity ​

Limit the animation's maximum acceleration

Type

number | ((...any: any) => number)

Default

75

minScale ​

Minimum scale level

Type

number | ((...any: any) => number)

Default

1

mouseMoveFactor ​

The proportion by which the content pans relative to the cursor position;
for example, 2 means the cursor only needs to move 80% of the width/height of the content to reach the container border

Type

number

Default

1

mouseMoveFriction ​

Animation friction when content is moved depending on cursor position

Type

number

Default

0.12

on ​

Optional event listeners

Type

Partial<Events>

Default

{}

panMode ​

Use touch events to pan content or follow the cursor.
Automatically switches to drag if user’s primary input mechanism can not hover over elements. Tip: experiment with mouseMoveFactor option for better ux.

Type

"drag" | "mousemove"

Default

"drag"

panOnlyZoomed ​

Allow panning only when content is zoomed in.
Using true allows other components (e.g. Carousel) to pick up touch events. Note: if set to "auto", disables for touch devices (to allow page scrolling).

Type

boolean | "auto" | ((...any: any) => boolean | "auto")

Default

"auto"

pinchToZoom ​

Enable pinch-to-zoom guesture to zoom in/out using two fingers

Type

boolean | ((...any: any) => boolean)

Default

true

rubberband ​

If enable rubberband effect - drag out of bounds with resistance

Type

boolean

Default

true

spinner ​

Show loading icon

Type

boolean

Default

true

touch ​

Enable touch guestures

Type

boolean | ((...any: any) => boolean)

Default

true

transformParent ​

If a CSS transformation is to be applied to the parent element of the content

Type

boolean

Default

false

wheel ​

Add mouse wheel event listener

Type

WheelAction | ((...any: any) => WheelAction)

Default

"zoom"

Note

type WheelAction = "zoom" | "pan" | false;

wheelLimit ​

Number of times to stop restricting wheel operation after min/max zoom level is reached

Type

number

Default

7

width ​

Content width

Type

"auto" | number | ((...any: any) => "auto" | number)

Default

"auto"

zoom ​

Globally enable (or disable) any zooming

Type

boolean | ((...any: any) => boolean)

Default

true