Media Plugin
GS Cropper
Image cropper with aspect ratios, zoom/rotate/flip, drag-pan, circular crop, a grid overlay and canvas/blob/dataURL export.
Install Package
npm i @get-set/gs-cropper
or via CDN
<link rel="stylesheet" href="https://cdn.get-set.it/gs-cropper/latest/gs-cropper.min.css"> <script src="https://cdn.get-set.it/gs-cropper/latest/gs-cropper.min.js"></script>
Interactive Playground
Live Sandbox
1
2
3
4
5
6
7
8
9
import Cropper from '@get-set/gs-cropper'; export default function App() { return ( <Cropper> <div className="content">Your Cropper content</div> </Cropper> ); }
Live Preview
Options
API Specifications
| Option | Type | Default | Description |
|---|---|---|---|
| reference | string | none | Reference. |
| src | string | none | Image source URL. Native reads an existing `<img src>` if omitted. |
| alt | string | none | Alt text for the image. |
| crossOrigin | '' | 'anonymous' | 'use-credentials' | none | Cross-origin attribute for the image (needed for tainted-free export). |
| aspectRatio | GSCropperAspectRatio | 'free' | Aspect ratio of the crop box. Default: 'free'. |
| initialAspectRatio | GSCropperAspectRatio | none | Initial aspect ratio applied only to the auto crop box. |
| circular | boolean | false | Circular (avatar) crop box + circular export mask. Default: false. |
| viewMode | GSCropperViewMode | 1 | Boundary mode (Cropper.js parity): 0 none · 1 crop box within canvas · 2 image covers box · 3 image covers canvas. Default: 1. |
| background | boolean | true | Show a repeating background grid behind a transparent image. Default: true. |
| responsive | boolean | true | Keep the cropper responsive on container resize. Default: true. |
| restore | boolean | true | Re-render (restore crop) on window resize. Default: true. |
| containerAspectRatio | number | none | Fixed container aspect ratio (canvas). Number = w/h. |
| autoCrop | number | false | 0.8 | Initial auto crop area as a fraction (0–1) of the canvas. `false` starts with no crop box (the whole image). Default: 0.8. |
| initialCrop | Partial<GSCropData> | none | Explicit initial crop rectangle in natural image pixels. Overrides autoCrop. |
| zoomable | boolean | true | Enable zooming (wheel + pinch). Default: true. |
| zoomOnWheel | boolean | true | Enable zoom on mouse wheel. Default: true (requires `zoomable`). |
| zoomOnPinch | boolean | true | Enable pinch-to-zoom on touch. Default: true (requires `zoomable`). |
| wheelZoomRatio | number | 0.1 | Wheel zoom sensitivity (ratio per wheel step). Default: 0.1. |
| minZoom | number | 0.1 | Minimum zoom scale (relative to fit). Default: 0.1. |
| maxZoom | number | 10 | Maximum zoom scale (relative to fit). Default: 10. |
| rotatable | boolean | true | Enable rotation. Default: true. |
| flippable | boolean | true | Enable horizontal/vertical flipping. Default: true. |
| rotateStep | number | 90 | Rotation step (deg) for keyboard / toolbar rotate. Default: 90. |
| draggable | boolean | true | Allow dragging the crop box across the image. Default: true. |
| movable | boolean | true | Allow moving/panning the image behind the crop box. Default: true. |
| pannable | boolean | true | Allow panning the image with a drag on the canvas. Default: true. |
| resizable | boolean | true | Allow resizing the crop box via its handles. Default: true. |
| handles | boolean | true | Toggle the crop-box resize handles. Default: true. |
| nudgeStep | number | 1 | Amount (px) the arrow keys nudge the crop box. Default: 1. |
| minCropWidth | number | 20 | Minimum crop-box width in px. Default: 20. |
| minCropHeight | number | 20 | Minimum crop-box height in px. Default: 20. |
| maxCropWidth | number | none | Maximum crop-box width in px. |
| maxCropHeight | number | none | Maximum crop-box height in px. |
| overlay | GSCropperOverlayType | 'dim' | Dimming style for the area outside the crop box. Default: 'dim'. |
| guides | GSCropperGuides | true | Show the rule-of-thirds / guide lines inside the crop box. Default: true. |
| center | boolean | true | Show a center indicator cross in the crop box. Default: true. |
| backdropType | GSCropperBackdropType | 'checkerboard' | Rich frame layer preset around the canvas. Default: 'checkerboard'. |
| toolbar | boolean | false | Show the built-in toolbar (zoom / rotate / flip / reset). Default: false. |
| theme | GSCropperTheme | 'auto' | Visual theme. `auto` follows prefers-color-scheme. Default: 'auto'. |
| accentColor | string | none | Accent color (CSS var --gsc-accent) for handles / focus ring. |
| rtl | boolean | false | Right-to-left layout. Default: false. |
| disabled | boolean | false | Disable the whole cropper (no interaction). Default: false. |
| reducedMotion | 'auto' | boolean | 'auto' | Honor prefers-reduced-motion. 'auto' | true | false. Default: 'auto'. |
| customClass | GSCropperCustomClass | none | Per-part class overrides. |
| className | string | none | Extra class name applied to the container root. |
| output | GSCropperOutputOptions | none | Default export options for getCroppedCanvas / getBlob / getDataURL. |
Technical Features
Aspect Ratios
Free, fixed or preset crop ratios.
Zoom / Rotate / Flip
Full transform control of the image.
Circular Crop
Round crop mask for avatars.
Multi Export
Canvas, Blob or dataURL output.