Skip to main content
Version: 4.1.0

Flicking

class Flicking extends Component

Constructor#

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

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:

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

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

horizontal#

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

Type: boolean

Default: true

circular#

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

Type: boolean

Default: false

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

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

needPanelThreshold#

A Threshold from viewport edge before triggering needPanel event

Type: number

Default: 0

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

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

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"

moveTypecontroloptions
"snap"{@link SnapControl}
"freeScroll"{@link FreeControl}{@link FreeControlOptions}
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

interruptable#

Set animation to be interruptable by click/touch.

Type: boolean

Default: true

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%"

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

preventClickOnDrag#

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

Type: boolean

Default: true

disableOnInit#

Automatically call disableInput() on initialization

Type: boolean

Default: false

renderOnlyVisible#

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

Type: boolean

Default: false

autoInit#

readonly

Call init() automatically when creating Flicking's instance

Type: boolean

Default: true

autoResize#

Attach Flicking's resize method to window's resize event.
Flicking will automatically call resize window size and orientation change.

Type: boolean

Default: true

renderExternal#

readonly

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

Type: boolean

Default: false

โš ๏ธ This member is for internal use only.

Methods#

init#

async

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

Returns: this

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
durationnumberyesoptions.durationDuration of the panel movement animation (unit: ms)

Throws: FlickingError

codecondition
INDEX_OUT_OF_RANGEWhen the previous panel does not exist
ANIMATION_ALREADY_PLAYINGWhen the animation is already playing
ANIMATION_INTERRUPTEDWhen the animation is interrupted by user input
STOP_CALLED_BY_USERWhen 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
durationnumberyesoptions.durationDuration of the panel movement animation (unit: ms).

Throws: FlickingError

codecondition
INDEX_OUT_OF_RANGEWhen the next panel does not exist
ANIMATION_ALREADY_PLAYINGWhen the animation is already playing
ANIMATION_INTERRUPTEDWhen the animation is interrupted by user input
STOP_CALLED_BY_USERWhen 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
indexnumbernoThe index of the panel to move
durationnumberyesoptions.durationDuration of the animation (unit: ms)
directionDIRECTIONyesDIRECTION.NONEDirection to move, only available in the circular mode

Throws: FlickingError

codecondition
INDEX_OUT_OF_RANGEWhen the root is not either string or HTMLElement
ANIMATION_ALREADY_PLAYINGWhen the animation is already playing
ANIMATION_INTERRUPTEDWhen the animation is interrupted by user input
STOP_CALLED_BY_USERWhen the any of the event's stop() is called

getPanel#

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

Returns: Panel | null

  • Panel at the given index
PARAMETERTYPEOPTIONALDEFAULTDESCRIPTION
indexnumberno

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: Partial<Status>

  • An object with current status value information
PARAMETERTYPEOPTIONALDEFAULTDESCRIPTION
optionsobjectyes{}Status retrieving options
options.indexbooleanyestrueInclude current panel index to the returning status. Camera will automatically move to the given index when the setStatus is called
options.positionbooleanyestrueInclude camera position to the returning status. This works only when the moveType is freeScroll
options.includePanelHTMLbooleanyesInclude panel's outerHTML to the returning status
options.visiblePanelsOnlybooleanyesInclude 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>noStatus 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
pluginsPluginnoThe plugin(s) to add

See:

removePlugins#

Remove plugins from Flicking.

Returns: this

PARAMETERTYPEOPTIONALDEFAULTDESCRIPTION
pluginPluginnoThe 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>noA 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>noA 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
indexnumbernoIndex to insert new panels at
elementElementLike | Array<ElementLike>noA 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
indexnumbernoIndex of panel to remove
deleteCountnumberyes1Number of panels to remove from index

trigger#

inherited

Trigger a custom event.

Returns: this

  • An instance of the component itself
PARAMETERTYPEOPTIONALDEFAULTDESCRIPTION
eventstring | ComponentEventnoThe name of the custom event to be triggered or an instance of the ComponentEvent
paramsArray<any> | $ts:...noEvent data to be sent when triggering a custom event
import Component, { ComponentEvent } from "@egjs/component";
class Some extends Component<{
beforeHi: ComponentEvent<{ foo: number; bar: string }>;
hi: { foo: { a: number; b: boolean } };
someEvent: (foo: number, bar: string) => void;
someOtherEvent: void; // When there's no event argument
}> {
some(){
if(this.trigger("beforeHi")){ // When event call to stop return false.
this.trigger("hi");// fire hi event.
}
}
}
const some = new Some();
some.on("beforeHi", e => {
if(condition){
e.stop(); // When event call to stop, `hi` event not call.
}
// `currentTarget` is component instance.
console.log(some === e.currentTarget); // true
typeof e.foo; // number
typeof e.bar; // string
});
some.on("hi", e => {
typeof e.foo.b; // boolean
});
// If you want to more know event design. You can see article.
// https://github.com/naver/egjs-component/wiki/How-to-make-Component-event-design%3F

once#

inherited

Executed event just one time.

Returns: this

  • An instance of the component itself
PARAMETERTYPEOPTIONALDEFAULTDESCRIPTION
eventNamestring | $ts:...noThe name of the event to be attached or an event name - event handler mapped object.
handlerToAttachfunction | $ts:...yesThe handler function of the event to be attached
import Component, { ComponentEvent } from "@egjs/component";
class Some extends Component<{
hi: ComponentEvent;
}> {
hi() {
alert("hi");
}
thing() {
this.once("hi", this.hi);
}
}
var some = new Some();
some.thing();
some.trigger(new ComponentEvent("hi"));
// fire alert("hi");
some.trigger(new ComponentEvent("hi"));
// Nothing happens

hasOn#

inherited

Checks whether an event has been attached to a component.

Returns: boolean

  • Indicates whether the event is attached.
PARAMETERTYPEOPTIONALDEFAULTDESCRIPTION
eventNamestringnoThe name of the event to be attached
import Component from "@egjs/component";
class Some extends Component<{
hi: void;
}> {
some() {
this.hasOn("hi");// check hi event.
}
}

on#

inherited

Attaches an event to a component.

Returns: this

  • An instance of a component itself
PARAMETERTYPEOPTIONALDEFAULTDESCRIPTION
eventNamestring | $ts:...noThe name of the event to be attached or an event name - event handler mapped object.
handlerToAttachfunction | $ts:...yesThe handler function of the event to be attached
import Component, { ComponentEvent } from "@egjs/component";
class Some extends Component<{
hi: void;
}> {
hi() {
console.log("hi");
}
some() {
this.on("hi",this.hi); //attach event
}
}

off#

inherited

Detaches an event from the component.
If the eventName is not given this will detach all event handlers attached.
If the handlerToDetach is not given, this will detach all event handlers for eventName.

Returns: this

  • An instance of a component itself
PARAMETERTYPEOPTIONALDEFAULTDESCRIPTION
eventNamestring | $ts:...yesThe name of the event to be detached
handlerToDetachfunction | $ts:...yesThe handler function of the event to be detached
import Component, { ComponentEvent } from "@egjs/component";
class Some extends Component<{
hi: void;
}> {
hi() {
console.log("hi");
}
some() {
this.off("hi",this.hi); //detach event
}
}

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