Skip to main content
Version: 4.0.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

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)