Skip to main content
Version: 4.10.8

Flicking

class Flicking extends Component

constructor

new Flicking(root, options)
PARAMETERTYPEOPTIONALDEFAULTDESCRIPTION
rootHTMLElement | stringA root HTMLElement to initialize Flicking on it. When it's a typeof string, it should be a css selector string
optionsobject✔️{}An options object for Flicking.

Throws: FlickingError

|code|condition|
|---|---|
|WRONG_TYPE|When the root is not either string or HTMLElement|
|ELEMENT_NOT_FOUND|When the element with given CSS selector does not exist|

import Flicking from "@egjs/flicking";

// Creating new instance of Flicking with HTMLElement
const flicking = new Flicking(document.querySelector(".flicking-viewport"), { circular: true });

// Creating new instance of Flicking with CSS selector
const flicking2 = new Flicking(".flicking-viewport", { circular: true });

Properties

VERSION

staticreadonly

Version info string

Type: string

Flicking.VERSION;  // ex) 4.0.0

control

readonly

Control instance of the Flicking

Type: Control

Default: SnapControl

See:

camera

readonly

Camera instance of the Flicking

Type: Camera

Default: LinearCamera

See:

  • Camera
  • LinearCamera
  • BoundCamera
  • CircularCamera

renderer

readonly

Renderer instance of the Flicking

Type: Renderer

Default: VanillaRenderer

See:

viewport

readonly

A component that manages viewport size

Type: Viewport

See:

initialized

readonly

Whether Flicking's init() is called.
This is true when init() is called, and is false after calling destroy().

Type: boolean

Default: false

circularEnabled

readonly

Whether the circular option is enabled.
The circular option can't be enabled when sum of the panel sizes are too small.

Type: boolean

Default: false

virtualEnabled

readonly

Whether the virtual option is enabled.
The virtual option can't be enabled when panelsPerView is less or equal than zero.

Type: boolean

Default: false

index

readonly

Index number of the currentPanel

Type: number

Default: 0

element

readonly

The root(.flicking-viewport) element

Type: HTMLElement

currentPanel

readonly

Currently active panel

Type: Panel

See:

panels

readonly

Array of panels

Type: Array<Panel>

See:

panelCount

readonly

Count of panels

Type: number

visiblePanels

readonly

Array of panels that is visible at the current position

Type: Array<Panel>

See:

animating

readonly

Whether Flicking's animating

Type: boolean

holding

readonly

Whether user is clicking or touching

Type: boolean

activePlugins

readonly

A current list of activated plugins

Type: Array<Plugin>

align

Align position of the panels within viewport. You can set different values each for the panel and camera

Type: ALIGN | string | number | Object

Default: "center"

PROPERTYTYPEDESCRIPTION
panelALIGN | string | numberThe align value for each Panels
cameraALIGN | string | numberThe align value for Camera

See:

const possibleOptions = [
// Literal strings
"prev", "center", "next",
// % values, applied to both panel & camera
"0%", "25%", "42%",
// px values, arithmetic calculation with (+/-) is also allowed.
"0px", "100px", "50% - 25px",
// numbers, same to number + px ("0px", "100px")
0, 100, 1000,
// Setting a different value for panel & camera
{ panel: "10%", camera: "25%" }
];

possibleOptions.forEach(align => {
new Flicking("#el", { align });
});

defaultIndex

Index of the panel to move when Flicking's init() is called. A zero-based integer

Type: number

Default: 0

See:

horizontal

Direction of panel movement (true: horizontal, false: vertical)

Type: boolean

Default: true

See:

circular

Enables circular(continuous loop) mode, which connects first/last panel for continuous scrolling.

Type: boolean

Default: false

See:

circularFallback

Set panel control mode for the case when circular cannot be enabled.
"linear" will set the view's range from the top of the first panel to the top of the last panel.
"bound" will prevent the view from going out of the first/last panel, so it won't show empty spaces before/after the first/last panel.

Type: string

Default: "linear"

See:

bound

Prevent the view(camera element) from going out of the first/last panel, so it won't show empty spaces before/after the first/last panel
Only can be enabled when circular=false

Type: boolean

Default: false

See:

adaptive

Update height of the viewport element after movement same to the height of the panel below. This can be only enabled when horizontal=true

Type: boolean

Default: false

See:

