> A lightweight, dependency-free image cropper with a responsive built-in UI for mouse, touch, and keyboard input.
## Features
- Works with existing `` elements and `` controls
- Responsive editor for desktop, mobile, tablets, and touchscreens
- Resizable crop selection with undo, redo, and reset controls
- JPEG and PNG output with configurable quality
- Built-in download button and custom callback buttons
- Customizable overlay, toolbar, and button colors
- No framework or runtime dependency
## Install
```sh
npm install js-crop
```
### Browser script
Load the minified file from a CDN. The constructor is exposed as `window.jsCrop`.
```html
```
To follow the latest published version instead of pinning a release:
```html
```
You can also serve `node_modules/js-crop/js-crop.min.js` from your own application.
### CommonJS
```js
const jsCrop = require('js-crop');
```
`js-crop` runs in a browser and requires DOM, canvas, `Image`, and `FileReader` APIs. If you bundle it on the server, create an instance only in the browser.
## Quick start
### Crop an uploaded image
```html
```
Selecting a file opens the crop editor automatically.
### Crop an existing image
```html
```
Clicking any matching image opens it in the editor. A selector may match one or many elements.
## API
```js
new jsCrop(selector, options?, customButtons?);
```
Creating an instance attaches listeners to every element that matches `selector`. The constructor returns the cropper instance; normal use does not require storing it.
### `selector`
Type: `string` (required)
Any selector accepted by `document.querySelectorAll()`. Matching elements can be:
- ``: opens the first selected file when the input changes.
- ``: opens the image when it is clicked.
- Another element with a `src` property: opens that source when the element is clicked.
```js
new jsCrop('#profile-photo');
new jsCrop('.croppable');
new jsCrop('input[type="file"][data-crop]');
```
### `options`
Type: `object` (optional)
| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `imageType` | `'png'` or `'jpeg'` | `'png'` | Output format used by downloads and callbacks. Values other than `'jpeg'` fall back to PNG. |
| `imageQuality` | `number` | `1` | Canvas export quality from `0` to `1`. It mainly affects JPEG output. |
| `saveButton` | `boolean` | `true` | Set to `false` to hide the built-in Download image button. |
| `customColor` | `object` | See below | Overrides colors in the editor UI. |
| `extButton` | `object` | None | Adds one callback button after the built-in controls. |
#### `customColor`
All color fields accept any valid CSS color value and are optional.
```js
new jsCrop('.crop-image', {
customColor: {
overlayBgColor: 'rgba(10, 10, 12, 0.98)',
toolbarBgColor: 'rgba(18, 18, 20, 0.84)',
buttonBgColor: 'rgba(255, 255, 255, 0.10)',
buttonFontColor: '#ffffff'
}
});
```
#### `extButton`
`extButton` is useful when you want the cropped result in application code instead of, or in addition to, the built-in download.
| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `callBack` | `function` | Required | Called with the cropped image data URL when the button is clicked. The button is only added when this is a function. |
| `buttonText` | `string` | `'ext'` | Button content. The value is inserted as HTML, so only use trusted content. |
| `buttonTitle` | `string` | `'Extension'` | Tooltip and accessible label. |
| `buttonCSS` | `string` | `''` | Inline CSS declarations appended to the button style, for example `'background:#2563eb;'`. This is not a class name. |
```js
new jsCrop('#avatar', {
saveButton: false,
extButton: {
buttonText: 'Save avatar',
buttonTitle: 'Save the cropped avatar',
buttonCSS: 'background:#2563eb;color:#fff;',
callBack: function (dataUrl) {
// dataUrl looks like: data:image/png;base64,...
document.querySelector('#preview').src = dataUrl;
}
}
});
```
Despite the historical callback examples calling this value `blob`, the library currently returns a base64-encoded data URL string from `canvas.toDataURL()`.
### `customButtons`
Type: `Array
```
Clicking any matching image opens it in the editor. A selector may match one or many elements.
## API
```js
new jsCrop(selector, options?, customButtons?);
```
Creating an instance attaches listeners to every element that matches `selector`. The constructor returns the cropper instance; normal use does not require storing it.
### `selector`
Type: `string` (required)
Any selector accepted by `document.querySelectorAll()`. Matching elements can be:
- ``: opens the first selected file when the input changes.
- `