cropper.js

해적왕·2025년 5월 11일

옵션

viewmode

0 제한 없음
1 크롭 박스가 캔버스 크기를 넘지 않도록 제한
2 캔버스의 최소 크기를 컨테이너 안에 맞도록 제한. 캔버스와 컨테이너 비율이 다르면, 한 쪽 방향으로 여백이 생김
3 캔버스의 최소 크기를 컨테이너를 완전히 채우도록 제한. 캔버스와 컨테이너 비율이 다르면, 한 방향의 내용이 잘릴 수 있음

dragMode

기본값 crop
crop 새로운 크롭 박스를 생성함
move 캔버스를 이동함
none 아무 동작도 하지 않음

initialAspectRatio

기본값 NaN
크롭 박스의 초기 가로세로 비율(aspect ratio) 을 설정
기본값은 NaN이며, 이 경우 캔버스(이미지 래퍼)의 비율과 동일하게 설정됨

이 옵션은 aspectRatio 옵션이 NaN으로 설정되어 있을 때만 적용
즉, 전체적으로 고정 비율을 사용하지 않되, 시작할 때만 특정 비율로 시작하고 싶은 경우 사용

aspectRatio

크롭 박스의 고정 가로세로 비율을 정의
기본값인 NaN은 자유롭게 비율을 조절할 수 있는 상태

이 옵션은 initialAspectRatio와 달리 사용 중에도 비율이 고정됨
비율을 강제하고 싶은 경우에 사용

data

초기화 시 setData 메서드를 통해 자동으로 전달되는 이전에 저장된 크롭 데이터
이 옵션은 autoCrop 옵션이 true일 때만 적용됨

이전에 사용자가 크롭한 위치나 크기를 기억해두고 다시 불러올 때 자동으로 해당 위치에 크롭 박스를 설정

new Cropper(image, {
  autoCrop: true,
  data: {
    x: 100,
    y: 50,
    width: 300,
    height: 200
  }
});

preview

크롭된 이미지를 실시간으로 미리 보여줄 컨테이너(요소) 를 지정할 수 있는 옵션

단일 DOM 요소, 요소 배열, NodeList, 혹은 CSS 선택자 문자열 형태로 전달 가능

Cropper는 이 옵션에 지정된 요소 안에 실시간으로 크롭된 미리보기 이미지를 자동으로 렌더링

최대 너비는 미리보기 컨테이너의 초기 너비로 결정
최대 높이도 미리보기 컨테이너의 초기 높이로 결정
aspectRatio 옵션을 설정했다면, 미리보기 컨테이너에도 동일한 비율을 설정해야 함
미리보기가 제대로 표시되지 않는다면, 미리보기 컨테이너에 overflow: hidden 스타일을 적용하기

responsive

기본값 true
브라우저 창 크기가 변경될 때(CSS로 리사이징 포함), Cropper를 다시 렌더링할지 여부를 설정

restore

기본값 true
창 크기가 변경되어 Cropper가 다시 렌더링된 후, 이전의 크롭 영역을 복원할지 여부를 설정

checkCrossOrigin

기본값 true
현재 이미지가 크로스 도메인(cross-origin) 이미지인지 확인

이미지가 cross-origin일 경우:
복제된 이미지 요소에 crossOrigin 속성이 자동으로 추가
브라우저 캐시 오류를 방지하기 위해, 이미지 URL에 타임스탬프 파라미터가 추가되어 이미지를 다시 로드

checkOrientation

기본값 true
현재 이미지의 Exif Orientation 정보를 확인
※ 이 정보는 JPEG 이미지에서만 존재할 수 있음

주요 기능:
이미지의 회전 방향 또는 뒤집힘 상태를 나타내는 Exif의 Orientation 값을 읽어서, 자동으로 회전 또는 반전 처리

이후, iOS에서 발생할 수 있는 렌더링 문제를 방지하기 위해, Orientation 값을 기본값인 1로 덮어씀

일부 JPG 이미지는 잘못된 Exif Orientation 값을 포함하고 있을 수 있으므로, 항상 100% 신뢰하긴 어렵
이 기능은 브라우저에서 Typed Arrays를 지원해야 하므로, IE 10 이상에서만 사용할 수 있음

기본값 true
이미지 위, 크롭 박스 아래에 반투명한 검정 모달 배경을 표시
크롭 영역이 더 도드라져 보이게 할 때 사용

guides

기본값 true
크롭 박스 위에 점선 가이드 라인(3등분 라인) 을 표시
이미지 구도를 맞출 때 유용 (예: 3분할 구도 등)