panelsPerView

A visible number of panels on viewport. Enabling this option will automatically resize panel size

Type: number

Default: -1

See:

noPanelStyleOverride

Enabling this option will not change width/height style of the panels if Flicking#panelsPerView is enabled.
This behavior can be useful in terms of performance when you're manually managing all panel sizes

Type: boolean

Default: false

resizeOnContentsReady

Enabling this option will automatically call Flicking#resize when all image/video inside panels are loaded.
This can be useful when you have contents inside Flicking that changes its size when it's loaded

Type: boolean

Default: false

See:

nested

If you enable this option on child Flicking when the Flicking is placed inside the Flicking, the parent Flicking will move in the same direction after the child Flicking reaches the first/last panel.
If the parent Flicking and child Flicking have different horizontal option, you do not need to set this option.

Type: boolean

Default: false

See:

needPanelThreshold

A Threshold from viewport edge before triggering needPanel event

Type: number

Default: 0

See:

preventEventsBeforeInit

When enabled, events are not triggered before ready when initializing

Type: boolean

Default: true

See:

deceleration

Deceleration value for panel movement animation which is triggered by user input. A higher value means a shorter animation time

Type: number

Default: 0.0075

See:

easing

An easing function applied to the panel movement animation. Default value is easeOutCubic

Type: function

Default: x => 1 - Math.pow(1 - x, 3)

See:

duration

Default duration of the animation (ms)

Type: number

Default: 500

See:

inputType

Types of input devices to enable

Type: Array<string>

Default: ["touch", "mouse"]

See:

moveType

Movement style by user input. This will change instance type of Flicking#control
You can use the values of the constant MOVE_TYPE

Type: MOVE_TYPE | Pair.<string, object>

Default: "snap"

See:

import Flicking, { MOVE_TYPE } from "@egjs/flicking";

const flicking = new Flicking({
moveType: MOVE_TYPE.SNAP
});
const flicking = new Flicking({
// If you want more specific settings for the moveType
// [moveType, options for that moveType]
// In this case, it's ["freeScroll", FreeControlOptions]
moveType: [MOVE_TYPE.FREE_SCROLL, { stopAtEdge: true }]
});

threshold

Movement threshold to change panel (unit: px). It should be dragged above the threshold to change the current panel.

Type: number

Default: 40

See:

interruptable

Set animation to be interruptable by click/touch.

Type: boolean

Default: true

See:

bounce

The size value of the bounce area. Only can be enabled when circular=false.
You can set different bounce value for prev/next direction by using array.
number for px value, and string for px, and % value relative to viewport size.
You have to call Control#updateInput after changing this to take effect.

Type: string | number | Array<(string|number)>

Default: "20%"

See:

const possibleOptions = [
// % values, relative to viewport element(".flicking-viewport")'s size
"0%", "25%", "42%",
// px values, arithmetic calculation with (+/-) is also allowed.
"0px", "100px", "50% - 25px",
// numbers, same to number + px ("0px", "100px")
0, 100, 1000
];
const flicking = new Flicking("#el", { bounce: "20%" });

flicking.bounce = "100%";
flicking.control.updateInput(); // Call this to update!

iOSEdgeSwipeThreshold

Size of the area from the right edge in iOS safari (in px) which enables swipe-back or swipe-forward

Type: number

Default: 30

See:

preventClickOnDrag

Automatically prevent click event if the user has dragged at least a single pixel on the viewport element

Type: boolean

Default: true

See:

disableOnInit

Automatically call disableInput() on initialization

Type: boolean

Default: false

See:

changeOnHold

Change active panel index on mouse/touch hold while animating.
index of the willChange/willRestore event will be used as new index.

Type: boolean

Default: false

See:

renderOnlyVisible

Whether to render visible panels only. This can dramatically increase performance when there're many panels

Type: boolean

Default: false

See:

virtual

By enabling this option, it will reduce memory consumption by restricting the number of DOM elements to panelsPerView + 1
Must be used with panelsPerview.
After Flicking's initialized, this property can be used to add/remove the panel count.

Type: VirtualManager

PROPERTYTYPEDEFAULTDESCRIPTION
renderPanelfunctionA rendering function for the panel element's innerHTML
initialPanelCountnumberInitial panel count to render
cachebooleanfalseWhether to cache rendered panel's innerHTML
panelClassstring"flicking-panel"The class name that will be applied to rendered panel elements

