Virtual Scroll

virtual 옵션으로 대량의 패널을 가상 렌더링하여 메모리 사용량을 대폭 줄입니다.

JavaScript

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

const TOTAL_PANELS = 1000;
const _COLORS = ["#3e8ed0", "#00d1b2", "#f14668", "#ffe08a", "#48c78e", "#9c27b0", "#ff5722"];

// Virtual mode: 1000 panels
const virtualFlicking = new Flicking("#flick-virtual", {
  align: "prev",
  panelsPerView: 3,
  virtual: {
    renderPanel: (panel, index) => `<div class="panel-inner color-${index % 7}">Panel ${index + 1}</div>`,
    initialPanelCount: TOTAL_PANELS,
    cache: true,
    panelClass: "flicking-panel"
  }
});

// Normal mode: 100 panels (for comparison)
// In normal mode, panels are created as HTML elements
const normalFlicking = new Flicking("#flick-normal", {
  align: "prev"
});

// Update DOM element count
function updateDomCounts() {
  const virtualCount = document.querySelectorAll("#flick-virtual .flicking-panel").length;
  const normalCount = document.querySelectorAll("#flick-normal .flicking-panel").length;

  document.getElementById("virtual-count").textContent = virtualCount;
  document.getElementById("normal-count").textContent = normalCount;
}

virtualFlicking.on("move", updateDomCounts);
virtualFlicking.on("ready", updateDomCounts);
normalFlicking.on("ready", updateDomCounts);

updateDomCounts();

Open Sandbox

React

import Flicking, { VirtualPanel } from "@egjs/react-flicking";
import { useEffect, useRef, useState } from "react";
import "@egjs/react-flicking/dist/flicking.css";
import "./styles.css";

const TOTAL_PANELS = 1000;
const COLORS = ["#3e8ed0", "#00d1b2", "#f14668", "#ffe08a", "#48c78e", "#9c27b0", "#ff5722"];

export default function App() {
  const normalFlickingRef = useRef(null);
  const virtualFlickingRef = useRef(null);
  const [normalDomCount, setNormalDomCount] = useState(0);
  const [virtualDomCount, setVirtualDomCount] = useState(0);

  // Update DOM element count
  const updateDomCounts = () => {
    if (normalFlickingRef.current) {
      const panels = normalFlickingRef.current.element.querySelectorAll(".flicking-panel");
      setNormalDomCount(panels.length);
    }
    if (virtualFlickingRef.current) {
      const panels = virtualFlickingRef.current.element.querySelectorAll(".flicking-panel");
      setVirtualDomCount(panels.length);
    }
  };

  useEffect(() => {
    updateDomCounts();
  }, [updateDomCounts]);

  // Normal mode panel array (100 only - 1000 causes memory issues)
  const normalPanels = Array.from({ length: 100 }, (_, i) => ({
    index: i,
    color: COLORS[i % COLORS.length]
  }));

  return (
    <div>
      {/* Virtual mode: 1000 panels */}
      <div className="demo-container">
        <div className="demo-label">virtual enabled (1000 panels)</div>
        <div className="demo-info">Only panelsPerView + 1 DOM elements are maintained</div>
        <Flicking
          ref={virtualFlickingRef}
          align="prev"
          panelsPerView={3}
          virtual={{
            renderPanel: (panel, index) => `<div class="panel-inner color-${index % 7}">Panel ${index + 1}</div>`,
            initialPanelCount: TOTAL_PANELS,
            cache: true,
            panelClass: "flicking-panel"
          }}
          onMove={() => updateDomCounts()}
        />
        <div className="dom-counter">
          Total <strong>{TOTAL_PANELS}</strong> panels, DOM elements: <strong>{virtualDomCount}</strong>
        </div>
      </div>

      {/* Normal mode: 100 panels (for comparison) */}
      <div className="demo-container">
        <div className="demo-label">virtual disabled (100 panels - for comparison)</div>
        <div className="demo-info">All panels exist in the DOM</div>
        <Flicking ref={normalFlickingRef} align="prev" onReady={() => updateDomCounts()}>
          {normalPanels.map(panel => (
            <div key={panel.index} className="flicking-panel" style={{ background: panel.color }}>
              Panel {panel.index + 1}
            </div>
          ))}
        </Flicking>
        <div className="dom-counter">
          Total <strong>{normalPanels.length}</strong> panels = DOM elements: <strong>{normalDomCount}</strong>
        </div>
      </div>
    </div>
  );
}