center

기본값 true
크롭 박스 안에 중심 점 표시선을 보여줌
정확한 중심을 확인하고 조절하고 싶을 때 사용

highlight

기본값 true
크롭 박스 위에 흰색 반투명 오버레이를 표시하여 크롭 박스를 강조

background

기본값 true
이미지 전체 컨테이너에 회색 격자 배경(grid) 을 표시
보통 배경을 구분 짓기 위해 사용되며, 필요 없다면 false

autoCrop

기본값 true
Cropper 초기화 시 자동으로 크롭 박스를 생성할지 여부
false로 설정하면 사용자가 직접 드래그해서 크롭 박스를 만들어야 함

autoCropArea

기본값: 0.8 (전체 이미지의 80%)
자동 크롭이 활성화된 경우, 처음 생성되는 크롭 박스의 크기 비율을 지정
예를 들어 1로 설정하면 이미지 전체가 크롭 박스로 잡히고, 0.5는 50%만 차지

movable

기본값 true
마우스 드래그 등으로 이미지를 이동(이동 가능) 할 수 있도록 허용

rotatable

기본값 true
이미지를 회전할 수 있도록 허용

scalable

기본값 true
이미지를 좌우 대칭/상하 대칭 변형할 수 있도록 허용

zoomable

기본값 true
마우스 휠 또는 제스처로 이미지를 확대/축소(줌인/아웃) 할 수 있도록 허용

zoomOnTouch

기본값 true
터치 드래그(핀치 등) 로 이미지를 확대/축소
모바일 기기에서 두 손가락으로 줌을 허용할지 여부

zoomOnWheel

기본값 true
마우스 휠로 이미지 줌 인/아웃

wheelZoomRatio

기본값 0.1
마우스 휠로 줌할 때, 확대/축소 비율의 크기(단계) 를 설정
값이 클수록 줌 속도가 빠름 (예: 0.2는 더 빠르게 확대/축소됨)

cropBoxMovable

기본값 true
크롭 박스를 드래그해서 이동할 수 있도록 허용
이미지는 고정된 상태에서 박스만 옮기고 싶을 때 사용

cropBoxResizable

기본값 true
크롭 박스를 드래그로 크기 조절할 수 있게 허용

toggleDragModeOnDblclick

기본값 true
더블 클릭(dblclick) 하면 "crop" ↔ "move" 모드 전환
이미지 이동 vs 크롭 박스 생성 모드를 빠르게 전환
(브라우저가 dblclick 이벤트를 지원해야 작동함)

minContainerWidth

기본값 200
컨테이너의 최소 너비(px)

minContainerHeight

기본값 100
컨테이너의 최소 높이(px)

minCanvasHeight

기본값 0
캔버스(이미지 영역)의 최소 높이(px)

minCropBoxWidth

기본값 0
크롭 박스의 최소 너비(px)

이미지 기준이 아닌 페이지 기준의 픽셀값

minCropBoxHeight

기본값 0
크롭 박스의 최소 높이(px)

이미지 기준이 아닌 페이지 기준의 픽셀값

이벤트 관련 옵션 (Function 타입)

new Cropper(image, {
  ready() {
  },
  crop(event) {
  },
  zoom(event) {
  }
});

ready

Cropper가 초기화 완료된 직후 실행
(이미지가 준비되고 DOM에 렌더링된 직후)

cropstart

사용자가 크롭 박스를 처음 드래그하기 시작할 때 실행

cropmove

사용자가 크롭 박스를 이동하거나 크기 조절 중일 때 계속해서 실행

cropend

드래그를 마칠 때 실행

crop

크롭 박스가 변경될 때마다 실행되며, 크롭된 영역의 정보를 받아옴

zoom

사용자가 이미지에 줌인/아웃할 때 실행

메서드

이미지를 로딩하는 과정이 비동기(asynchronous) 이기 때문에, 대부분의 메서드는 ready 이벤트 이후에 호출

단, setAspectRatio, replace, destroy 메서드는 예외로 ready 이전에도 호출 가능

반환값이 없는 메서드는 this(cropper 인스턴스)를 반환하므로, 체이닝 방식으로 이어서 여러 메서드를 연속 호출 가능

new Cropper(image, {
  ready() {
    // 이미지가 준비되면 cropper 메서드 사용 가능
    this.cropper.move(1, -1); // 이미지를 우측 아래로 이동

    // 체이닝으로 여러 작업을 이어서 처리
    this.cropper.move(1, -1).rotate(45).scale(1, -1);
  }
});

crop()

크롭 박스를 수동으로 표시
autoCrop: false로 설정한 경우에 사용

new Cropper(image, {
  autoCrop: false,
  ready() {
    // 초기 작업 이후
    this.cropper.crop();  // 크롭 박스 표시
  }
});

reset()

크롭 박스를 제거 (이미지는 그대로 있음)

this.cropper.clear();

replace(url[, hasSameSize])

url 새 이미지의 URL (문자열)
hasSameSize (선택): Boolean, 기본값 false

현재 이미지의 src를 새 URL로 교체하고 Cropper를 다시 구성
hasSameSize를 true로 설정하면 사이즈 재계산 없이 URL만 교체됨
(필터만 적용하거나 동일 사이즈 이미지 교체 시 유용)

cropper.replace('new-image.jpg');              // 일반 교체
cropper.replace('new-image.jpg', true);        // 동일 사이즈 빠른 교체

enable()

크로퍼 기능을 활성화(해제)
이전에 disable()로 비활성화한 경우 다시 조작할 수 있게 만듦

disable()

크로퍼를 비활성화(잠금)
드래그, 리사이즈, 줌 등 모든 조작을 막습니다. 단, 시각적으로는 유지됨

destroy()

Cropper 인스턴스를 완전히 제거하고 이미지도 원래 상태로 복원

move(offsetX[, offsetY])

이미지를 상대 좌표(px) 만큼 이동

사용 예	설명
move(10)	오른쪽으로 10px
move(-10, 5)	왼쪽으로 10px, 아래로 5px
move(0, -20)	위로 20px

moveTo(x[, y])

캔버스(이미지 래퍼)를 절대 위치 (x, y) 로 이동
(y를 생략하면 x가 두 축에 모두 적용)

cropper.moveTo(100, 50);   // 왼쪽 100px, 위 50px 위치로 이동
cropper.moveTo(200);       // 좌표 (200, 200)로 이동

zoom(ratio)

상대적인 비율로 이미지 확대/축소
양수 → 줌 인
음수 → 줌 아웃

zoomTo(ratio[, pivot])

ratio Number (필수)
pivot { x: Number, y: Number } (선택)

cropper.zoomTo(1); // 원래 크기(100%)
cropper.zoomTo(0.5, { x: 150, y: 100 }); // 특정 위치 중심으로 50% 축소

rotate(degree)

이미지 상대 회전 (누적 회전)

cropper.rotate(90);    // 시계 방향 90도 회전
cropper.rotate(-45);   // 반시계 방향 45도 회전

rotateTo(degree)

cropper.rotateTo(180); // 180도 고정 회전

scale(scaleX[, scaleY])

이미지 좌우(X), 상하(Y) 방향으로 스케일/반전 적용

cropper.scale(-1);        // 좌우·상하 반전 모두
cropper.scale(-1, 1);     // 좌우 반전만
cropper.scale(1, -1);     // 상하 반전만

이 모든 기능은 CSS 2D 변형(transform) 기능을 사용하는 브라우저(IE9+)에서 지원

scaleX(scaleX)

이미지를 가로 방향(X축) 으로 스케일 조절
1 원본 유지
-1 좌우 반전
2 2배 확대 등

cropper.scaleX(-1);  // 이미지 좌우 반전

scaleY(scaleY)

이미지를 세로 방향(Y축) 으로 스케일 조절
-1 상하 반전
2 상하 2배 확대

getData([rounded])

기본값 false
최종 크롭된 영역의 정
rounded를 true로 하면 정수 값으로 반환

setData(data)

타입 Object
getData()로 얻은 데이터를 기반으로 크롭 영역의 위치 및 크기를 수동 설정할 수 있음
이 메서드는 viewMode가 1 이상일 때만 사용 가능

⚠️ 데이터를 넘기기 전에 정수로 반올림하기

cropper.setData({
  x: 50,
  y: 30,
  width: 200,
  height: 150,
  rotate: 0,
  scaleX: 1,
  scaleY: 1
});

getContainerData()

Cropper를 담고 있는 컨테이너 요소의 현재 크기(width, height) 정보를 반환

const containerData = cropper.getContainerData();
console.log(containerData);
// { width: 800, height: 600 }

getImageData()

이미지 자체의 위치 및 상태 데이터를 반환