See:

import Flicking, { VirtualPanel } from "@egjs/flicking";

const flicking = new Flicking("#some_el", {
panelsPerView: 3,
virtual: {
renderPanel: (panel: VirtualPanel, index: number) => `Panel ${index}`,
initialPanelCount: 100
}
});

// Add 100 virtual panels (at the end)
flicking.virtual.append(100);

// Remove 100 virtual panels from 0 to 100
flicking.virtual.remove(0, 100);

autoInit

readonly

Call init() automatically when creating Flicking's instance

Type: boolean

Default: true

See:

autoResize

Whether to automatically call resize() when the viewport element(.flicking-viewport)'s size is changed

Type: boolean

Default: true

useResizeObserver

Whether to listen ResizeObserver's event instead of Window's resize event when using the autoResize option

Type: boolean

Default: true

See:

resizeDebounce

Delays size recalculation from autoResize by the given time in milisecond.
If the size is changed again while being delayed, it cancels the previous one and delays from the beginning again.
This can increase performance by preventing resize being called too often.

Type: number

Default: 0

See:

maxResizeDebounce

The maximum time for size recalculation delay when using resizeDebounce, in milisecond.
This guarantees that size recalculation is performed at least once every (n)ms.

Type: number

Default: 100

See:

useFractionalSize

By enabling this, Flicking will calculate all internal size with CSS width computed with getComputedStyle.
This can prevent 1px offset issue in some cases where panel size has the fractional part.
All sizes will have the original size before CSS transform is applied on the element.

Type: boolean

Default: false

See:

externalRenderer

readonly

This is an option for the frameworks(React, Vue, Angular, ...). Don't set it as it's automatically managed by Flicking.

Default: null

renderExternal

readonly

This is an option for the frameworks(React, Vue, Angular, ...). Don't set it as it's automatically managed by Flicking.

Default: null

Methods

init

Initialize Flicking and move to the default index
This is automatically called on Flicking's constructor when autoInit is true(default)

Returns: Promise<void>

Emits: Flicking#event:ready

destroy

Destroy Flicking and remove all event handlers

Returns: void

prev

async

Move to the previous panel (current index - 1)

Returns: Promise<void>

  • A Promise which will be resolved after reaching the previous panel

Emits: Flicking#event:moveStart, Flicking#event:move, Flicking#event:moveEnd, Flicking#event:willChange, Flicking#event:changed, Flicking#event:willRestore, Flicking#event:restored, Flicking#event:needPanel, Flicking#event:visibleChange, Flicking#event:reachEdge

PARAMETERTYPEOPTIONALDEFAULTDESCRIPTION
durationnumber✔️options.durationDuration of the panel movement animation (unit: ms)

Throws: FlickingError

|code|condition|
|---|---|
|INDEX_OUT_OF_RANGE|When the previous panel does not exist|
|ANIMATION_ALREADY_PLAYING|When the animation is already playing|
|ANIMATION_INTERRUPTED|When the animation is interrupted by user input|
|STOP_CALLED_BY_USER|When the any of the event's stop() is called|

next

async

Move to the next panel (current index + 1)

Returns: Promise<void>

  • A Promise which will be resolved after reaching the next panel

Emits: Flicking#event:moveStart, Flicking#event:move, Flicking#event:moveEnd, Flicking#event:willChange, Flicking#event:changed, Flicking#event:willRestore, Flicking#event:restored, Flicking#event:needPanel, Flicking#event:visibleChange, Flicking#event:reachEdge

PARAMETERTYPEOPTIONALDEFAULTDESCRIPTION
durationnumber✔️options.durationDuration of the panel movement animation (unit: ms).

Throws: FlickingError

|code|condition|
|---|---|
|INDEX_OUT_OF_RANGE|When the next panel does not exist|
|ANIMATION_ALREADY_PLAYING|When the animation is already playing|
|ANIMATION_INTERRUPTED|When the animation is interrupted by user input|
|STOP_CALLED_BY_USER|When the any of the event's stop() is called|

moveTo

async

Move to the panel with given index

Returns: Promise<void>

  • A Promise which will be resolved after reaching the target panel