Open Sandbox

Vue@3

<template>
  <div>
    <!-- Virtual mode: 1000 panels -->
    <div class="demo-container">
      <div class="demo-label">virtual enabled (1000 panels)</div>
      <div class="demo-info">Only panelsPerView + 1 DOM elements are maintained</div>
      <Flicking
        ref="virtualFlicking"
        :options="virtualOptions"
        @move="updateDomCounts"
        @ready="updateDomCounts"
      />
      <div class="dom-counter">
        Total <strong>1000</strong> panels, DOM elements: <strong>{{ virtualDomCount }}</strong>
      </div>
    </div>

    <!-- Normal mode: 100 panels (for comparison) -->
    <div class="demo-container">
      <div class="demo-label">virtual disabled (100 panels - for comparison)</div>
      <div class="demo-info">All panels exist in the DOM</div>
      <Flicking
        ref="normalFlicking"
        :options="{ align: 'prev' }"
        @ready="updateDomCounts"
      >
        <div
          v-for="panel in normalPanels"
          :key="panel.index"
          class="flicking-panel"
          :style="{ background: panel.color }"
        >
          Panel {{ panel.index + 1 }}
        </div>
      </Flicking>
      <div class="dom-counter">
        Total <strong>{{ normalPanels.length }}</strong> panels = DOM elements: <strong>{{ normalDomCount }}</strong>
      </div>
    </div>
  </div>
</template>

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

const COLORS = ["#3e8ed0", "#00d1b2", "#f14668", "#ffe08a", "#48c78e", "#9c27b0", "#ff5722"];
const normalFlicking = ref(null);
const virtualFlicking = ref(null);
const normalDomCount = ref(0);
const virtualDomCount = ref(0);
const normalPanels = Array.from({ length: 100 }, (_, i) => ({
  index: i,
  color: COLORS[i % COLORS.length]
}));
const virtualOptions = {
  align: "prev",
  panelsPerView: 3,
  virtual: {
    renderPanel: (panel, index) => {
      return `<div class="panel-inner color-${index % 7}">Panel ${index + 1}</div>`;
    },
    initialPanelCount: 1000,
    cache: true,
    panelClass: "flicking-panel"
  }
};

const updateDomCounts = () => {
  nextTick(() => {
    if (normalFlicking.value) {
      const panels = normalFlicking.value.$el.querySelectorAll(".flicking-panel");
      normalDomCount.value = panels.length;
    }
    if (virtualFlicking.value) {
      const panels = virtualFlicking.value.$el.querySelectorAll(".flicking-panel");
      virtualDomCount.value = panels.length;
    }
  });
};
</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;
}

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

.panel-inner {
  width: 100%;
  height: 100%;
  display: flex;
  align-items: center;
  justify-content: center;
  border-radius: inherit;
}

.color-0 {
  background: #3e8ed0;
}
.color-1 {
  background: #00d1b2;
}
.color-2 {
  background: #f14668;
}
.color-3 {
  background: #ffe08a;
  color: #333;
}
.color-4 {
  background: #48c78e;
}
.color-5 {
  background: #9c27b0;
}
.color-6 {
  background: #ff5722;
}

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

.demo-info {
  font-size: 14px;
  color: #888;
  margin-bottom: 12px;
}
.dom-counter {
  margin-top: 8px;
  padding: 8px 12px;
  background: #f5f5f5;
  border-radius: 4px;
  font-size: 14px;
  color: #333;
}
.dom-counter strong {
  color: #3e8ed0;
}

</style>

Open Sandbox

요약

주요 옵션

옵션	타입	기본값	설명
virtual	VirtualOptions | null	null	가상 렌더링 설정
panelsPerView	number	-1	뷰포트에 보이는 패널 수 (virtual 사용 시 필수)

VirtualOptions 속성

