@egjs/flicking
Version:
Everyday 30 million people experience. It's reliable, flexible and extendable carousel.
1,180 lines • 52.4 kB
TypeScript
import Component from "@egjs/component";
import { Camera } from "./camera";
import { ALIGN, CIRCULAR_FALLBACK, DIRECTION, MOVE_TYPE } from "./constants/values";
import { Control } from "./control";
import AutoResizer from "./core/AutoResizer";
import { Panel } from "./core/panel";
import Viewport from "./core/Viewport";
import VirtualManager, { VirtualOptions } from "./core/VirtualManager";
import { FlickingEvents } from "./event/types";
import { ExternalRenderer, Renderer, RendererOptions } from "./renderer";
import { ElementLike, MoveTypeOptions, Plugin, Status } from "./types/external";
import { LiteralUnion, ValueOf } from "./types/internal";
/**
* Options for the Flicking component
* @public
*/
export interface FlickingOptions {
/**
* Align position of the panels within viewport. You can set different values each for the panel and camera.
* @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 `panel` and `camera` alignment values
*
* @example
* ```ts
* 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 });
* });
* ```
* @accepts {@link ALIGN}
* @defaultValue "center"
* @see {@link https://naver.github.io/egjs-flicking/docs/demos/basic/alignment | Demo: Alignment}
*/
align: LiteralUnion<ValueOf<typeof ALIGN>> | number | {
panel: number | string;
camera: number | string;
};
/**
* Index of the panel to move when Flicking's {@link Flicking.init | init()} is called. A zero-based integer.
* @defaultValue 0
* @see {@link https://naver.github.io/egjs-flicking/docs/demos/basic/default-index | Demo: Default Index}
*/
defaultIndex: number;
/**
* Direction of panel movement. `true` for horizontal, `false` for vertical.
*
* @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
* ```ts
* // 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
* });
* ```
*
* @defaultValue true
* @see {@link https://naver.github.io/egjs-flicking/docs/demos/basic/vertical | Demo: Vertical}
*/
horizontal: boolean;
/**
* Enables circular (continuous loop) mode, which connects first/last panel for continuous scrolling.
* @dependency Mutual Exclusive - {@link FlickingOptions.bound | bound}. When both are true, circular takes precedence and bound will be ignored.
* @dependency Conditional - Total panel size must be ≥ viewport size. If not met, automatically falls back to {@link FlickingOptions.circularFallback | circularFallback} mode.
* @dependency Related - {@link FlickingOptions.circularFallback | circularFallback} determines fallback behavior when circular cannot be enabled
*
* @defaultValue false
* @see {@link https://naver.github.io/egjs-flicking/docs/demos/basic/circular | Demo: Circular}
*/
circular: boolean;
/**
* Set panel control mode for the case when circular cannot be enabled.
* @dependency Requires - Only takes effect when {@link FlickingOptions.circular | circular} is true but activation requirements are not met (total panel size < viewport size)
*
* @remarks
* - "linear": The view's range is set from the top of the first panel to the top of the last panel.
* - "bound": Prevents the view from going out of the first/last panel, hiding empty spaces.
*
* @accepts {@link CIRCULAR_FALLBACK}
* @defaultValue "linear"
*
* @since 4.5.0
* @see {@link https://naver.github.io/egjs-flicking/docs/demos/basic/circular | Demo: Circular}
*/
circularFallback: LiteralUnion<ValueOf<typeof CIRCULAR_FALLBACK>>;
/**
* Prevent the view (camera element) from going out of the first/last panel.
* @dependency Mutual Exclusive - {@link FlickingOptions.circular | circular}. When circular is true, this option is ignored.
* @dependency Related - Works with {@link FlickingOptions.bounce | bounce} for bounce effect at boundaries
*
* @defaultValue false
* @see {@link https://naver.github.io/egjs-flicking/docs/demos/basic/bound | Demo: Bound}
*/
bound: boolean;
/**
* Update height of the viewport element after movement same to the height of the panel below.
* @dependency Conditional - Only works when {@link FlickingOptions.horizontal | horizontal} is true. When horizontal is false, this option has no effect.
*
* @defaultValue false
* @see {@link https://naver.github.io/egjs-flicking/docs/demos/basic/adaptive | Demo: Adaptive}
*/
adaptive: boolean;
/**
* A visible number of panels on viewport. Enabling this option will force the panel to resize.
* @remarks
* When set to -1, automatically calculates based on panel sizes.
*
* @dependency Related - Affects how {@link FlickingOptions.align | align} calculates panel positions
* @dependency Requires - Required for {@link FlickingOptions.virtual | virtual} to work (must be > 0)
* @dependency Related - Works with {@link FlickingOptions.noPanelStyleOverride | noPanelStyleOverride} to prevent style modifications
*
* @defaultValue -1
*
* @since 4.2.0
* @see {@link https://naver.github.io/egjs-flicking/docs/demos/basic/panels-per-view | Demo: Panels Per View}
*/
panelsPerView: number;
/**
* When enabled, prevents modifying the panel's `width/height` styles when {@link Flicking.panelsPerView | panelsPerView} is enabled.
* Enabling this option can improve performance if you are manually managing all panel sizes.
* @defaultValue false
* @see {@link https://naver.github.io/egjs-flicking/docs/demos/basic/panels-per-view | Demo: Panels Per View}
*/
noPanelStyleOverride: boolean;
/**
* When enabled, automatically calls {@link Flicking.resize} when images/videos inside Flicking panels are loaded.
* This is useful when Flicking contains content that changes size before and after loading.
* @defaultValue false
* @since 4.3.0
* @see {@link https://naver.github.io/egjs-flicking/docs/demos/advanced/resize-on-contents-ready | Demo: Resize On Contents Ready}
*/
resizeOnContentsReady: boolean;
/**
* Enable nested Flicking mode to allow parent Flicking to move when reaching boundaries.
* @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.
*
* @defaultValue false
*
* @since 4.7.0
* @see {@link https://naver.github.io/egjs-flicking/docs/demos/basic/nested | Demo: Nested}
*/
nested: boolean;
/**
* A threshold from the viewport edge to trigger the `needPanel` event.
* @defaultValue 0
* @see {@link https://naver.github.io/egjs-flicking/docs/demos/advanced/infinite-scroll | Demo: Infinite Scroll}
*/
needPanelThreshold: number;
/**
* When enabled, disables events before the `ready` event during initialization.
* @defaultValue true
* @since 4.2.0
* @see {@link https://naver.github.io/egjs-flicking/docs/demos/basic/auto-init | Demo: Auto Init}
*/
preventEventsBeforeInit: boolean;
/**
* Deceleration of panel movement animation with momentum applied by user interaction (input).
* Higher values result in a shorter animation duration.
* @defaultValue 0.0075
* @see {@link https://naver.github.io/egjs-flicking/docs/demos/basic/deceleration | Demo: Deceleration}
*/
deceleration: number;
/**
* Default duration of the animation in milliseconds.
* @defaultValue 500
* @see {@link https://naver.github.io/egjs-flicking/docs/demos/basic/duration | Demo: Duration}
*/
duration: number;
/**
* An easing function applied to the panel movement animation.
* @defaultValue "easeOutCubic" (x => 1 - Math.pow(1 - x, 3))
* @see {@link http://easings.net/ | Easing Functions Cheat Sheet}
* @see {@link https://naver.github.io/egjs-flicking/docs/demos/basic/easing | Demo: Easing}
*/
easing: (x: number) => number;
/**
* Types of input devices to enable.
* @defaultValue ["touch", "mouse"]
* @see {@link https://naver.github.io/egjs-flicking/docs/demos/basic/input-type | Demo: Input Type}
*/
inputType: string[];
/**
* Movement style by user input. Determines the instance type of {@link Flicking.control | control}.
* @remarks
* - "snap": Uses {@link SnapControl}
*
* - "freeScroll": Uses {@link FreeControl} with {@link FreeControlOptions}
*
* - "strict": Uses {@link StrictControl} with {@link StrictControlOptions}
* @accepts {@link MOVE_TYPE}
* @example
* ```ts
* import Flicking, { MOVE_TYPE } from "@egjs/flicking";
*
* const flicking = new Flicking({
* moveType: MOVE_TYPE.SNAP
* });
* ```
*
* ```ts
* 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 }]
* });
* ```
* @defaultValue "snap"
* @see {@link https://naver.github.io/egjs-flicking/docs/demos/basic/movement-types | Demo: Movement Types}
*/
moveType: ValueOf<typeof MOVE_TYPE> | MoveTypeOptions<ValueOf<typeof MOVE_TYPE>>;
/**
* Movement threshold to change panels (unit: px). Panels will only change after scrolling beyond this value.
* @defaultValue 40
* @see {@link https://naver.github.io/egjs-flicking/docs/demos/basic/threshold | Demo: Threshold}
*/
threshold: number;
/**
* Minimum distance to recognize user input (unit: px). Panels will only move after scrolling beyond this value.
* @defaultValue 1
* @see {@link https://naver.github.io/egjs-flicking/docs/demos/basic/threshold | Demo: Threshold}
*/
dragThreshold: number;
/**
* The minimum distance for animation to proceed.
* @remarks
* If the distance to be moved is less than `animationThreshold`, the movement proceeds immediately without animation (duration: 0).
* @defaultValue 0.5
* @since 4.15.0
* @see {@link https://naver.github.io/egjs-flicking/docs/demos/advanced/animation-threshold | Demo: Animation Threshold}
*/
animationThreshold: number;
/**
* Using `useCSSOrder` does not change the DOM order, but the `order` CSS property changes the order on the screen.
* @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.
* @defaultValue false
* @since 4.15.0
* @see {@link https://naver.github.io/egjs-flicking/docs/demos/advanced/use-css-order | Demo: CSS Order}
*/
useCSSOrder: boolean;
/**
* Allows stopping animations with user click/touch input.
* @defaultValue true
* @see {@link https://naver.github.io/egjs-flicking/docs/demos/basic/interruptable | Demo: Interruptable}
*/
interruptable: boolean;
/**
* The size value of the bounce area.
* @dependency Conditional - Only can be enabled when {@link FlickingOptions.circular | circular} is false
* @dependency Related - Works with {@link FlickingOptions.bound | bound} to provide bounce effect at panel boundaries
*
* @remarks
* You can set different bounce value for prev/next direction by using array.
* Use `number` for px value, and `string` for px or % value relative to viewport size.
* You have to call {@link Control.updateInput | updateInput()} after changing this value to take effect.
*
* @example
* ```ts
* const possibleOptions = [
* "0%", "25%", "42%", // % values
* "0px", "100px", "50% - 25px", // px values with arithmetic
* 0, 100, 1000 // numbers (same as px)
* ];
* ```
*
* @defaultValue "20%"
* @see {@link https://naver.github.io/egjs-flicking/docs/demos/basic/bound | Demo: Bound}
*/
bounce: number | string | [number | string, number | string];
/**
* Size of the area from the right edge in iOS Safari (in px) that enables swipe-back or swipe-forward.
* @defaultValue 30
* @see {@link https://naver.github.io/egjs-flicking/docs/demos/basic/input-type | Demo: Input Type}
*/
iOSEdgeSwipeThreshold: number;
/**
* Automatically cancels {@link https://developer.mozilla.org/ko/docs/Web/API/Element/click_event | click} events when the user drags the viewport by any amount.
* @defaultValue true
* @see {@link https://naver.github.io/egjs-flicking/docs/demos/basic/prevent-click | Demo: Prevent Click}
*/
preventClickOnDrag: boolean;
/**
* Whether to use the {@link https://developer.mozilla.org/ko/docs/Web/API/Event/preventDefault | preventDefault} when the user starts dragging
* @defaultValue false
* @since 4.11.0
* @see {@link https://naver.github.io/egjs-flicking/docs/demos/basic/prevent-click | Demo: Prevent Click}
*/
preventDefaultOnDrag: boolean;
/**
* Automatically call {@link Flicking.disableInput | disableInput()} during initialization.
* @defaultValue false
* @see {@link https://naver.github.io/egjs-flicking/docs/demos/basic/disable-input | Demo: Disable Input}
*/
disableOnInit: boolean;
/**
* Change active panel index on mouse/touch hold while animating.
* @remarks
* `index` of the `willChange`/`willRestore` event will be used as new index.
* @defaultValue false
* @since 4.8.0
* @see {@link https://naver.github.io/egjs-flicking/docs/demos/basic/interruptable | Demo: Interruptable}
*/
changeOnHold: boolean;
/**
* When enabled, only renders visible panels. Can significantly improve performance with many panels.
* @defaultValue false
* @see {@link https://naver.github.io/egjs-flicking/docs/demos/advanced/render-only-visible | Demo: Render Only Visible}
*/
renderOnlyVisible: boolean;
/**
* When enabled, restricts the number of panel elements to `panelsPerView + 1` to reduce memory usage.
* @dependency Requires - Must be used with {@link FlickingOptions.panelsPerView | panelsPerView}. When panelsPerView is -1 (auto), this option is ignored.
*
* @remarks
* After Flicking initialization, this property can be used to add or remove the number of rendered panels.
*
* The option object contains:
* - `renderPanel`: A rendering function for the panel element's innerHTML
* - `initialPanelCount`: Initial panel count to render
* - `cache` (optional, default: false): Whether to cache rendered panel's innerHTML
* - `panelClass` (optional, default: "flicking-panel"): The class name for rendered panel elements
*
* @example
* ```ts
* 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);
* ```
*
* @defaultValue null
*
* @since 4.4.0
* @see {@link https://naver.github.io/egjs-flicking/docs/demos/advanced/virtual-scroll | Demo: Virtual Scroll}
*/
virtual: VirtualOptions | null;
/**
* Call {@link Flicking.init | init()} automatically when creating Flicking's instance.
* @defaultValue true
* @readonly
* @see {@link https://naver.github.io/egjs-flicking/docs/demos/basic/auto-init | Demo: Auto Init}
*/
autoInit: boolean;
/**
* Whether to automatically call {@link Flicking.resize | resize()} when the viewport element (.flicking-viewport) size is changed.
* @defaultValue true
* @see {@link https://naver.github.io/egjs-flicking/docs/demos/advanced/auto-resize | Demo: Auto Resize}
*/
autoResize: boolean;
/**
* Whether to listen {@link https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver | ResizeObserver}'s event instead of Window's {@link https://developer.mozilla.org/ko/docs/Web/API/Window/resize_event | resize} event when using the `autoResize` option
* @defaultValue true
* @since 4.4.0
* @see {@link https://naver.github.io/egjs-flicking/docs/demos/advanced/auto-resize | Demo: Auto Resize}
*/
useResizeObserver: boolean;
/**
* Delays size recalculation from `autoResize` by the given time in milliseconds.
* @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.
* @defaultValue 0
* @since 4.6.0
* @see {@link https://naver.github.io/egjs-flicking/docs/demos/advanced/resize-debounce | Demo: Resize Debounce}
*/
resizeDebounce: number;
/**
* Whether to use ResizeObserver to observe the size of the panel element.
* @dependency Conditional - Only available when {@link FlickingOptions.useResizeObserver | useResizeObserver} is enabled
*
* @remarks
* This option guarantees that the resize event is triggered when the size of the panel element is changed.
*
* @since 4.13.1
* @defaultValue false
* @see {@link https://naver.github.io/egjs-flicking/docs/demos/advanced/observe-panel-resize | Demo: Observe Panel Resize}
*/
observePanelResize: boolean;
/**
* The maximum time for size recalculation delay when using `resizeDebounce`, in milliseconds.
* @remarks
* This guarantees that size recalculation is performed at least once every (n)ms.
* @defaultValue 100
* @since 4.6.0
* @see {@link https://naver.github.io/egjs-flicking/docs/demos/advanced/resize-debounce | Demo: Resize Debounce}
*/
maxResizeDebounce: number;
/**
* By enabling this, Flicking will calculate all internal size with CSS width computed with getComputedStyle.
* @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 {@link https://developer.mozilla.org/en-US/docs/Web/CSS/transform | transform} is applied on the element.
* @defaultValue false
* @since 4.9.0
* @see {@link https://naver.github.io/egjs-flicking/docs/demos/advanced/fractional-size | Demo: Fractional Size}
*/
useFractionalSize: boolean;
/**
* This is an option for the frameworks (React, Vue, Angular, ...).
* Don't set it as it's automatically managed by Flicking.
* @defaultValue null
* @internal
* @readonly
*/
externalRenderer: ExternalRenderer | null;
/**
* This option works only when autoResize is set to true.
* @internal
* @defaultValue false
*/
optimizeSizeUpdate: boolean;
/**
* @deprecated Use {@link FlickingOptions.externalRenderer | externalRenderer} instead
*/
renderExternal: {
renderer: new (options: RendererOptions) => ExternalRenderer;
rendererOptions: RendererOptions;
} | null;
}
/**
* Parameters for {@link Flicking.getStatus}
* @public
*/
export interface GetStatusParams {
/**
* Include current panel index
* @defaultValue true
*/
index?: boolean;
/**
* Include camera position. Only works when {@link FlickingOptions.moveType | moveType} is `freeScroll`
* @defaultValue true
*/
position?: boolean;
/**
* Include panel's `outerHTML`
* @defaultValue false
*/
includePanelHTML?: boolean;
/**
* Include only visible panels' HTML. Only available when `includePanelHTML` is `true`
* @defaultValue false
*/
visiblePanelsOnly?: boolean;
}
declare class Flicking extends Component<FlickingEvents> {
/**
* Version info string
* @example
* ```ts
* Flicking.VERSION; // ex) 4.0.0
* ```
*/
static readonly VERSION: string;
private _viewport;
private _autoResizer;
private _camera;
private _control;
private _renderer;
private _virtualManager;
private _align;
private _defaultIndex;
private _horizontal;
private _circular;
private _circularFallback;
private _bound;
private _adaptive;
private _panelsPerView;
private _noPanelStyleOverride;
private _resizeOnContentsReady;
private _virtual;
private _nested;
private _needPanelThreshold;
private _preventEventsBeforeInit;
private _deceleration;
private _duration;
private _easing;
private _inputType;
private _moveType;
private _threshold;
private _dragThreshold;
private _animationThreshold;
private _useCSSOrder;
private _interruptable;
private _bounce;
private _iOSEdgeSwipeThreshold;
private _preventClickOnDrag;
private _preventDefaultOnDrag;
private _disableOnInit;
private _changeOnHold;
private _renderOnlyVisible;
private _autoInit;
private _autoResize;
private _useResizeObserver;
private _resizeDebounce;
private _observePanelResize;
private _maxResizeDebounce;
private _useFractionalSize;
private _externalRenderer;
private _renderExternal;
private _optimizeSizeUpdate;
private _initialized;
private _plugins;
private _isResizing;
private _scheduleResize;
/**
* {@link Control} instance that manages user input and panel movement animations
* @remarks
* The concrete Control implementation is selected based on {@link FlickingOptions.moveType | moveType} option.
* @privateRemarks
* The control instance is created during construction by {@link Flicking._createControl}.
* @readonly
*/
get control(): Control;
/**
* {@link Camera} instance that manages actual movement and positioning inside the viewport
* @remarks
* The concrete Camera implementation is selected based on {@link FlickingOptions.circular} and {@link FlickingOptions.bound} options.
* @privateRemarks
* The camera instance is created during construction by {@link Flicking._createCamera}.
* @readonly
*/
get camera(): Camera;
/**
* {@link Renderer} instance that manages panels and their elements
* @remarks
* The concrete Renderer implementation is selected based on {@link Flicking.externalRenderer} and {@link FlickingOptions.virtual} options.
* @privateRemarks
* The renderer instance is created during construction by {@link Flicking._createRenderer}.
* @readonly
*/
get renderer(): Renderer;
/**
* {@link Viewport} instance that manages viewport size and element
* @privateRemarks
* The viewport instance is created during construction by {@link Flicking} constructor.
* @readonly
*/
get viewport(): Viewport;
/**
* {@link AutoResizer} instance that detects size changes and triggers resize when {@link FlickingOptions.autoResize | autoResize} option is enabled
* @privateRemarks
* The autoResizer instance is created during construction by {@link Flicking} constructor.
* @readonly
*/
get autoResizer(): AutoResizer;
/**
* Whether Flicking's {@link Flicking.init} is called.
* @remarks
* This is `true` when {@link Flicking.init} is called, and is `false` after calling {@link Flicking.destroy}.
* Use this to check if Flicking is ready before calling certain methods that require initialization.
* @defaultValue false
* @readonly
* @example
* ```ts
* if (flicking.initialized) {
* flicking.setStatus(status);
* } else {
* await flicking.init();
* flicking.setStatus(status);
* }
* ```
*/
get initialized(): boolean;
/**
* Whether the circular mode is actually enabled.
* @remarks
* The {@link FlickingOptions.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 {@link FlickingOptions.circular} option value.
* @defaultValue false
* @readonly
*/
get circularEnabled(): boolean;
/**
* Whether the virtual mode is actually enabled.
* @remarks
* The {@link FlickingOptions.virtual} option may not be enabled when {@link FlickingOptions.panelsPerView} is less than or equal to zero.
* This property reflects the actual enabled state, which may differ from the {@link FlickingOptions.virtual} option value.
* @defaultValue false
* @readonly
*/
get virtualEnabled(): boolean;
/**
* Index of the currently active panel.
* @remarks
* Returns -1 when there is no active panel. This is a shorthand for `Flicking.currentPanel.index`.
* @readonly
*/
get index(): number;
/**
* The root viewport element (`.flicking-viewport`).
* @remarks
* This is the element passed to the Flicking constructor. It is a shorthand for `Flicking.viewport.element`.
* @readonly
*/
get element(): HTMLElement;
/**
* The currently active panel.
* @remarks
* Returns `null` when there is no active panel. This is a shorthand for `Flicking.control.activePanel`.
* @readonly
*/
get currentPanel(): Panel | null;
/**
* Array of all panels.
* @remarks
* This is a shorthand for `Flicking.renderer.panels`.
* @readonly
*/
get panels(): Panel[];
/**
* Total number of panels.
* @remarks
* This is a shorthand for `Flicking.renderer.panelCount`.
* @readonly
*/
get panelCount(): number;
/**
* Array of panels that are currently visible in the viewport.
* @remarks
* This is a shorthand for `Flicking.camera.visiblePanels`.
* @readonly
*/
get visiblePanels(): Panel[];
/**
* Whether Flicking is currently animating.
* @remarks
* This is a shorthand for `Flicking.control.animating`.
* @readonly
*/
get animating(): boolean;
/**
* Whether the user is currently clicking or touching the viewport.
* @remarks
* This is a shorthand for `Flicking.control.holding`.
* @readonly
*/
get holding(): boolean;
/**
* Array of currently activated plugins.
* @remarks
* Plugins are added via {@link Flicking.addPlugins} and removed via {@link Flicking.removePlugins}.
* @readonly
*/
get activePlugins(): Plugin[];
/** Current value of the {@link FlickingOptions.align | align} option. */
get align(): FlickingOptions["align"];
/** Current value of the {@link FlickingOptions.defaultIndex | defaultIndex} option. */
get defaultIndex(): FlickingOptions["defaultIndex"];
/** Current value of the {@link FlickingOptions.horizontal | horizontal} option. */
get horizontal(): FlickingOptions["horizontal"];
/** Current value of the {@link FlickingOptions.circular | circular} option. */
get circular(): FlickingOptions["circular"];
/**
* Current value of the {@link FlickingOptions.circularFallback | circularFallback} option.
* @since 4.5.0
*/
get circularFallback(): FlickingOptions["circularFallback"];
/** Current value of the {@link FlickingOptions.bound | bound} option. */
get bound(): FlickingOptions["bound"];
/** Current value of the {@link FlickingOptions.adaptive | adaptive} option. */
get adaptive(): FlickingOptions["adaptive"];
/**
* Current value of the {@link FlickingOptions.panelsPerView | panelsPerView} option.
* @since 4.2.0
*/
get panelsPerView(): FlickingOptions["panelsPerView"];
/** Current value of the {@link FlickingOptions.noPanelStyleOverride | noPanelStyleOverride} option. */
get noPanelStyleOverride(): FlickingOptions["noPanelStyleOverride"];
/**
* Current value of the {@link FlickingOptions.resizeOnContentsReady | resizeOnContentsReady} option.
* @since 4.3.0
*/
get resizeOnContentsReady(): FlickingOptions["resizeOnContentsReady"];
/**
* Current value of the {@link FlickingOptions.nested | nested} option.
* @since 4.7.0
*/
get nested(): FlickingOptions["nested"];
/** Current value of the {@link FlickingOptions.needPanelThreshold | needPanelThreshold} option. */
get needPanelThreshold(): FlickingOptions["needPanelThreshold"];
/**
* Current value of the {@link FlickingOptions.preventEventsBeforeInit | preventEventsBeforeInit} option.
* @since 4.2.0
*/
get preventEventsBeforeInit(): FlickingOptions["preventEventsBeforeInit"];
/** Current value of the {@link FlickingOptions.deceleration | deceleration} option. */
get deceleration(): FlickingOptions["deceleration"];
/** Current value of the {@link FlickingOptions.easing | easing} option. */
get easing(): FlickingOptions["easing"];
/** Current value of the {@link FlickingOptions.duration | duration} option. */
get duration(): FlickingOptions["duration"];
/** Current value of the {@link FlickingOptions.inputType | inputType} option. */
get inputType(): FlickingOptions["inputType"];
/** Current value of the {@link FlickingOptions.moveType | moveType} option. */
get moveType(): FlickingOptions["moveType"];
/** Current value of the {@link FlickingOptions.threshold | threshold} option. */
get threshold(): FlickingOptions["threshold"];
/** Current value of the {@link FlickingOptions.dragThreshold | dragThreshold} option. */
get dragThreshold(): FlickingOptions["dragThreshold"];
/**
* Current value of the {@link FlickingOptions.animationThreshold | animationThreshold} option.
* @since 4.15.0
*/
get animationThreshold(): FlickingOptions["animationThreshold"];
/**
* Current value of the {@link FlickingOptions.useCSSOrder | useCSSOrder} option.
* @since 4.15.0
*/
get useCSSOrder(): FlickingOptions["useCSSOrder"];
/** Current value of the {@link FlickingOptions.interruptable | interruptable} option. */
get interruptable(): FlickingOptions["interruptable"];
/** Current value of the {@link FlickingOptions.bounce | bounce} option. */
get bounce(): FlickingOptions["bounce"];
/** Current value of the {@link FlickingOptions.iOSEdgeSwipeThreshold | iOSEdgeSwipeThreshold} option. */
get iOSEdgeSwipeThreshold(): FlickingOptions["iOSEdgeSwipeThreshold"];
/** Current value of the {@link FlickingOptions.preventClickOnDrag | preventClickOnDrag} option. */
get preventClickOnDrag(): FlickingOptions["preventClickOnDrag"];
/**
* Current value of the {@link FlickingOptions.preventDefaultOnDrag | preventDefaultOnDrag} option.
* @since 4.11.0
*/
get preventDefaultOnDrag(): FlickingOptions["preventDefaultOnDrag"];
/** Current value of the {@link FlickingOptions.disableOnInit | disableOnInit} option. */
get disableOnInit(): FlickingOptions["disableOnInit"];
/**
* Current value of the {@link FlickingOptions.changeOnHold | changeOnHold} option.
* @since 4.8.0
*/
get changeOnHold(): FlickingOptions["changeOnHold"];
/** Current value of the {@link FlickingOptions.renderOnlyVisible | renderOnlyVisible} option. */
get renderOnlyVisible(): FlickingOptions["renderOnlyVisible"];
/**
* {@link VirtualManager} instance that manages virtual panels
* @privateRemarks
* The virtualManager instance is created during construction by {@link Flicking} constructor.
* @readonly
*/
get virtual(): VirtualManager;
/** Current value of the {@link FlickingOptions.autoInit | autoInit} option. */
get autoInit(): FlickingOptions["autoInit"];
/** Current value of the {@link FlickingOptions.autoResize | autoResize} option. */
get autoResize(): FlickingOptions["autoResize"];
/**
* Current value of the {@link FlickingOptions.useResizeObserver | useResizeObserver} option.
* @since 4.4.0
*/
get useResizeObserver(): FlickingOptions["useResizeObserver"];
/**
* Current value of the {@link FlickingOptions.observePanelResize | observePanelResize} option.
* @since 4.13.1
*/
get observePanelResize(): FlickingOptions["observePanelResize"];
/**
* Current value of the {@link FlickingOptions.resizeDebounce | resizeDebounce} option.
* @since 4.6.0
*/
get resizeDebounce(): FlickingOptions["resizeDebounce"];
/**
* Current value of the {@link FlickingOptions.maxResizeDebounce | maxResizeDebounce} option.
* @since 4.6.0
*/
get maxResizeDebounce(): FlickingOptions["maxResizeDebounce"];
/**
* Current value of the {@link FlickingOptions.useFractionalSize | useFractionalSize} option.
* @since 4.9.0
*/
get useFractionalSize(): FlickingOptions["useFractionalSize"];
/** Current value of the {@link FlickingOptions.externalRenderer | externalRenderer} option. */
get externalRenderer(): FlickingOptions["externalRenderer"];
/**
* @deprecated Use {@link Flicking.externalRenderer | externalRenderer} instead.
* Current value of the {@link FlickingOptions.renderExternal | renderExternal} option.
*/
get renderExternal(): FlickingOptions["renderExternal"];
/** @internal */
get optimizeSizeUpdate(): FlickingOptions["optimizeSizeUpdate"];
/**
* Sets {@link FlickingOptions.align}.
* @privateRemarks
* Setting this value updates the renderer and camera alignment, and triggers a resize operation.
*/
set align(val: FlickingOptions["align"]);
set defaultIndex(val: FlickingOptions["defaultIndex"]);
/**
* Sets {@link FlickingOptions.horizontal}.
* @privateRemarks
* Setting this value updates the control direction and triggers a resize operation.
*/
set horizontal(val: FlickingOptions["horizontal"]);
/**
* Sets {@link FlickingOptions.circular}.
* @privateRemarks
* Setting this value triggers a resize operation to recalculate panel positions.
*/
set circular(val: FlickingOptions["circular"]);
/**
* Sets {@link FlickingOptions.bound}.
* @privateRemarks
* Setting this value triggers a resize operation to recalculate panel positions.
*/
set bound(val: FlickingOptions["bound"]);
/**
* Sets {@link FlickingOptions.adaptive}.
* @privateRemarks
* Setting this value triggers a resize operation to recalculate panel sizes.
*/
set adaptive(val: FlickingOptions["adaptive"]);
/**
* Sets {@link FlickingOptions.panelsPerView}.
* @privateRemarks
* Setting this value triggers a resize operation to recalculate panel sizes.
*/
set panelsPerView(val: FlickingOptions["panelsPerView"]);
/**
* Sets {@link FlickingOptions.noPanelStyleOverride}.
* @privateRemarks
* Setting this value triggers a resize operation to update panel styles.
*/
set noPanelStyleOverride(val: FlickingOptions["noPanelStyleOverride"]);
/**
* Sets {@link FlickingOptions.resizeOnContentsReady}.
* @privateRemarks
* When set to `true`, immediately checks all panels for content readiness.
*/
set resizeOnContentsReady(val: FlickingOptions["resizeOnContentsReady"]);
/**
* Sets {@link FlickingOptions.nested}.
* @privateRemarks
* Setting this value updates the control's axes options.
*/
set nested(val: FlickingOptions["nested"]);
set needPanelThreshold(val: FlickingOptions["needPanelThreshold"]);
set preventEventsBeforeInit(val: FlickingOptions["preventEventsBeforeInit"]);
/**
* Sets {@link FlickingOptions.deceleration}.
* @privateRemarks
* Setting this value updates the control's axes deceleration option.
*/
set deceleration(val: FlickingOptions["deceleration"]);
/**
* Sets {@link FlickingOptions.easing}.
* @privateRemarks
* Setting this value updates the control's axes easing option.
*/
set easing(val: FlickingOptions["easing"]);
set duration(val: FlickingOptions["duration"]);
/**
* Sets {@link FlickingOptions.inputType}.
* @privateRemarks
* Setting this value updates the control's pan input options.
*/
set inputType(val: FlickingOptions["inputType"]);
/**
* Sets {@link FlickingOptions.moveType}.
* @privateRemarks
* Setting this value creates a new Control instance based on the moveType and preserves the current panel position and progress.
*/
set moveType(val: FlickingOptions["moveType"]);
set threshold(val: FlickingOptions["threshold"]);
/**
* Sets {@link FlickingOptions.dragThreshold}.
* @privateRemarks
* Setting this value updates the control's pan input threshold option.
*/
set dragThreshold(val: FlickingOptions["dragThreshold"]);
/**
* Sets {@link FlickingOptions.animationThreshold}.
*/
set animationThreshold(val: FlickingOptions["animationThreshold"]);
/**
* Sets {@link FlickingOptions.useCSSOrder}.
*/
set useCSSOrder(val: FlickingOptions["useCSSOrder"]);
/**
* Sets {@link FlickingOptions.interruptable}.
* @privateRemarks
* Setting this value updates the control's axes interruptable option.
*/
set interruptable(val: FlickingOptions["interruptable"]);
/**
* Sets {@link FlickingOptions.bounce}.
* @privateRemarks
* Setting this value updates the control input configuration.
*/
set bounce(val: FlickingOptions["bounce"]);
/**
* Sets {@link FlickingOptions.iOSEdgeSwipeThreshold}.
* @privateRemarks
* Setting this value updates the control's pan input iOS edge swipe threshold option.
*/
set iOSEdgeSwipeThreshold(val: FlickingOptions["iOSEdgeSwipeThreshold"]);
/**
* Sets {@link FlickingOptions.preventClickOnDrag}.
* @privateRemarks
* Setting this value adds or removes the prevent click handler from the control.
*/
set preventClickOnDrag(val: FlickingOptions["preventClickOnDrag"]);
/**
* Sets {@link FlickingOptions.preventDefaultOnDrag}.
* @privateRemarks
* Setting this value updates the control's pan input preventDefaultOnDrag option.
*/
set preventDefaultOnDrag(val: FlickingOptions["preventDefaultOnDrag"]);
set disableOnInit(val: FlickingOptions["disableOnInit"]);
set changeOnHold(val: FlickingOptions["changeOnHold"]);
/**
* Sets {@link FlickingOptions.renderOnlyVisible}.
* @privateRemarks
* Setting this value triggers an immediate render operation.
*/
set renderOnlyVisible(val: FlickingOptions["renderOnlyVisible"]);
/**
* Sets {@link FlickingOptions.autoResize}.
* @privateRemarks
* Setting this value enables or disables the auto resizer if Flicking is already initialized.
*/
set autoResize(val: FlickingOptions["autoResize"]);
/**
* Sets {@link FlickingOptions.useResizeObserver}.
* @privateRemarks
* Setting this value re-enables the auto resizer if Flicking is initialized and autoResize is enabled.
*/
set useResizeObserver(val: FlickingOptions["useResizeObserver"]);
/**
* Sets {@link FlickingOptions.observePanelResize}.
* @privateRemarks
* Setting this value starts or stops observing panel sizes if Flicking is initialized and autoResize is enabled.
*/
set observePanelResize(val: FlickingOptions["observePanelResize"]);
set optimizeSizeUpdate(val: FlickingOptions["optimizeSizeUpdate"]);
/** Creates a new Flicking instance
* @param root - A root HTMLElement to initialize Flicking on it. When it's a typeof `string`, it should be a css selector string
* @param options - A {@link FlickingOptions} object
* @throws {@link InitializationErrors}
* @example
* ```ts
* 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 });
* ```
*/
constructor(root: HTMLElement | string, options?: Partial<FlickingOptions>);
/**
* Initialize Flicking and move to the default index.
* @remarks
* This method is automatically called in the constructor when {@link FlickingOptions.autoInit | autoInit} is `true` (default).
* If Flicking is already initialized, this method returns immediately without doing anything.
* @fires {@link ReadyEvent}
* @returns Promise that resolves when initialization is complete
*/
init(): Promise<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, {@link Flicking.initialized} will be `false` and the instance should not be used.
*/
destroy(): void;
/**
* Move to the previous panel (current index - 1).
* @param duration - Duration of the panel movement animation (unit: ms). Defaults to {@link FlickingOptions.duration}
* @fires {@link MovementEvents}
* @throws {@link MovementErrors}
* @returns Promise that resolves after reaching the previous panel
*/
prev(duration?: number): Promise<void>;
/**
* Move to the next panel (current index + 1).
* @param duration - Duration of the panel movement animation (unit: ms). Defaults to {@link FlickingOptions.duration}
* @fires {@link MovementEvents}
* @throws {@link MovementErrors}
* @returns Promise that resolves after reaching the next panel
*/
next(duration?: number): Promise<void>;
/**
* Move to the panel with the given index.
* @param index - The index of the panel to move to
* @param duration - Duration of the animation (unit: ms). Defaults to {@link FlickingOptions.duration}
* @param direction - Direction to move (circular mode only). Defaults to {@link DIRECTION.NONE}
* @fires {@link MovementEvents}
* @throws {@link MovementErrors}
* @returns Promise that resolves after reaching the target panel
*/
moveTo(index: number, duration?: number, direction?: ValueOf<typeof DIRECTION>): Promise<void>;
/**
* Change the destination and duration of the animation currently playing.
* @remarks
* This method does nothing if no animation is currently playing.
* @param index - The index of the panel to move to
* @param duration - Duration of the animation (unit: ms)
* @param direction - Direction to move. Only available when {@link FlickingOptions.circular} is enabled
* @since 4.10.0
* @throws {@link AnimationUpdateErrors}
*/
updateAnimation(index: number, duration?: number, direction?: ValueOf<typeof DIRECTION>): void;
/**
* Stop the animation currently playing.
* @remarks
* This method does nothing if no animation is currently playing.
* @since 4.10.0
* @fires {@link MoveEndEvent}
*/
stopAnimation(): void;
/**
* Get the panel at the given index.
* @param index - 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)`.
* @example
* ```ts
* const panel = flicking.getPanel(0);
* // Which is a shorthand to...
* const samePanel = flicking.panels[0];
* ```
*/
getPanel(index: number): Panel | null;
/**
* Enable user input (mouse/touch).
* @remarks
* This is a shorthand for `Flicking.control.enable`.
* @returns The current instance for method chaining
*/
enableInput(): this;
/**
* Disable user input (mouse/touch).
* @remarks
* This is a shorthand for `Flicking.control.disable`.
* @returns The current instance for method chaining
*/
disableInput(): this;
/**
* Get the current Flicking status.
* @param options - {@link GetStatusParams}
* @returns Status object that can be used with {@link Flicking.setStatus} to restore the state
*/
getStatus(options?: GetStatusParams): Status;
/**
* Restore Flicking to the state of the given {@link Status}.
* @param status - {@link Status}
* @throws {@link StatusRestoreErrors}
*/
setStatus(status: Status): void;
/**
* Add plugins to Flicking.
* @remarks
* Plugins are automatically initialized if Flicking is already initialized.
* @param plugins - {@link Plugin}
* @returns The current instance for method chaining
* @see https://github.com/naver/egjs-flicking-plugins
*/
addPlugins(...plugins: Plugin[]): this;
/**
* Remove plugins from Flicking.
* @param plugins - {@link Plugin}
* @returns The current instance for method chaining
* @see https://github.com/naver/egjs-flicking-plugins
*/
removePlugins(...plugins: Plugin[]): this;
/**
* Update viewport and panel sizes.
* @remarks
* This method does nothing if a resize is already in progress.
* @fires {@link ResizeEvents}
* @returns Promise that resolves when resize is complete
*/
resize(): Promise<void>;
/**
* Add new panels after the last panel.
* @param element - A new HTMLElement, outerHTML string, or an array of both
* @throws {@link DOMManipulationErrors}
* @returns Array of appended panels
* @example
* ```ts
* const flicking = new Flicking("#flick");
* flicking.append(document.createElement("div"));
* flicking.append("<div>Panel</div>");
* flicking.append(["<div>Panel</div>", document.createElement("div")]);
* ```
*/
append(element: ElementLike | ElementLike[]): Panel[];
/**
* Add new panels before the first panel.
* @remarks
* This will increase the index of existing panels by the number of panels added.
* @param element - A new HTMLElement, outerHTML string, or an array of both
* @throws {@link DOMManipulationErrors}
* @returns Array of prepended panels
* @example
* ```ts
* const flicking = new Flicking("#flick");
* flicking.prepend(document.createElement("div"));
* flicking.prepend("<div>Panel</div>");
* flicking.prepend(["<div>Panel</div>", document.createElement("div")]);
* ```
*/
prepend(element: ElementLike | ElementLike[]): Panel[];
/**
* Insert new panels at the given index.
* @remarks
* This will increase the index of panels at or after the given index by the number of panels added.
* @param index - Index to insert new panels at
* @param element - A new HTMLElement, outerHTML string, or an array of both
* @throws {@link DOMManipulationErrors}
* @returns Array of inserted panels
* @example
* ```ts
* const flicking = new Flicking("#flick");
* flicking.insert(0, document.createElement("div"));
* flicking.insert(2, "<div>Panel</div>");
* flicking.insert(1, ["<div>Panel</div>", document.createElement("div")]);
* ```
*/
insert(index: number, element: ElementLike | ElementLike[]): Panel[];
/**
* Remove panels starting from the given index.
* @remarks
* This will decrease the index of panels after the removed ones by the number of panels removed.
* @param index - Index of the first panel to remove
* @param deleteCount - Number of panels to remove. Defaults to `1`
* @throws {@link DOMManipulationErrors}
* @returns Array of removed panels
*/
remove(index: number, deleteCount?: number): Panel[];
/**
* Factory method to create the appropriate Control implementation based on moveType option.
* @internal
* @privateRemarks
* Called during constructor and when moveType option is changed. The moveType option must be set before calling this method.
* Th