Emits: Flicking#event:moveStart, Flicking#event:move, Flicking#event:moveEnd, Flicking#event:willChange, Flicking#event:changed, Flicking#event:willRestore, Flicking#event:restored, Flicking#event:needPanel, Flicking#event:visibleChange, Flicking#event:reachEdge

PARAMETERTYPEOPTIONALDEFAULTDESCRIPTION
indexnumberThe index of the panel to move
durationnumber✔️options.durationDuration of the animation (unit: ms)
directionDIRECTION✔️DIRECTION.NONEDirection to move, only available in the circular mode

Throws: FlickingError

|code|condition|
|---|---|
|INDEX_OUT_OF_RANGE|When the root is not either string or HTMLElement|
|ANIMATION_ALREADY_PLAYING|When the animation is already playing|
|ANIMATION_INTERRUPTED|When the animation is interrupted by user input|
|STOP_CALLED_BY_USER|When the any of the event's stop() is called|

updateAnimation

Change the destination and duration of the animation currently playing

Returns: void

PARAMETERTYPEOPTIONALDEFAULTDESCRIPTION
indexnumberThe index of the panel to move
durationnumber✔️Duration of the animation (unit: ms)
directionDIRECTION✔️Direction to move, only available in the circular mode

Throws: FlickingError

INDEX_OUT_OF_RANGE When the root is not either string or HTMLElement

stopAnimation

Stops the animation currently playing

Returns: void

Emits: Flicking#event:moveEnd

getPanel

Return the Panel at the given index. null if it doesn't exists.

Returns: Panel | null

  • Panel at the given index
PARAMETERTYPEOPTIONALDEFAULTDESCRIPTION
indexnumber

See:

const panel = flicking.getPanel(0);
// Which is a shorthand to...
const samePanel = flicking.panels[0];

enableInput

Enable input from the user (mouse/touch)

Returns: this

disableInput

Disable input from the user (mouse/touch)

Returns: this

getStatus

Get current flicking status. You can restore current state by giving returned value to setStatus()

Returns: Status

  • An object with current status value information
PARAMETERTYPEOPTIONALDEFAULTDESCRIPTION
optionsobject✔️{}Status retrieving options
options.indexboolean✔️trueInclude current panel index to the returning status. Camera will automatically move to the given index when the setStatus is called
options.positionboolean✔️trueInclude camera position to the returning status. This works only when the moveType is freeScroll
options.includePanelHTMLboolean✔️falseInclude panel's outerHTML to the returning status
options.visiblePanelsOnlyboolean✔️falseInclude only visiblePanel's HTML. This option is available only when the includePanelHTML is true

setStatus

Restore to the state of the given Status

Returns: void

PARAMETERTYPEOPTIONALDEFAULTDESCRIPTION
statusPartial<Status>Status value to be restored. You should use the return value of the getStatus() method

addPlugins

Add plugins that can have different effects on Flicking

Returns: this

PARAMETERTYPEOPTIONALDEFAULTDESCRIPTION
pluginsPluginThe plugin(s) to add

See:

removePlugins

Remove plugins from Flicking.

Returns: this

PARAMETERTYPEOPTIONALDEFAULTDESCRIPTION
pluginPluginThe plugin(s) to remove.

See:

resize

async

Update viewport/panel sizes

Returns: this

Emits: Flicking#event:beforeResize, Flicking#event:afterResize

append

Add new panels after the last panel

Returns: Array<Panel>

  • An array of appended panels
PARAMETERTYPEOPTIONALDEFAULTDESCRIPTION
elementElementLike | Array<ElementLike>A new HTMLElement, a outerHTML of element, or an array of both

Throws: FlickingError

ERROR_CODE.NOT_ALLOWED_IN_FRAMEWORK if called on frameworks (React, Angular, Vue...)
See:

const flicking = new Flicking("#flick");
// These are possible parameters
flicking.append(document.createElement("div"));
flicking.append("\<div\>Panel\</div\>");
flicking.append(["\<div\>Panel\</div\>", document.createElement("div")]);
// Even this is possible
flicking.append("\<div\>Panel 1\</div\>\<div\>Panel 2\</div\>");

prepend

Add new panels before the first panel
This will increase index of panels after by the number of panels added

Returns: Array<Panel>

  • An array of prepended panels