속성	타입	기본값	설명
renderPanel	(panel, index) => string	-	패널 innerHTML 반환 함수
initialPanelCount	number	-1	초기 가상 패널 수
cache	boolean	false	렌더링 결과 캐싱 여부
panelClass	string	"flicking-panel"	패널 요소 클래스명

모드별 비교

모드	패널 1000개 시 DOM 요소	메모리 사용	초기 렌더링
일반 모드	1000개	높음	느림
virtual 모드	~4개 (panelsPerView + 1)	낮음	빠름

상세 설명

Virtual 렌더링 원리

Virtual 모드는 화면에 보이는 패널 + 버퍼만 실제 DOM에 유지합니다:

// 1000개의 논리적 패널, 실제 DOM은 4개만
const flicking = new Flicking("#el", {
  panelsPerView: 3,  // 필수: 화면에 보이는 패널 수
  virtual: {
    renderPanel: (panel, index) => `Panel ${index + 1}`,
    initialPanelCount: 1000,
    cache: true  // 동일 패널 재렌더링 방지
  }
});

스크롤 시 DOM 요소를 재활용하여 새 패널 내용으로 교체합니다. 이 방식으로 1000개, 10000개 이상의 패널도 일정한 메모리로 처리할 수 있습니다.

필수 설정: panelsPerView

panelsPerView 필수

virtual 옵션을 사용하려면 반드시 panelsPerView를 양수로 설정해야 합니다.
panelsPerView: -1 (자동)이면 virtual은 무시됩니다.

// 올바른 설정
{ panelsPerView: 3, virtual: { ... } }  // 동작함

// 잘못된 설정
{ panelsPerView: -1, virtual: { ... } }  // virtual 무시됨

renderPanel 콜백

renderPanel은 패널이 화면에 나타날 때마다 호출되어 innerHTML을 반환합니다:

virtual: {
  renderPanel: (panel, index) => {
    // index: 0부터 시작하는 패널 인덱스
    return `
      <img src="/images/item-${index}.jpg" />
      <span>Item ${index + 1}</span>
    `;
  },
  initialPanelCount: 1000
}

cache 옵션

// cache: true (권장 - 정적 콘텐츠)
virtual: {
  renderPanel: (panel, index) => `Panel ${index}`,
  cache: true  // 한 번 렌더링된 패널 내용 재사용
}

// cache: false (동적 콘텐츠)
virtual: {
  renderPanel: (panel, index) => `Panel ${index}: ${Date.now()}`,
  cache: false  // 매번 새로 렌더링
}

VirtualManager 메서드

런타임에 가상 패널을 추가/제거할 수 있습니다:

// 패널 추가
flicking.virtual.append(100);     // 끝에 100개 추가
flicking.virtual.prepend(50);     // 앞에 50개 추가
flicking.virtual.insert(10, 20);  // 인덱스 10에 20개 삽입

// 패널 제거
flicking.virtual.remove(0, 10);   // 인덱스 0부터 10개 제거

사용 시나리오

언제 virtual을 사용하나요?

사용 권장:

• 패널 수가 많은 경우 (50개 이상)
• 이미지 갤러리, 상품 목록 등 대량 데이터
• 무한 스크롤 구현
• 메모리 제약이 있는 모바일 환경

사용하지 않아도 되는 경우:

• 패널 수가 적은 경우 (10개 미만)
• 복잡한 패널 상호작용이 필요한 경우
• 패널 내용이 매우 동적인 경우

주의사항

프레임워크별 차이

React, Vue에서는 renderPanel이 문자열 HTML을 반환합니다. 컴포넌트 렌더링이 필요하면 renderOnlyVisible 옵션을 고려하세요.

renderPanel 성능

renderPanel은 스크롤 중 빈번히 호출됩니다. 복잡한 연산이나 DOM 조작은 피하고, cache: true를 활용하세요.

관련 링크

관련 옵션

• panelsPerView: 뷰포트에 보이는 패널 수
• renderOnlyVisible: React/Vue에서 보이는 패널만 렌더링

관련 클래스

• VirtualManager: 가상 패널 관리자

관련 데모

• Render Only Visible: 프레임워크 최적화 렌더링
• Infinite Scroll: 무한 스크롤 구현