드래그 & 드랍 라이브러리 Draggable JS: Sortable/Swappable 빠르게 적용하는 실전 가이드

드래그 & 드랍 라이브러리 Draggable JS: Sortable/Swappable 빠르게 적용하는 실전 가이드

설명(Description)

Draggable은 모듈식 드래그 앤 드롭 라이브러리로, 기본 Drag & Drop부터 빠른 DOM 재정렬(Sortable), 요소 교환(Swappable), 접근성 있는 마크업, 다양한 이벤트 처리까지 확장할 수 있습니다. 마우스/터치(포스 터치 포함) 입력과 호환되며, 플러그인·센서 구조로 기능을 단계적으로 추가할 수 있습니다.

키워드 태그(앞에 #)

#DraggableJS #드래그앤드롭 #Sortable #Swappable #JavaScript #프론트엔드 #UI개발 #MIT라이선스 #GoogleSEO #SearchAIOptimization

홈페이지 바로가기 · 소스 다운로드 · 데모 미리보기

홈페이지 바로가기 소스 다운로드(GitHub) 데모 미리보기

- 홈페이지: https://shopify.github.io/draggable/
- 소스(GitHub): https://github.com/Shopify/draggable
- 데모(Examples): https://shopify.github.io/draggable/examples/

목차 (버튼 클릭 시 바로 이동)

1) 한 줄 요약 2) 핵심 기능 3) 라이선스 4) 사용방법 5) 설치/불러오기 6) 옵션 설정 7) 주요 이벤트 8) 사용 예시 9) 실전 팁 10) 추천 태그

1) 한 줄 요약

Draggable JS는 “기본 드래그”를 중심으로, 필요에 따라 Sortable(정렬), Swappable(교환) 같은 모듈을 덧붙여 확장할 수 있는 모듈식 드래그 앤 드롭 라이브러리입니다.

2) 핵심 기능

• 기본 Drag & Drop: 드래그 가능한 요소를 쉽게 정의
• 빠른 DOM 재정렬: Sortable을 통해 리스트/카드 정렬 구현
• 접근성 있는 마크업: 접근성 고려(프로젝트 구조상 유리)
• 다양한 이벤트: 드래그 시작/이동/종료부터 sortable/swappable 전용 이벤트까지 제공
• 입력 호환: 네이티브 드래그, 마우스, 터치, 포스 터치 이벤트 호환
• 확장 구조: 드래그 수명 주기에 연결해 동작 확장(플러그인/센서 구조)
• ES6 우선: 현대적인 JS 환경을 기본 타겟

3) 라이선스

MIT License
상업/비상업 모두 사용 가능하며, 라이선스 고지 및 저작권 고지를 포함하는 형태로 사용하는 것이 일반적입니다.

4) 사용방법

압축파일 내부에 test.html이 포함되어 있으며, 많은 기능 중 Sortable, Swappable 기능을 데모로 구현해 둔 형태입니다. 처음 시작할 때는 test.html을 먼저 실행해 동작 흐름을 확인한 후, 필요한 모듈만 프로젝트에 적용하는 방식이 가장 빠릅니다.

5) 설치/불러오기 (초보자용 2가지 방식)

방법 A) NPM 설치(권장: 번들러 환경)

npm install @shopify/draggable

NPM 페이지: https://www.npmjs.com/package/@shopify/draggable

방법 B) CDN(빠른 테스트/데모용, ESM import)

최신 브라우저 환경에서 type="module"로 ESM을 가져와 간단히 테스트할 수 있습니다. (실서비스는 번들러/빌드 환경을 권장)

<script type="module">
  import { Sortable, Swappable } from 'https://cdn.jsdelivr.net/npm/@shopify/draggable/build/esm/index.mjs';
  // 여기서 인스턴스 생성
</script>

jsDelivr: https://cdn.jsdelivr.net/npm/@shopify/draggable/

6) 옵션 설정 (해피CGI 옵션 목록 정리)

6-1. Draggable 공통 옵션

• draggable : 드래그 가능한 요소의 CSS 셀렉터
• handle : 드래그를 시작할 핸들 요소의 CSS 셀렉터
• delay : 드래그 시작 전 지연 시간(ms)
• distance : 드래그로 인식하기 위한 최소 이동 거리(px)
• plugins : 사용할 플러그인 배열
• sensors : 사용할 센서 배열(마우스, 터치 등)
• classes : 드래그 상태별 CSS 클래스 커스터마이징 객체

6-2. Sortable 전용 옵션

• sortAnimation : 정렬 애니메이션 플러그인 설정
• swapAnimation : 교환 애니메이션 플러그인 설정

6-3. Mirror(미러 이미지) 옵션

• mirror.appendTo : 미러 요소를 추가할 부모 요소
• mirror.constrainDimensions : 미러 크기를 원본과 동일하게 고정(true/false)
• mirror.xAxis : X축 이동만 허용(true/false)
• mirror.yAxis : Y축 이동만 허용(true/false)
• mirror.cursorOffsetX : 커서 X축 오프셋
• mirror.cursorOffsetY : 커서 Y축 오프셋

