Cross Flicking

CrossFlicking은 가로·세로 Flicking을 하나의 2D 캐러셀로 결합한 프리셋 클래스입니다. 가로로 스와이프하면 그룹 간 전환, 세로로 스와이프하면 그룹 내 항목 탐색이 이루어집니다.

JavaScript

import { CrossFlicking } from "@egjs/flicking";
import "@egjs/flicking/dist/flicking.css";
import "./styles.css";

// The panel structure lives in index.html; attaching CrossFlicking is all that's needed.
new CrossFlicking("#cross", {
  align: "prev",
  moveType: "strict",
  bound: true,
  sideOptions: { moveType: "strict", bound: true }
});

Open Sandbox

React

import { CrossFlicking } from "@egjs/flicking";
import "@egjs/flicking/dist/flicking.css";
import "./styles.css";
import { useEffect, useRef } from "react";

// The panel structure is declared in JSX; the core CrossFlicking class is attached to it on mount.
// react-flicking's CrossFlicking/CrossGroup components are avoided for now because they break
// under React StrictMode (destroyed before their async init completes).
const CATEGORIES = [
  {
    name: "Nature",
    items: [
      { title: "Forest", gradient: "linear-gradient(135deg, #0f9b70, #1e5631)" },
      { title: "Meadow", gradient: "linear-gradient(135deg, #56ab2f, #a8e063)" },
      { title: "Canyon", gradient: "linear-gradient(135deg, #3ca55c, #b5ac49)" }
    ]
  },
  {
    name: "Ocean",
    items: [
      { title: "Reef", gradient: "linear-gradient(135deg, #2193b0, #6dd5ed)" },
      { title: "Wave", gradient: "linear-gradient(135deg, #1a2980, #26d0ce)" },
      { title: "Deep", gradient: "linear-gradient(135deg, #000046, #1cb5e0)" }
    ]
  },
  {
    name: "Sunset",
    items: [
      { title: "Dawn", gradient: "linear-gradient(135deg, #ff9966, #ff5e62)" },
      { title: "Dusk", gradient: "linear-gradient(135deg, #f7971e, #ffd200)" },
      { title: "Ember", gradient: "linear-gradient(135deg, #cb2d3e, #ef473a)" }
    ]
  },
  {
    name: "Space",
    items: [
      { title: "Nebula", gradient: "linear-gradient(135deg, #654ea3, #eaafc8)" },
      { title: "Aurora", gradient: "linear-gradient(135deg, #4776e6, #8e54e9)" },
      { title: "Cosmos", gradient: "linear-gradient(135deg, #200122, #6f0000)" }
    ]
  }
];

export default function App() {
  const viewportRef = useRef(null);
  const flickingRef = useRef(null);

  useEffect(() => {
    // The ref keeps a single instance across StrictMode's double-invoke.
    if (flickingRef.current) return;
    flickingRef.current = new CrossFlicking(viewportRef.current, {
      align: "prev",
      moveType: "strict",
      bound: true,
      sideOptions: { moveType: "strict", bound: true }
    });
  }, []);

  return (
    <div ref={viewportRef} className="cross-viewport flicking-viewport">
      <div className="flicking-camera">
        {CATEGORIES.map((category, ci) => (
          <div className="cross-group" key={ci}>
            {category.items.map((it, ii) => (
              <div className="cross-panel" key={ii} style={{ background: it.gradient }}>
                <span className="panel-category">{category.name}</span>
                <span className="panel-title">{it.title}</span>
                <span className="panel-hint">↕ browse items · ↔ switch category</span>
              </div>
            ))}
          </div>
        ))}
      </div>
    </div>
  );
}

Open Sandbox

Vue@3

<template>
  <div ref="viewport" class="cross-viewport flicking-viewport">
    <div class="flicking-camera">
      <div v-for="(category, ci) in CATEGORIES" :key="ci" class="cross-group">
        <div v-for="(it, ii) in category.items" :key="ii"
             class="cross-panel" :style="{ background: it.gradient }">
          <span class="panel-category">{{ category.name }}</span>
          <span class="panel-title">{{ it.title }}</span>
          <span class="panel-hint">↕ browse items · ↔ switch category</span>
        </div>
      </div>
    </div>
  </div>
</template>

<script setup>
import { CrossFlicking } from "@egjs/vue3-flicking";
import "@egjs/vue3-flicking/dist/flicking.css";
import { onBeforeUnmount, onMounted, ref } from "vue";

