Fancyapps
Return to top
On this page

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