6-4. Scrollable(자동 스크롤) 옵션

• scrollable.speed : 자동 스크롤 속도
• scrollable.sensitivity : 스크롤 감지 영역 크기(px)

6-5. Classes(CSS 클래스 커스터마이징)

• classes.draggable : 드래그 가능한 요소에 적용될 클래스
• classes.mirror : 미러 요소에 적용될 클래스
• classes.source.dragging : 드래그 중인 원본 요소 클래스
• classes.source.placed : 드래그 완료 후 원본 요소 클래스
• classes.container.dragging : 드래그 중인 컨테이너 클래스
• classes.body.dragging : 드래그 중일 때 body 적용 클래스
• classes.draggable.over : 드래그 요소가 위에 있을 때 적용 클래스

7) 주요 이벤트 (해피CGI 이벤트 목록 정리)

7-1. Draggable 기본 이벤트

• drag:start : 드래그 시작
• drag:move : 드래그 이동
• drag:stop : 드래그 종료

7-2. Sortable 전용 이벤트

• sortable:start : 정렬 시작
• sortable:sort : 정렬 중
• sortable:sorted : 정렬 완료
• sortable:stop : 정렬 종료

7-3. Swappable 전용 이벤트

• swappable:start : 교환 시작
• swappable:swap : 교환 중
• swappable:swapped : 교환 완료
• swappable:stop : 교환 종료

7-4. Droppable/Mirror 관련 이벤트

• droppable:start / droppable:dropped / droppable:returned / droppable:stop
• mirror:created / mirror:attached / mirror:move / mirror:destroy

8) 사용 예시 (Sortable / Swappable 중심)

8-1. Sortable 예시(리스트 정렬)

아래 예시는 “컨테이너 안의 아이템(.item)을 드래그로 재정렬”하는 기본 구조입니다. 옵션은 가장 자주 쓰는 draggable, handle만 먼저 적용하고, 필요할 때 delay/distance/classes 등을 추가하는 방식이 좋습니다.

<!-- HTML 구조 예시 -->
<div class="list" id="todoList">
  <div class="item"><span class="handle">≡</span> 할 일 1</div>
  <div class="item"><span class="handle">≡</span> 할 일 2</div>
  <div class="item"><span class="handle">≡</span> 할 일 3</div>
</div>

<script type="module">
  import { Sortable } from 'https://cdn.jsdelivr.net/npm/@shopify/draggable/build/esm/index.mjs';

  const sortable = new Sortable(document.querySelectorAll('#todoList'), {
    draggable: '.item',
    handle: '.handle',
    delay: 0,
    distance: 0
  });

  sortable.on('sortable:sorted', (evt) => {
    // 정렬 완료 후 처리(예: 서버 저장, 순서 출력 등)
    // evt.oldIndex, evt.newIndex 등 이벤트 객체를 확인해 확장하세요.
    console.log('sorted', evt);
  });
</script>

8-2. Swappable 예시(요소 자리 교환)

Swappable은 “순서 정렬”이 아니라 “서로 자리 교환”이 핵심입니다. 카드 UI, 자리 배치, 슬롯 교환형 UI에 잘 맞습니다.

<!-- HTML 구조 예시 -->
<div class="grid" id="swapGrid">
  <div class="card">A</div>
  <div class="card">B</div>
  <div class="card">C</div>
  <div class="card">D</div>
</div>

<script type="module">
  import { Swappable } from 'https://cdn.jsdelivr.net/npm/@shopify/draggable/build/esm/index.mjs';

  const swappable = new Swappable(document.querySelectorAll('#swapGrid'), {
    draggable: '.card'
  });

  swappable.on('swappable:swapped', (evt) => {
    console.log('swapped', evt);
  });
</script>

9) 실전 팁 (초보자 관점에서 실패를 줄이는 체크리스트)

가장 흔한 실수 3가지

1. 드래그 대상 셀렉터(draggable)가 실제 DOM 구조와 맞지 않음
2. 컨테이너 지정을 잘못해 “원하는 영역이 아닌 곳”에서 드래그가 걸림
3. 핸들(handle) 지정 후 핸들 요소가 아이템 내부에 존재하지 않음

추천 적용 순서

1. 먼저 Sortable 또는 Swappable 중 필요한 모듈 1개만 선택
2. 옵션은 draggable만 적용해 동작 확인
3. 그다음 handle 적용 (의도치 않은 드래그 방지)
4. 마지막으로 classes/mirror/scrollable로 UX 고도화
5. 이벤트는 sorted/swapped부터 연결해 “순서 저장/상태 저장” 구현

참고 링크(공식)

• 공식 홈페이지: https://shopify.github.io/draggable/
• 문서(Documentation): https://shopify.github.io/draggable/docs/
• 예제(Examples): https://shopify.github.io/draggable/examples/
• GitHub(소스): https://github.com/Shopify/draggable
• NPM: https://www.npmjs.com/package/@shopify/draggable

맨 위로