// Vue3 has no dedicated CrossFlicking wrapper, so the core class is used imperatively.
const CATEGORIES = [
  {
    name: "Nature",
    items: [
      { title: "Forest", gradient: "linear-gradient(135deg, #0f9b70, #1e5631)" },
      { title: "Meadow", gradient: "linear-gradient(135deg, #56ab2f, #a8e063)" },
      { title: "Canyon", gradient: "linear-gradient(135deg, #3ca55c, #b5ac49)" }
    ]
  },
  {
    name: "Ocean",
    items: [
      { title: "Reef", gradient: "linear-gradient(135deg, #2193b0, #6dd5ed)" },
      { title: "Wave", gradient: "linear-gradient(135deg, #1a2980, #26d0ce)" },
      { title: "Deep", gradient: "linear-gradient(135deg, #000046, #1cb5e0)" }
    ]
  },
  {
    name: "Sunset",
    items: [
      { title: "Dawn", gradient: "linear-gradient(135deg, #ff9966, #ff5e62)" },
      { title: "Dusk", gradient: "linear-gradient(135deg, #f7971e, #ffd200)" },
      { title: "Ember", gradient: "linear-gradient(135deg, #cb2d3e, #ef473a)" }
    ]
  },
  {
    name: "Space",
    items: [
      { title: "Nebula", gradient: "linear-gradient(135deg, #654ea3, #eaafc8)" },
      { title: "Aurora", gradient: "linear-gradient(135deg, #4776e6, #8e54e9)" },
      { title: "Cosmos", gradient: "linear-gradient(135deg, #200122, #6f0000)" }
    ]
  }
];

const viewport = ref(null);
let flicking = null;

onMounted(() => {
  flicking = new CrossFlicking(viewport.value, {
    align: "prev",
    moveType: "strict",
    bound: true,
    sideOptions: { moveType: "strict", bound: true }
  });
});

onBeforeUnmount(() => {
  if (flicking) flicking.destroy();
});
</script>


<style>

.flicking-viewport.vertical {
  display: block;
  width: 100%;
}

.flicking-panel {
  width: 200px;
  height: 150px;
  margin-right: 10px;
  border-radius: 8px;
  display: flex;
  align-items: center;
  justify-content: center;
  font-size: 24px;
  font-weight: bold;
  color: white;
}

