Cross Flicking

CrossFlicking is a preset class that combines a horizontal and vertical Flicking into a single 2D carousel. Swipe horizontally to switch between groups and vertically to browse items within a group.

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

Summary

Key Options

Option	Type	Default	Description
sideOptions	Partial<FlickingOptions>	{}	Options applied to the auto-created vertical (side) Flicking instances
preserveIndex	boolean	true	Keep each group's own side index when switching groups
disableSlideOnHold	boolean	true	Lock the perpendicular axis while dragging one direction
disableIndexSync	boolean	false	Disable automatic index synchronization between main/side

CrossFlicking also accepts every FlickingOptions (e.g. moveType, bound) which apply to the horizontal main axis.

Structure

Level	Direction	Role
Main Flicking (CrossFlicking)	Horizontal (↔)	Navigation between groups
Side Flicking (auto-created)	Vertical (↕)	Navigation within a group

Each group is a direct child of the camera — a wrapper <div> whose children become the vertical side panels.

Details

How CrossFlicking Works

CrossFlicking reads the group structure from the DOM at initialization, then rebuilds each group into an independent vertical Flicking. The outer instance handles horizontal movement between groups, while each group manages its own vertical movement — producing a grid-like 2D navigation from a single class.

Authoring per Framework

Across all frameworks the demo drives the core CrossFlicking class imperatively: group the panels with a wrapper <div> and pass the viewport element to the constructor.

import { CrossFlicking } from "@egjs/flicking"; // or "@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><!-- group: Nature -->
      <div class="cross-panel">Forest</div>
      <div class="cross-panel">Meadow</div>
    </div>
    <div><!-- group: Ocean -->
      <div class="cross-panel">Reef</div>
      <div class="cross-panel">Wave</div>
    </div>
  </div>
</div>

React / Vue

@egjs/react-flicking also exports CrossFlicking/CrossGroup components, but they currently break under React StrictMode (the instance is destroyed before its async init completes). Until that is fixed, drive the core class from useEffect/onMounted as this demo does. Vue3 has no dedicated wrapper, so the core class is the only option there.

Events

Main-axis events (changed, willChange) carry an extra sideIndex field pointing to the active group's side index. Side-axis events are prefixed with side and carry mainIndex to identify which group moved.

Event	Payload	Description
changed	{ index, sideIndex }	The horizontal (group) index changed
sideChanged	{ index, mainIndex }	A group's vertical (item) index changed
sideWillChange	{ index, mainIndex }	A group's vertical index is about to change

Related Options

• Combination with moveType: "strict": Moves exactly one group/item per swipe for clear grid navigation.
• Combination with bound: true: Prevents empty space at the edges of both axes.
• sideOptions: Configure the vertical instances independently from the horizontal one.

Use Cases

When should you use this?

• Category-based galleries (horizontal for categories, vertical for items)
• Story/reel viewers (horizontal for authors, vertical for posts)
• Dashboards (horizontal for sections, vertical for cards)

Notes

Caution

• Give the viewport an explicit height, since the vertical side instances need a fixed layout height.
• CrossFlicking rebuilds the group DOM on initialization; author groups as wrapper elements rather than expecting the original markup to remain unchanged.
• Vue has no CrossFlicking/CrossGroup component wrapper — use the core class through ref + onMounted, and call destroy() on unmount.

Related Links

Related APIs

• CrossFlicking: 2D cross-directional carousel preset class
• CrossFlickingOptions: CrossFlicking configuration

Related Demos

• Nested: On/off comparison of the nested option for same-direction nesting
• Fullpage Scroll: Vertical fullpage pattern