Flicking
Constructor
constructor(root: HTMLElement | string, options?: Partial<FlickingOptions>);
Creates a new Flicking instance
Parameters
root (HTMLElement | string) - A root HTMLElement to initialize Flicking on it. When it's a typeof string, it should be a css selector string
options (Partial<FlickingOptions>) - A FlickingOptions object
Throws:
Examples
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
activePlugins
Type: Plugin[]
Array of currently activated plugins.
Remarks: Plugins are added via addPlugins and removed via removePlugins.
This property is read-only.
animating
Type: boolean
Whether Flicking is currently animating.
Remarks: This is a shorthand for Flicking.control.animating.
This property is read-only.
animationThreshold
Type: FlickingOptions["animationThreshold"]
Current value of the animationThreshold option.
autoInit
Type: FlickingOptions["autoInit"]
Current value of the autoInit option.
This property is read-only.
autoResizer
Type: AutoResizer
AutoResizer instance that detects size changes and triggers resize when autoResize option is enabled
This property is read-only.
camera
Type: Camera
Camera instance that manages actual movement and positioning inside the viewport
Remarks: The concrete Camera implementation is selected based on circular and bound options.
This property is read-only.
changeOnHold
Type: FlickingOptions["changeOnHold"]
Current value of the changeOnHold option.
circularEnabled
Type: boolean
Whether the circular mode is actually enabled.
Remarks: The circular option may not be enabled when the sum of panel sizes is too small. This property reflects the actual enabled state, which may differ from the circular option value.
Default: false
This property is read-only.
circularFallback
Type: FlickingOptions["circularFallback"]
Current value of the circularFallback option.
This property is read-only.
control
Type: Control
Control instance that manages user input and panel movement animations
Remarks: The concrete Control implementation is selected based on moveType option.
This property is read-only.
currentPanel
Type: Panel | null
The currently active panel.
Remarks: Returns null when there is no active panel. This is a shorthand for Flicking.control.activePanel.
This property is read-only.
element
Type: HTMLElement
The root viewport element (.flicking-viewport).
Remarks: This is the element passed to the Flicking constructor. It is a shorthand for Flicking.viewport.element.
This property is read-only.
externalRenderer
Type: FlickingOptions["externalRenderer"]
Current value of the externalRenderer option.
This property is read-only.
holding
Type: boolean
Whether the user is currently clicking or touching the viewport.
Remarks: This is a shorthand for Flicking.control.holding.
This property is read-only.
index
Type: number
Index of the currently active panel.
Remarks: Returns -1 when there is no active panel. This is a shorthand for Flicking.currentPanel.index.
This property is read-only.
initialized
Type: boolean
Whether Flicking's init is called.
Remarks: This is true when init is called, and is false after calling destroy. Use this to check if Flicking is ready before calling certain methods that require initialization.
Default: false
This property is read-only.
iOSEdgeSwipeThreshold
Type: FlickingOptions["iOSEdgeSwipeThreshold"]
Current value of the iOSEdgeSwipeThreshold option.
maxResizeDebounce
Type: FlickingOptions["maxResizeDebounce"]
Current value of the maxResizeDebounce option.
This property is read-only.
needPanelThreshold
Type: FlickingOptions["needPanelThreshold"]
Current value of the needPanelThreshold option.
noPanelStyleOverride
Type: FlickingOptions["noPanelStyleOverride"]
Current value of the noPanelStyleOverride option.
observePanelResize
Type: FlickingOptions["observePanelResize"]
Current value of the observePanelResize option.
panelCount
Type: number
Total number of panels.
Remarks: This is a shorthand for Flicking.renderer.panelCount.
This property is read-only.
panels
Type: Panel[]
Array of all panels.
Remarks: This is a shorthand for Flicking.renderer.panels.
This property is read-only.
panelsPerView
Type: FlickingOptions["panelsPerView"]
Current value of the panelsPerView option.
preventClickOnDrag
Type: FlickingOptions["preventClickOnDrag"]
Current value of the preventClickOnDrag option.
preventDefaultOnDrag
Type: FlickingOptions["preventDefaultOnDrag"]
Current value of the preventDefaultOnDrag option.
preventEventsBeforeInit
Type: FlickingOptions["preventEventsBeforeInit"]
Current value of the preventEventsBeforeInit option.
renderer
Type: Renderer
Renderer instance that manages panels and their elements
Remarks: The concrete Renderer implementation is selected based on externalRenderer and virtual options.
This property is read-only.
renderExternal
Type: FlickingOptions["renderExternal"]
⚠️ Deprecated: Use externalRenderer instead. Current value of the renderExternal option.
This property is read-only.
renderOnlyVisible
Type: FlickingOptions["renderOnlyVisible"]
Current value of the renderOnlyVisible option.
resizeDebounce
Type: FlickingOptions["resizeDebounce"]
Current value of the resizeDebounce option.
This property is read-only.
resizeOnContentsReady
Type: FlickingOptions["resizeOnContentsReady"]
Current value of the resizeOnContentsReady option.
useCSSOrder
Type: FlickingOptions["useCSSOrder"]
Current value of the useCSSOrder option.
useFractionalSize
Type: FlickingOptions["useFractionalSize"]
Current value of the useFractionalSize option.
This property is read-only.
usePercentagePos
Type: FlickingOptions["usePercentagePos"]
Current value of the usePercentagePos option.
useResizeObserver
Type: FlickingOptions["useResizeObserver"]
Current value of the useResizeObserver option.
viewport
Type: Viewport
Viewport instance that manages viewport size and element
This property is read-only.
virtual
Type: VirtualManager
VirtualManager instance that manages virtual panels
This property is read-only.
virtualEnabled
Type: boolean
Whether the virtual mode is actually enabled.
Remarks: The virtual option may not be enabled when panelsPerView is less than or equal to zero. This property reflects the actual enabled state, which may differ from the virtual option value.
Default: false
This property is read-only.
visiblePanels
Type: Panel[]
Array of panels that are currently visible in the viewport.
Remarks: This is a shorthand for Flicking.camera.visiblePanels.
This property is read-only.
Methods
addPlugins
addPlugins(...plugins: Plugin[]): this
Add plugins to Flicking.
Parameters:
plugins(Plugin[]) -Plugin
Returns: The current instance for method chaining
Remarks: Plugins are automatically initialized if Flicking is already initialized.
append
append(element: ElementLike | ElementLike[]): Panel[]
Add new panels after the last panel.
Parameters:
element(ElementLike | ElementLike[]) - A new HTMLElement, outerHTML string, or an array of both
Returns: Array of appended panels
Throws:
destroy
destroy(): void
Destroy Flicking and remove all event handlers.
Remarks: This method cleans up all resources including event handlers, components, and plugins. After calling this method, initialized will be false and the instance should not be used.
disableInput
disableInput(): this
Disable user input (mouse/touch).
Returns: The current instance for method chaining
Remarks: This is a shorthand for Flicking.control.disable.
enableInput
enableInput(): this
Enable user input (mouse/touch).
Returns: The current instance for method chaining
Remarks: This is a shorthand for Flicking.control.enable.
getPanel
getPanel(index: number): Panel | null
Get the panel at the given index.
Parameters:
index(number) - The index of the panel to get
Returns: The panel at the given index, or null if it doesn't exist. This is a shorthand for Flicking.renderer.getPanel(index).
getStatus
getStatus(options?: GetStatusParams): Status
Get the current Flicking status.
Parameters:
options(GetStatusParams) - GetStatusParams
Returns: Status object that can be used with setStatus to restore the state
init
init(): Promise<void>
Initialize Flicking and move to the default index.
Returns: Promise that resolves when initialization is complete
Remarks: This method is automatically called in the constructor when autoInit is true (default). If Flicking is already initialized, this method returns immediately without doing anything.
Fires:
insert
insert(index: number, element: ElementLike | ElementLike[]): Panel[]
Insert new panels at the given index.
Parameters:
-
index(number) - Index to insert new panels at -
element(ElementLike | ElementLike[]) - A new HTMLElement, outerHTML string, or an array of both
Returns: Array of inserted panels
Remarks: This will increase the index of panels at or after the given index by the number of panels added.
Throws:
moveTo
moveTo(index: number, duration?: number, direction?: ValueOf<typeof DIRECTION>): Promise<void>
Move to the panel with the given index.
Parameters:
-
index(number) - The index of the panel to move to -
duration(number) - Duration of the animation (unit: ms). Defaults to duration -
direction(ValueOf<typeof DIRECTION>) - Direction to move (circular mode only). Defaults toNONE
Returns: Promise that resolves after reaching the target panel
Throws:
Fires:
next
next(duration?: number): Promise<void>
Move to the next panel (current index + 1).
Parameters:
duration(number) - Duration of the panel movement animation (unit: ms). Defaults to duration
Returns: Promise that resolves after reaching the next panel
Throws:
Fires:
prepend
prepend(element: ElementLike | ElementLike[]): Panel[]
Add new panels before the first panel.
Parameters:
element(ElementLike | ElementLike[]) - A new HTMLElement, outerHTML string, or an array of both
Returns: Array of prepended panels
Remarks: This will increase the index of existing panels by the number of panels added.
Throws:
prev
prev(duration?: number): Promise<void>
Move to the previous panel (current index - 1).
Parameters:
duration(number) - Duration of the panel movement animation (unit: ms). Defaults to duration
Returns: Promise that resolves after reaching the previous panel
Throws:
Fires:
remove
remove(index: number, deleteCount?: number): Panel[]
Remove panels starting from the given index.
Parameters:
-
index(number) - Index of the first panel to remove -
deleteCount(number) - Number of panels to remove. Defaults to1
Returns: Array of removed panels
Remarks: This will decrease the index of panels after the removed ones by the number of panels removed.
Throws:
removePlugins
removePlugins(...plugins: Plugin[]): this
Remove plugins from Flicking.
Parameters:
plugins(Plugin[]) -Plugin
Returns: The current instance for method chaining
resize
resize(): Promise<void>
Update viewport and panel sizes.
Returns: Promise that resolves when resize is complete
Remarks: This method does nothing if a resize is already in progress.
Fires:
setStatus
setStatus(status: Status): void
Restore Flicking to the state of the given Status.
Parameters:
status(Status) - Status
Throws:
stopAnimation
stopAnimation(): void
Stop the animation currently playing.
Remarks: This method does nothing if no animation is currently playing.
Fires:
updateAnimation
updateAnimation(index: number, duration?: number, direction?: ValueOf<typeof DIRECTION>): void
Change the destination and duration of the animation currently playing.
Parameters:
-
index(number) - The index of the panel to move to -
duration(number) - Duration of the animation (unit: ms) -
direction(ValueOf<typeof DIRECTION>) - Direction to move. Only available when circular is enabled
Remarks: This method does nothing if no animation is currently playing.
Throws: