Cropper.jsとは？ブラウザで画像を切り抜くJavaScriptライブラリ

ページ内ナビ

概要

Cropper.jsはブラウザ上で画像の切り抜きUIを構成するJavaScript/TypeScriptライブラリです。Cropperインスタンスが<cropper-canvas>・<cropper-image>・<cropper-selection>などのcustom elementを組み合わせ、選択範囲の移動・サイズ変更・出力を扱います。

特徴と向いている用途

公式資料に基づく紹介・実機未検証 · 内容確認日：2026-10-05

主な特徴

画像またはCanvasを渡してCropperインスタンスを作成する

new Cropper(element, options)へHTMLImageElement、HTMLCanvasElement、またはselector文字列を渡して初期化できます。既定templateにはcanvas、image、selection、grid、handle等が含まれます。

出典：[2]

selectionの位置・サイズ・aspect ratioをelement propertyで制御する

v2では切り抜き範囲を<cropper-selection>として扱い、x・y・width・heightやaspectRatioを通じて状態を制御します。複数のselectionの取得にも対応します。

出典：[2][3]

選択範囲を$toCanvasでCanvasへ変換する

v1のgetCroppedCanvas()に相当する処理は、v2では<cropper-selection>の$toCanvas()へ移っています。Canvasとして取得した後の画像formatや保存方法はアプリケーション側で選択できます。

出典：[3]

向いている用途

avatar・商品画像・投稿画像の切り抜きUIをブラウザ内で実装したい場合に向く

upload前の画像調整や編集画面で、利用者がselectionを直接操作して切り抜き範囲を決めるフロントエンドに適します。

出典：[1][2]

導入前の確認

v1からv2では多くのoption・methodがcustom element APIへ移行している

viewMode、dragMode、preview、getCroppedCanvas()など、v1で使われていたoption・methodの多くはv2で廃止または別elementのproperty/methodへ置き換わっています。既存コードの移行ではmigration guideの確認が必要です。

出典：[3]

Cropper.jsは切り抜きUIを提供し、画像保存先やserver処理までは担当しない

切り抜き結果はCanvas等としてapplicationへ渡されます。最終的な圧縮、upload、永続化、サーバー側の画像処理は利用側で設計してください。

出典：[2]

参考にした公式資料

[1]Cropper.js v2.2.0 package README(2026-10-05)
[2]Cropper.js v2.2.0 Cropper API(2026-10-05)
[3]Cropper.js v2 migration guide(2026-10-05)
[4]Cropper.js v2.2.0 package metadata(2026-10-05)
[5]Cropper.js v2.2.0 release(2026-10-05)

編集部からの補足

v2では従来の一枚岩APIから<cropper-selection>などの要素へ役割が分かれています。v1のgetCroppedCanvas()をそのまま持ち込まず、v2の$toCanvas()やselection propertyへ置き換える前提で評価すると移行差分を把握しやすいです。

3ステップで試す

1
Cropper.js 2.2.0を導入する
v2系の安定版を固定し、v1のAPIと混同しない状態で導入します。
npm install --save-exact cropperjs@2.2.0
2
画像要素からCropperを作成する
公式APIどおり、対象のHTMLImageElementをCropper constructorへ渡して切り抜きUIを初期化します。
import Cropper from 'cropperjs'; const image = document.querySelector('#image'); const cropper = new Cropper(image);
3
選択範囲をCanvasへ変換する
v2では旧getCroppedCanvas()ではなく<cropper-selection>の$toCanvas()から切り抜き結果を取得します。
const selection = cropper.getCropperSelection(); const canvas = await selection?.$toCanvas();

公式READMEで確認

成長

成長の推移 · 直近30日

13,902 Stars

推移データを蓄積中です。

開発アクティビティ

直近90日・週次

Commit（直近30日）: 24
Open PR: 0

開発アクティビティを蓄積中です。

Built with

カテゴリとタグ

GitHubデータ

GitHubのデータGitHubの詳細データを見る

GitHubで見る

GitHub Topics

image-cropper
image-processing
cropper
cropperjs
javascript

Stars: 13,902
Forks: 2,431
Watchers: 168
Open Issues: 7
Contributors: 44
所有者種別: User
主要言語: TypeScript
ライセンス: MIT
リポジトリ最終更新: 2026/10/04