PARAMETERTYPEOPTIONALDEFAULTDESCRIPTION
elementElementLike | Array<ElementLike>A new HTMLElement, a outerHTML of element, or an array of both

Throws: FlickingError

ERROR_CODE.NOT_ALLOWED_IN_FRAMEWORK if called on frameworks (React, Angular, Vue...)
See:

const flicking = new eg.Flicking("#flick");
flicking.prepend(document.createElement("div"));
flicking.prepend("\<div\>Panel\</div\>");
flicking.prepend(["\<div\>Panel\</div\>", document.createElement("div")]);
// Even this is possible
flicking.prepend("\<div\>Panel 1\</div\>\<div\>Panel 2\</div\>");

insert

Insert new panels at given index
This will increase index of panels after by the number of panels added

Returns: Array<Panel>

  • An array of prepended panels
PARAMETERTYPEOPTIONALDEFAULTDESCRIPTION
indexnumberIndex to insert new panels at
elementElementLike | Array<ElementLike>A new HTMLElement, a outerHTML of element, or an array of both

Throws: FlickingError

ERROR_CODE.NOT_ALLOWED_IN_FRAMEWORK if called on frameworks (React, Angular, Vue...)

const flicking = new eg.Flicking("#flick");
flicking.insert(0, document.createElement("div"));
flicking.insert(2, "\<div\>Panel\</div\>");
flicking.insert(1, ["\<div\>Panel\</div\>", document.createElement("div")]);
// Even this is possible
flicking.insert(3, "\<div\>Panel 1\</div\>\<div\>Panel 2\</div\>");

remove

Remove the panel at the given index
This will decrease index of panels after by the number of panels removed

Returns: Array<Panel>

  • An array of removed panels
PARAMETERTYPEOPTIONALDEFAULTDESCRIPTION
indexnumberIndex of panel to remove
deleteCountnumber✔️1Number of panels to remove from index

Events

ready

Event that fires when Flicking's init() is called

Type: object

PROPERTYTYPEDESCRIPTION
currentTargetFlickingAn Flicking instance that triggered this event
eventTypestringName of the event

beforeResize

Event that fires when Flicking's resize() is called, before updating the sizes of panels and viewport.
You can update the sizes of panels and viewport with this event, and it'll be applied after resize() is finished.

Type: object

PROPERTYTYPEDESCRIPTION
currentTargetFlickingAn Flicking instance that triggered this event
eventTypestringName of the event
widthnumberPrevious width of the viewport
heightnumberPrevious height of the viewport
elementHTMLElementThe viewport element

afterResize

Event that fires when Flicking's resize() is called, after updating the sizes of panels and viewport.

Type: object

PROPERTYTYPEDESCRIPTION
currentTargetFlickingAn Flicking instance that triggered this event
eventTypestringName of the event
widthnumberNew width of the viewport
heightnumberNew height of the viewport
prevobjectPrevious size of the viewport
prev.widthnumberPrevious width of the viewport
prev.heightnumberPrevious height of the viewport
sizeChangedbooleanA Boolean value indicating whether the width/height of the viewport element is changed
elementHTMLElementThe viewport element

holdStart

Event that fires when user started dragging.

Type: object

PROPERTYTYPEDESCRIPTION
currentTargetFlickingAn Flicking instance that triggered this event
eventTypestringName of the event
stopfunctionStop the event action and prevent user from dragging
axesEventobjecthold event of Axes

holdEnd

Event that fires when user stopped dragging.

Type: object

PROPERTYTYPEDESCRIPTION
currentTargetFlickingAn Flicking instance that triggered this event
eventTypestringName of the event
axesEventobjectrelease event of Axes

moveStart

Event that fires once before first move event

Type: object

PROPERTYTYPEDESCRIPTION
currentTargetFlickingAn Flicking instance that triggered this event
eventTypestringName of the event
stopfunctionStop the event action and prevent user from dragging
isTrustedbooleanBoolean that indicates whether the event was generated by a user action
holdingbooleanBoolean that indicates whether the user is dragging the viewport element
directionDIRECTIONMoving direction relative to previous position of the camera
axesEventobjectchange event of Axes

move

Event that fires for every movement

Type: object