.panel-1 { background: #3e8ed0; }
.panel-2 { background: #00d1b2; }
.panel-3 { background: #f14668; }
.panel-4 { background: #ffe08a; color: #333; }
.panel-5 { background: #48c78e; }

.demo-container {
  margin-bottom: 24px;
}

.demo-label {
  font-weight: bold;
  margin-bottom: 8px;
  color: #666;
}

.button {
  padding: 8px 16px;
  margin: 4px;
  border: 2px solid #3498db;
  background: transparent;
  color: #3498db;
  border-radius: 4px;
  cursor: pointer;
  font-size: 14px;
}

.button:hover {
  background: #3498db;
  color: white;
}

.controls {
  display: flex;
  justify-content: center;
  margin-top: 16px;
  gap: 8px;
}

.cross-viewport {
  width: 100%;
  max-width: 360px;
  height: 320px;
  margin: 0 auto;
  border-radius: 12px;
  overflow: hidden;
}

/* Each main panel doubles as a vertical side viewport (built by CrossFlicking). */
.cross-viewport > .flicking-camera > .flicking-panel {
  width: 100%;
  height: 320px;
  margin: 0;
}

.cross-viewport .cross-panel {
  width: 100%;
  height: 320px;
  margin: 0;
  border-radius: 0;
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  gap: 8px;
  color: #fff;
  text-align: center;
}

.cross-viewport .panel-category {
  font-size: 13px;
  letter-spacing: 2px;
  text-transform: uppercase;
  opacity: 0.85;
}

.cross-viewport .panel-title {
  font-size: 28px;
  font-weight: 700;
}

.cross-viewport .panel-hint {
  margin-top: 12px;
  font-size: 12px;
  font-weight: 400;
  opacity: 0.8;
}

</style>

Open Sandbox

요약

주요 옵션

옵션	타입	기본값	설명
sideOptions	Partial<FlickingOptions>	{}	자동 생성되는 세로(side) Flicking 인스턴스에 적용되는 옵션
preserveIndex	boolean	true	그룹 전환 시 각 그룹의 side 인덱스를 유지
disableSlideOnHold	boolean	true	한 방향으로 드래그하는 동안 수직 축을 잠금
disableIndexSync	boolean	false	main/side 간 자동 인덱스 동기화 비활성화

CrossFlicking은 모든 FlickingOptions(예: moveType, bound)도 받으며, 이들은 가로 방향 main 축에 적용됩니다.

구조

레벨	방향	역할
Main Flicking (CrossFlicking)	가로 (↔)	그룹 간 이동
Side Flicking (자동 생성)	세로 (↕)	그룹 내 이동

각 그룹은 camera의 직속 자식으로, 그 자식들이 세로 side 패널이 되는 래퍼 <div>입니다.

상세 설명

CrossFlicking 동작 방식

CrossFlicking은 초기화 시 DOM에서 그룹 구조를 읽어 각 그룹을 독립적인 세로 Flicking으로 재구성합니다. 외부 인스턴스는 그룹 간 가로 이동을 처리하고, 각 그룹은 자체 세로 이동을 관리하여 — 하나의 클래스로 격자형 2D 네비게이션을 만들어냅니다.

프레임워크별 작성법

모든 프레임워크에서 데모는 코어 CrossFlicking 클래스를 명령형으로 구동합니다. 패널을 래퍼 <div>로 묶고 뷰포트 요소를 생성자에 전달합니다.

import { CrossFlicking } from "@egjs/flicking"; // 또는 "@egjs/vue3-flicking"

new CrossFlicking("#cross", {
  align: "prev",
  moveType: "strict",
  bound: true,
  sideOptions: { moveType: "strict", bound: true }
});

<div id="cross" class="flicking-viewport">
  <div class="flicking-camera">
    <div><!-- 그룹: Nature -->
      <div class="cross-panel">Forest</div>
      <div class="cross-panel">Meadow</div>
    </div>
    <div><!-- 그룹: Ocean -->
      <div class="cross-panel">Reef</div>
      <div class="cross-panel">Wave</div>
    </div>
  </div>
</div>

React / Vue

@egjs/react-flicking도 CrossFlicking/CrossGroup 컴포넌트를 export하지만, 현재 React StrictMode에서 정상 동작하지 않습니다(비동기 init이 끝나기 전에 인스턴스가 destroy됨). 이 문제가 해결되기 전까지는 이 데모처럼 useEffect/onMounted에서 코어 클래스를 직접 구동하세요. Vue3에는 전용 래퍼가 없으므로 코어 클래스가 유일한 방법입니다.

이벤트

Main 축 이벤트(changed, willChange)는 활성 그룹의 side 인덱스를 가리키는 sideIndex 필드를 추가로 전달합니다. Side 축 이벤트는 side 접두어가 붙으며, 어느 그룹이 이동했는지 식별하는 mainIndex를 전달합니다.

이벤트	페이로드	설명
changed	{ index, sideIndex }	가로(그룹) 인덱스 변경됨
sideChanged	{ index, mainIndex }	그룹의 세로(항목) 인덱스 변경됨
sideWillChange	{ index, mainIndex }	그룹의 세로 인덱스가 변경되기 직전

연관 옵션

• moveType: "strict"와의 조합: 스와이프 한 번에 정확히 그룹/항목 하나씩 이동하여 격자 네비게이션이 명확해집니다.
• bound: true와의 조합: 양쪽 축 가장자리에서 빈 공간을 방지합니다.
• sideOptions: 가로 인스턴스와 별개로 세로 인스턴스를 설정합니다.

사용 시나리오

언제 사용하나요?

• 카테고리 기반 갤러리 (가로로 카테고리, 세로로 항목)
• 스토리/릴 뷰어 (가로로 작성자, 세로로 게시물)
• 대시보드 (가로로 섹션, 세로로 카드)

주의사항

주의

• 세로 side 인스턴스는 고정된 레이아웃 높이가 필요하므로, 뷰포트에 명시적인 높이를 지정하세요.
• CrossFlicking은 초기화 시 그룹 DOM을 재구성합니다. 원본 마크업이 그대로 유지된다고 가정하지 말고 그룹을 래퍼 요소로 작성하세요.
• Vue에는 CrossFlicking/CrossGroup 컴포넌트 래퍼가 없습니다 — ref + onMounted로 코어 클래스를 사용하고, 언마운트 시 destroy()를 호출하세요.

관련 링크

관련 API

• CrossFlicking: 2D 크로스 방향 캐러셀 프리셋 클래스
• CrossFlickingOptions: CrossFlicking 설정

관련 데모

• Nested: 같은 방향 중첩을 위한 nested 옵션의 on/off 비교
• Fullpage Scroll: 세로 방향 풀페이지 패턴