Quick Start

Get started with Flicking in 5 minutes. This guide covers installation and creating your first carousel for JavaScript, React, and Vue3.

Installation

Using Package Managers (Recommended)

Install Flicking using npm or yarn:

JavaScript

npm install @egjs/flicking
# or
yarn add @egjs/flicking

React

npm install @egjs/react-flicking
# or
yarn add @egjs/react-flicking

Vue3

npm install @egjs/vue3-flicking
# or
yarn add @egjs/vue3-flicking

Using CDN (JavaScript Only)

For quick prototyping or simple projects, you can use CDN links:

<!-- JavaScript -->
<script src="https://unpkg.com/@egjs/flicking/dist/flicking.pkgd.min.js"></script>

<!-- CSS -->
<link rel="stylesheet" href="https://unpkg.com/@egjs/flicking/dist/flicking.css" />

info

CDN usage is convenient for testing, but using package managers is recommended for production.

---

Your First Carousel

Basic Setup

JavaScript

HTML Structure:

<div id="carousel" class="flicking-viewport">
  <div class="flicking-camera">
    <div class="panel">Panel 1</div>
    <div class="panel">Panel 2</div>
    <div class="panel">Panel 3</div>
  </div>
</div>

JavaScript:

import Flicking from "@egjs/flicking";
import "@egjs/flicking/dist/flicking.css";

// Initialize Flicking
const flicking = new Flicking("#carousel", {
  align: "center",
  circular: true
});

Required

• Base CSS: Must import @egjs/flicking/dist/flicking.css
• HTML Structure: .flicking-viewport and .flicking-camera wrapper divs are required
• Fixed Class Names: .flicking-viewport and .flicking-camera cannot be changed
• Flexible Panel Class: Panel class name is your choice (.panel, .slide, .item, etc.)
• Panel Detection: Direct children of .flicking-camera become panels

React

import Flicking from "@egjs/react-flicking";
import "@egjs/react-flicking/dist/flicking.css";

function App() {
  return (
    <Flicking align="center" circular={true}>
      <div className="panel">Panel 1</div>
      <div className="panel">Panel 2</div>
      <div className="panel">Panel 3</div>
    </Flicking>
  );
}

export default App;

Required

• Base CSS: Must import @egjs/react-flicking/dist/flicking.css
• Auto Structure: The <Flicking> component creates required structure automatically
• Panel Detection: Direct children of <Flicking> become panels

Vue3

<template>
  <Flicking :options="{ align: 'center', circular: true }">
    <div class="panel">Panel 1</div>
    <div class="panel">Panel 2</div>
    <div class="panel">Panel 3</div>
  </Flicking>
</template>

<script setup>
import Flicking from "@egjs/vue3-flicking";
import "@egjs/vue3-flicking/dist/flicking.css";
</script>

Required

• Base CSS: Must import @egjs/vue3-flicking/dist/flicking.css
• Auto Structure: The <Flicking> component creates required structure automatically
• Panel Detection: Direct children of <Flicking> become panels

Want to style your carousel?

Flicking provides minimal base styles to give you maximum styling freedom. The required base CSS handles only functionality, not design. Learn about HTML Structure & Styling to understand Flicking's architecture and how to style your carousel. This guide covers:

• How Flicking's 3-layer structure works
• Why the base CSS is required
• Common styling patterns and best practices

---

Using Methods

You can control Flicking programmatically using methods:

JavaScript

const flicking = new Flicking("#carousel");

// Move to specific panel
flicking.moveTo(2);

// Move to next panel
flicking.next();

// Move to previous panel
flicking.prev();

React

import { useRef } from "react";
import Flicking from "@egjs/react-flicking";

function App() {
  const flickingRef = useRef(null);

  const handleClick = () => {
    // Access Flicking instance via ref
    flickingRef.current?.moveTo(2);
  };

  return (
    <>
      <Flicking ref={flickingRef}>
        <div>Panel 1</div>
        <div>Panel 2</div>
        <div>Panel 3</div>
      </Flicking>
      <button onClick={handleClick}>Move to Panel 3</button>
    </>
  );
}

Vue3

<template>
  <div>
    <Flicking ref="flickingRef">
      <div>Panel 1</div>
      <div>Panel 2</div>
      <div>Panel 3</div>
    </Flicking>
    <button @click="handleClick">Move to Panel 3</button>
  </div>
</template>

<script setup>
import { ref } from "vue";
import Flicking from "@egjs/vue3-flicking";

const flickingRef = ref(null);

const handleClick = () => {
  // Access Flicking instance via ref
  flickingRef.value?.moveTo(2);
};
</script>

See Flicking Methods for all available methods.

---

Listening to Events

Handle user interactions by listening to events:

JavaScript

const flicking = new Flicking("#carousel");

// Listen to changed event (fired AFTER panel change)
flicking.on("changed", (e) => {
  console.log("Current panel index:", e.index);
});

// Listen to willChange event (fired BEFORE panel change)
flicking.on("willChange", (e) => {
  console.log("Moving to panel:", e.index);
});

React

<Flicking
  onChanged={(e) => {
    console.log("Current panel index:", e.index);
  }}
  onWillChange={(e) => {
    console.log("Moving to panel:", e.index);
  }}>
  {/* panels */}
</Flicking>

Event Handler Props

React event handlers use camelCase with on prefix: onChanged, onWillChange, etc.
See React Guide for more details.

Vue3

<Flicking
  @changed="handleChanged"
  @will-change="handleWillChange">
  <!-- panels -->
</Flicking>

<script setup>
const handleChanged = (e) => {
  console.log("Current panel index:", e.index);
};

const handleWillChange = (e) => {
  console.log("Moving to panel:", e.index);
};
</script>

Event Binding

Vue3 uses @ directive with kebab-case: @changed, @will-change, etc.
See Vue3 Guide for more details.

See Event Interfaces for all available events.

---

Next Steps

Now that you have a basic carousel working, explore more features:

• HTML Structure & Styling: Understand Flicking's architecture and customize your carousel
• Framework Guides (React / Vue3): Framework-specific features and best practices
• API Reference: Complete API documentation
• Demos: Interactive examples

---

Troubleshooting

Panels not displaying correctly?

Make sure you've imported the CSS file:

import "@egjs/flicking/dist/flicking.css";  // JavaScript
import "@egjs/react-flicking/dist/flicking.css";  // React
import "@egjs/vue3-flicking/dist/flicking.css";  // Vue3

Need more help? Check GitHub Issues or read the API documentation