{
  left: 이미지의 좌측 오프셋,
  top: 이미지의 상단 오프셋,
  width: 렌더링된 너비,
  height: 렌더링된 높이,
  naturalWidth: 원본 너비,
  naturalHeight: 원본 높이,
  aspectRatio: 가로세로 비율,
  rotate: 회전 각도,
  scaleX: 좌우 스케일,
  scaleY: 상하 스케일
}

getCanvasData()

이미지가 그려지는 캔버스(wrapper)의 위치와 크기 정보를 반환

{
  left: 캔버스의 좌측 위치,
  top: 캔버스의 상단 위치,
  width: 캔버스 너비,
  height: 캔버스 높이,
  naturalWidth: 원본 캔버스 너비 (읽기 전용),
  naturalHeight: 원본 캔버스 높이 (읽기 전용)
}

setCanvasData(data)

현재 크롭 박스의 위치와 크기를 가져옴

cropper.setCanvasData({
  left: 50,
  top: 30,
  width: 400,
  height: 300
});

setCropBoxData(data)

크롭 박스의 위치 및 크기를 수동으로 설정

cropper.setCropBoxData({
  left: 100,
  top: 50,
  width: 200,
  height: 200
});

getCroppedCanvas([options])

크롭된 영역을 기반으로 새로운 Canvas 엘리먼트를 생성

옵션	설명	기본값
width, height	출력 캔버스의 크기 지정	없음
minWidth, minHeight	출력 캔버스 최소 크기	0
maxWidth, maxHeight	출력 캔버스 최대 크기	Infinity
fillColor	투명 영역을 채울 색 (JPEG 저장 시 중요)	투명
imageSmoothingEnabled	이미지 보정 여부	true
imageSmoothingQuality	보정 품질: 'low', 'medium', 'high'	'low'
rounded	좌표 값을 반올림해서 사용할지 여부	false

const canvas = cropper.getCroppedCanvas({
  width: 300,
  height: 300,
  fillColor: '#fff', // JPEG로 저장 시 반드시 설정!
  imageSmoothingQuality: 'high'
});

저장 예시: 이미지 저장

이미지로 보여주기

document.body.appendChild(canvas);

Data URL로 저장

const dataURL = canvas.toDataURL('image/jpeg'); // or 'image/png'

canvas.toBlob((blob) => {
  const formData = new FormData();
  formData.append('cropped', blob);
  fetch('/upload', {
    method: 'POST',
    body: formData
  });
}, 'image/jpeg');

크롭 안 했으면 전체 이미지가 추출됨

캔버스 사이즈가 너무 크면 브라우저에서 블랙/빈 캔버스가 나올 수 있으니 maxWidth, maxHeight 설정 권장

JPEG 저장 시 fillColor를 지정하지 않으면 투명 영역이 검정색으로 나올 수 있음

zoom 이벤트에서 최대 줌 비율 제한도 성능상 추천

크롭된 이미지를 캔버스로 가져오기

cropper.getCroppedCanvas();

기본 설정으로 크롭된 이미지를 Canvas로 반환
반환값: HTMLCanvasElement
별도 옵션이 없을 경우, 현재 크롭 박스 영역이 그대로 캔버스로 생성

특정 크기로 캔버스 생성

cropper.getCroppedCanvas({
  width: 160,
  height: 90,
});

최소 및 최대 크기 제한 설정

cropper.getCroppedCanvas({
  minWidth: 256,
  minHeight: 256,
  maxWidth: 4096,
  maxHeight: 4096,
});

최소 256px, 최대 4096px 범위 내에서 캔버스 크기를 자동 조절
너무 크거나 작은 캔버스를 방지

고급 옵션 (배경색, 이미지 보정 설정)

cropper.getCroppedCanvas({
  fillColor: '#fff', // JPEG 저장 시 투명 영역을 흰색으로 채우기 위해 설정 (안 하면 검정색 나올 수 있음) 
  imageSmoothingEnabled: false, // 이미지 확대 시 부드럽게 보정되는 것을 끄는 옵션
  imageSmoothingQuality: 'high',// 보정 품질
});

setAspectRatio(aspectRatio)

cropper.setAspectRatio(1);     // 정사각형(1:1)
cropper.setAspectRatio(16 / 9); // 16:9 비율
cropper.setAspectRatio(NaN);   // 비율 제한 해제

setDragMode([mode])

String ('none', 'crop', 'move')
기본값 none

값	동작 설명
'none'	드래그 불가
'crop'	새 크롭 박스 생성 가능
'move'	이미지 이동 가능

Cropper 위에서 더블클릭하면 'crop'과 'move' 모드가 전환 (기본 기능)

이벤트

ready

이미지가 모두 로드되고, Cropper 인스턴스가 사용 준비 완료된 순간에 발생

let cropper;

image.addEventListener('ready', function () {
  console.log(this.cropper === cropper); // true
});

cropper = new Cropper(image);

cropstart

캔버스(이미지)나 크롭 박스를 조작하기 시작할 때 발생
예: 크롭 박스를 새로 만들거나, 크기 조절, 이동 등을 시작하는 순간

image.addEventListener('cropstart', (event) => {
  console.log(event.detail.originalEvent); // 원래 발생한 이벤트 객체 (pointerdown, mousedown, touchstart 등)
  console.log(event.detail.action);        // 어떤 작업인지 ('move', 'crop', 'se' 등)
});

event.detail.action 값 목록

값	설명
'crop'	크롭 박스 새로 생성
'move'	이미지 캔버스 이동
'zoom'	터치로 줌인/아웃
'e', 'w', 's', 'n'	동/서/남/북 방향 크기 조절
'se', 'sw', 'ne', 'nw'	대각선 방향 크기 조절
'all'	크롭 박스 전체 이동

cropmove

사용자가 조작 중일 때 계속 발생하는 이벤트

image.addEventListener('cropmove', (event) => {
  console.log(event.detail.action); // ex: 'move', 's', 'ne' 등
});

cropend

조작(이동, 리사이징, 줌 등)이 끝났을 때 발생

crop

이미지 캔버스나 크롭 박스가 변경될 때마다 발생
이 값들은 getData() 메서드의 반환값과 동일

속성	설명
x	크롭 영역의 왼쪽 위치 (원본 이미지 기준)
y	크롭 영역의 상단 위치
width	크롭 영역의 너비
height	크롭 영역의 높이
rotate	이미지 회전 각도
scaleX	X축 스케일
scaleY	Y축 스케일

autoCrop: true이면 ready 이벤트보다 먼저 crop 이벤트가 실행.
data 옵션으로 초기 데이터 설정 시에도 crop 이벤트가 선실행

zoom

이미지가 줌인 또는 줌아웃 될 때 발생

속성	설명
originalEvent	발생한 실제 이벤트 (wheel, touchmove, 등)
oldRatio	이전 줌 배율 (기존 canvas 비율)
ratio	새로운 줌 배율 (적용될 canvas 비율)

image.addEventListener('zoom', (event) => {
  const { oldRatio, ratio } = event.detail;

  if (ratio > oldRatio) {
    console.log('줌 인 중입니다');
    event.preventDefault(); // 줌 인 막기
  } else {
    console.log('줌 아웃 중입니다');
  }
});

활용 팁:
crop 이벤트로 실시간으로 크롭 위치를 표시하거나 서버로 데이터 전송 가능
zoom 이벤트로 최대 배율 제한, 줌 방지, UI 반응 처리 가능

해적왕

이전 포스트

canvas 그리기

다음 포스트

cropper.js

옵션

viewmode

dragMode

initialAspectRatio

aspectRatio

data

preview

responsive

restore

checkCrossOrigin

checkOrientation

modal

guides

center

highlight

background

autoCrop

autoCropArea

movable

rotatable

scalable

zoomable

zoomOnTouch

zoomOnWheel

wheelZoomRatio

cropBoxMovable

cropBoxResizable

toggleDragModeOnDblclick

minContainerWidth

minContainerHeight

minCanvasHeight

minCropBoxWidth

minCropBoxHeight

이벤트 관련 옵션 (Function 타입)

ready

cropstart

cropmove

cropend

crop

zoom

메서드

crop()

reset()

replace(url[, hasSameSize])

enable()

disable()

destroy()

move(offsetX[, offsetY])

moveTo(x[, y])

zoom(ratio)

zoomTo(ratio[, pivot])

rotate(degree)

rotateTo(degree)

scale(scaleX[, scaleY])

scaleX(scaleX)

scaleY(scaleY)

getData([rounded])

setData(data)

getContainerData()

getImageData()

getCanvasData()

setCanvasData(data)

setCropBoxData(data)

getCroppedCanvas([options])

저장 예시: 이미지 저장

크롭된 이미지를 캔버스로 가져오기

특정 크기로 캔버스 생성

최소 및 최대 크기 제한 설정

고급 옵션 (배경색, 이미지 보정 설정)

setAspectRatio(aspectRatio)

setDragMode([mode])

이벤트

ready

cropstart

cropmove

cropend

crop

zoom

canvas 그리기