PROPERTYTYPEDESCRIPTION
currentTargetFlickingAn Flicking instance that triggered this event
eventTypestringName of the event
stopfunctionStop the event action and prevent user from dragging
isTrustedbooleanBoolean that indicates whether the event was generated by a user action
holdingbooleanBoolean that indicates whether the user is dragging the viewport element
directionDIRECTIONMoving direction relative to previous position of the camera
axesEventobjectchange event of Axes

moveEnd

Event that fires when the movement is finished by user input release or animation end.

Type: object

PROPERTYTYPEDESCRIPTION
currentTargetFlickingAn Flicking instance that triggered this event
eventTypestringName of the event
isTrustedbooleanBoolean that indicates whether the event was generated by a user action
holdingbooleanBoolean that indicates whether the user is dragging the viewport element
directionDIRECTIONMoving direction relative to previous position of the camera
axesEventobjectfinish event of Axes

willChange

Event that fires when Flicking's active index will be changed. Index will be changed at the changed event.
It can be triggered when user finished input, or flicking start to move by method.
Calling stop() in event will prevent index change and camera movement.

Type: object

PROPERTYTYPEDESCRIPTION
currentTargetFlickingAn Flicking instance that triggered this event
eventTypestringName of the event
stopfunctionStop the event action and prevent user from dragging
indexnumberNew active index
panelPanelNew active panel
isTrustedbooleanBoolean that indicates whether the event was generated by a user action
directionDIRECTIONMoving direction from the active panel to the target panel

changed

Event that fires when Flicking's index is changed.

Type: object

PROPERTYTYPEDESCRIPTION
currentTargetFlickingAn Flicking instance that triggered this event
eventTypestringName of the event
indexnumberNew index
panelPanelNew active panel
prevIndexnumberPrevious index
prevPanelPanel | nullPrevious active panel
isTrustedbooleanBoolean that indicates whether the event was generated by a user action
directionDIRECTIONMoving direction from the active panel to the target panel

willRestore

Event fires when user drag amount not reached threshold and is returning to currentPanel

Type: object

PROPERTYTYPEDESCRIPTION
currentTargetFlickingAn Flicking instance that triggered this event
eventTypestringName of the event
stopfunctionStop the event action and prevent user from dragging
indexnumberIndex of the panel to restore
panelPanelPanel to restore
isTrustedbooleanBoolean that indicates whether the event was generated by a user action
directionDIRECTIONMoving direction relative to previous position of the camera

restored

Event that fires when Flicking has returned to currentPanel

Type: object

PROPERTYTYPEDESCRIPTION
currentTargetFlickingAn Flicking instance that triggered this event
eventTypestringName of the event
isTrustedbooleanBoolean that indicates whether the event was generated by a user action

select

Event that fires when panel is statically click / touched

Type: object

PROPERTYTYPEDESCRIPTION
currentTargetFlickingAn Flicking instance that triggered this event
eventTypestringName of the event
indexnumberSelected panel's index
panelPanelSelected panel
directionDIRECTIONDirection from current camera position to the selected panel's position

needPanel

Event that fires when an empty panel area is visible at the edge of viewport
You can set its threshold with needPanelThreshold

Type: object

PROPERTYTYPEDESCRIPTION
currentTargetFlickingAn Flicking instance that triggered this event
eventTypestringName of the event
directionDIRECTIONDirection where new panel is needed. DIRECTION.PREV means panels should be prepended and DIRECTION.NEXT means panels should be appended

visibleChange

Event that fires when visible panel inside the viewport changes

Type: object

PROPERTYTYPEDESCRIPTION
currentTargetFlickingAn Flicking instance that triggered this event
eventTypestringName of the event
addedArray<Panel>Panels that added from previous visible panels
removedArray<Panel>Panels that removed from previous visible panels
visiblePanelsArray<Panel>Current visible panels

reachEdge

Event that fires when camera reaches the maximum/minimum range

Type: object

PROPERTYTYPEDESCRIPTION
currentTargetFlickingAn Flicking instance that triggered this event
eventTypestringName of the event
directionDIRECTIONDirection indicates whether the camera's position is at the maximum range(DIRECTION.NEXT) or minimum range(DIRECTION.PREV)

panelChange

Event that fires when a panel is added or removed

Type: object

PROPERTYTYPEDESCRIPTION
currentTargetFlickingAn Flicking instance that triggered this event
eventTypestringName of the event
addedArray<Panel>An array of new panels added
removedArray<Panel>An array of panels removed