FlickingOptions
Options for the Flicking component
Properties
adaptive
Type: boolean
Update height of the viewport element after movement same to the height of the panel below.
Default: false
Dependencies:
- Conditional: Only works when horizontal is true. When horizontal is false, this option has no effect.
See Also:
align
Type: LiteralUnion<ValueOf<typeof ALIGN>> | number | { panel: number | string; camera: number | string; }
Align position of the panels within viewport. You can set different values each for the panel and camera.
Default: "center"
Accepts: ALIGN - "prev" | "center" | "next"
Remarks: Possible values include
-
literal strings ("prev", "center", "next")
-
percentage values ("0%", "25%")
-
pixel values ("0px", "100px")
-
arithmetic expressions ("50% - 25px")
-
numbers
-
an object with separate
panelandcameraalignment values
Example:
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 });
});
See Also:
animationThreshold
Type: number
The minimum distance for animation to proceed.
Default: 0.5
Remarks: If the distance to be moved is less than animationThreshold, the movement proceeds immediately without animation (duration: 0).
See Also:
autoInit
Type: boolean
Call init() automatically when creating Flicking's instance.
Default: true
See Also:
autoResize
Type: boolean
Whether to automatically call resize() when the viewport element (.flicking-viewport) size is changed.
Default: true
See Also:
bounce
Type: number | string | [number | string, number | string]
The size value of the bounce area.
Default: "20%"
Dependencies:
-
Conditional: Only can be enabled when circular is false
-
Related: Works with bound to provide bounce effect at panel boundaries
Example:
const possibleOptions = [
"0%", "25%", "42%", // % values
"0px", "100px", "50% - 25px", // px values with arithmetic
0, 100, 1000 // numbers (same as px)
];
See Also:
bound
Type: boolean
Prevent the view (camera element) from going out of the first/last panel.
Default: false
Dependencies:
-
Mutual Exclusive: circular. When circular is true, this option is ignored.
-
Related: Works with bounce for bounce effect at boundaries
See Also:
changeOnHold
Type: boolean
Change active panel index on mouse/touch hold while animating.
Default: false
Remarks: index of the willChange/willRestore event will be used as new index.
See Also:
circular
Type: boolean
Enables circular (continuous loop) mode, which connects first/last panel for continuous scrolling.
Default: false
Dependencies:
-
Conditional: Total panel size must be ≥ viewport size. If not met, automatically falls back to circularFallback mode.
-
Mutual Exclusive: bound. When both are true, circular takes precedence and bound will be ignored.
-
Related: circularFallback determines fallback behavior when circular cannot be enabled
See Also:
circularFallback
Type: LiteralUnion<ValueOf<typeof CIRCULAR_FALLBACK>>
Set panel control mode for the case when circular cannot be enabled.
Default: "linear"
Accepts: CIRCULAR_FALLBACK - "linear" | "bound"
Dependencies:
- Requires: Only takes effect when circular is true but activation requirements are not met (total panel size < viewport size)
See Also:
deceleration
Type: number
Deceleration of panel movement animation with momentum applied by user interaction (input). Higher values result in a shorter animation duration.
Default: 0.0075
See Also:
defaultIndex
Type: number
Index of the panel to move when Flicking's init() is called. A zero-based integer.
Default: 0
See Also:
disableOnInit
Type: boolean
Automatically call disableInput() during initialization.
Default: false
See Also:
dragThreshold
Type: number
Minimum distance to recognize user input (unit: px). Panels will only move after scrolling beyond this value.
Default: 1
See Also:
easing
Type: (x: number) => number
An easing function applied to the panel movement animation.
Default: "easeOutCubic" (x => 1 - Math.pow(1 - x, 3))
See Also:
horizontal
Type: boolean
Direction of panel movement. true for horizontal, false for vertical.
Default: true
Remarks: In vanilla JS, you must manually add the vertical class to the viewport element when using vertical mode. React and Vue wrappers add this class automatically.
Example:
// Vanilla JS: add "vertical" class to the viewport element
// <div class="flicking-viewport vertical">
// <div class="flicking-camera">...</div>
// </div>
const flicking = new Flicking("#my-flicking", {
horizontal: false
});
See Also:
interruptable
Type: boolean
Allows stopping animations with user click/touch input.
Default: true
See Also:
iOSEdgeSwipeThreshold
Type: number
Size of the area from the right edge in iOS Safari (in px) that enables swipe-back or swipe-forward.
Default: 30
See Also:
maxResizeDebounce
Type: number
The maximum time for size recalculation delay when using resizeDebounce, in milliseconds.
Default: 100
Remarks: This guarantees that size recalculation is performed at least once every (n)ms.
See Also:
moveType
Type: ValueOf<typeof MOVE_TYPE> | MoveTypeOptions<ValueOf<typeof MOVE_TYPE>>
Movement style by user input. Determines the instance type of control.
Default: "snap"
Accepts: MOVE_TYPE - "snap" | "freeScroll" | "strict"
Remarks: - "snap": Uses SnapControl
-
"freeScroll": Uses FreeControl with FreeControlOptions
-
"strict": Uses StrictControl with StrictControlOptions
Example:
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 }]
});
See Also:
needPanelThreshold
Type: number
A threshold from the viewport edge to trigger the needPanel event.
Default: 0
See Also:
nested
Type: boolean
Enable nested Flicking mode to allow parent Flicking to move when reaching boundaries.
Default: false
Remarks: When Flicking is nested inside another Flicking, enabling this option allows the parent Flicking to move in the same direction after the nested Flicking reaches the first or last panel.
This option is not required if the parent and nested Flicking have different horizontal options.
See Also:
noPanelStyleOverride
Type: boolean
When enabled, prevents modifying the panel's width/height styles when panelsPerView is enabled. Enabling this option can improve performance if you are manually managing all panel sizes.
Default: false
See Also:
observePanelResize
Type: boolean
Whether to use ResizeObserver to observe the size of the panel element.
Default: false
Dependencies:
- Conditional: Only available when useResizeObserver is enabled
See Also:
panelsPerView
Type: number
A visible number of panels on viewport. Enabling this option will force the panel to resize.
Default: -1
Dependencies:
-
Related: Affects how align calculates panel positions
-
Related: Works with noPanelStyleOverride to prevent style modifications
-
Requires: Required for virtual to work (must be > 0)
See Also:
preventClickOnDrag
Type: boolean
Automatically cancels click events when the user drags the viewport by any amount.
Default: true
See Also:
preventDefaultOnDrag
Type: boolean
Whether to use the preventDefault when the user starts dragging
Default: false
See Also:
preventEventsBeforeInit
Type: boolean
When enabled, disables events before the ready event during initialization.
Default: true
See Also:
renderExternal
Type: { renderer: new (options: RendererOptions) => ExternalRenderer; rendererOptions: RendererOptions; } | null
⚠️ Deprecated: Use externalRenderer instead
renderOnlyVisible
Type: boolean
When enabled, only renders visible panels. Can significantly improve performance with many panels.
Default: false
See Also:
resizeDebounce
Type: number
Delays size recalculation from autoResize by the given time in milliseconds.
Default: 0
Remarks: 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.
See Also:
resizeOnContentsReady
Type: boolean
When enabled, automatically calls resize when images/videos inside Flicking panels are loaded. This is useful when Flicking contains content that changes size before and after loading.
Default: false
See Also:
threshold
Type: number
Movement threshold to change panels (unit: px). Panels will only change after scrolling beyond this value.
Default: 40
See Also:
useCSSOrder
Type: boolean
Using useCSSOrder does not change the DOM order, but the order CSS property changes the order on the screen.
Default: false
Remarks: When circular is used, the DOM order changes depending on the position. When using iframe, you can prevent reloading when the DOM order changes. In svelte, CSS order is always used.
See Also:
useFractionalSize
Type: boolean
By enabling this, Flicking will calculate all internal size with CSS width computed with getComputedStyle.
Default: false
Remarks: 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.
See Also:
usePercentagePos
Type: boolean
Whether to apply the camera element's transform position as a percentage value (%) instead of px.
Default: false
Remarks: The percentage value is calculated relative to the viewport size. When enabled, the camera element keeps its relative position even if the viewport size changes before resize() is applied. This can prevent a temporary panel position mismatch when Flicking is resized with a responsive(%-based) layout.
See Also:
useResizeObserver
Type: boolean
Whether to listen ResizeObserver's event instead of Window's resize event when using the autoResize option
Default: true
See Also:
virtual
Type: VirtualOptions | null
When enabled, restricts the number of panel elements to panelsPerView + 1 to reduce memory usage.
Default: null
Dependencies:
- Requires: Must be used with panelsPerView. When panelsPerView is -1 (auto), this option is ignored.
Example:
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);
See Also: