Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/theodorejb/cropt
A lightweight JavaScript image cropper
https://github.com/theodorejb/cropt
avatar crop-image croppie profile-image
Last synced: 17 days ago
JSON representation
A lightweight JavaScript image cropper
- Host: GitHub
- URL: https://github.com/theodorejb/cropt
- Owner: theodorejb
- License: mit
- Created: 2023-11-04T23:01:02.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2024-10-24T14:10:19.000Z (20 days ago)
- Last Synced: 2024-10-24T16:20:22.365Z (19 days ago)
- Topics: avatar, crop-image, croppie, profile-image
- Language: TypeScript
- Homepage: https://theodorejb.github.io/cropt/
- Size: 6.05 MB
- Stars: 23
- Watchers: 4
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Cropt - lightweight JavaScript image cropper
Originally based on [Foliotek/Croppie](https://github.com/Foliotek/Croppie), but rewritten as a modern ES module with a simpler API, higher quality image scaling, and numerous other improvements.
Demo: https://theodorejb.github.io/cropt/
## Installation
```
npm install cropt
```
## Usage
1. Include the `src/cropt.css` stylesheet on your page.
2. Add a `div` element to your HTML to hold the Cropt instance.
3. Import Cropt and bind it to an image:
```javascript
import { Cropt } from "cropt";
let c = new Cropt(document.getElementById('demo'), options);
c.bind("path/to/image.jpg");
```
### Sizing
The Cropt boundary defaults to 320px wide and 320px high.
To customize this, override the `.cropt-container .cr-boundary` width and height via CSS.
## Options
### `mouseWheelZoom`
Type: `"off" | "on" | "ctrl"`
Default value: `"on"`
If set to `"off"`, the mouse wheel cannot be used to zoom in and out of the image. If set to `"ctrl"`, the mouse wheel will only zoom in and out while the CTRL key is pressed.
### `viewport`
Type: `{ width: number, height: number, type: "square" | "circle" }`
Default value: `{ width: 220, height: 220, type: "square" }`
Defines the size and shape of the crop box.
### `zoomerInputClass`
Type: `string`
Default value: `"cr-slider"`
Optionally set a different class on the zoom range input to customize styling (e.g. set to `"form-range"` when using Bootstrap).
## Methods
### `bind(src: string, zoom: number | null = null): Promise`
Takes an image URL as the first argument, and an optional initial zoom value. Returns a `Promise` which resolves when the image has been loaded and state is initialized.
### `destroy(): void`
Deconstructs a Cropt instance and removes the elements from the DOM.
### `refresh(): void`
Recalculate points for the image. Necessary if the instance was initially bound to a hidden element.
### `toCanvas(size: number | null = null): Promise`
Returns a `Promise` resolving to an `HTMLCanvasElement` object for the cropped image. If `size` is specified, the cropped image will be scaled with its longest side set to this value.
### `toBlob(size: number | null = null, type = "image/webp", quality = 1): Promise`
Returns a Promise resolving to a `Blob` object for the cropped image. If `size` is specified, the cropped image will be scaled with its longest side set to this value. The `type` and `quality` parameters are passed directly to the corresponding [HTMLCanvasElement.toBlob()](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/toBlob) method parameters.
### `setOptions(options: CroptOptions): void`
Allows options to be dynamically changed on an existing Cropt instance.
### `setZoom(value: number): void`
Set the zoom of a Cropt instance. The value must be between 0 and 1, and is restricted to the min/max set by Cropt.
## Visibility and binding
Cropt is dependent on its container being visible when the bind method is called. This can be an issue when your component is inside a modal that isn't shown. Consider the Bootstrap modal, for example:
```javascript
const cropEl = document.getElementById('my-cropt');
const c = new Cropt(cropEl, opts);
const myModal = document.getElementById('my-modal');
myModal.addEventListener('shown.bs.modal', () => {
c.bind("my/image.jpg");
});
```
If you have issues getting the correct result, and your Cropt instance is shown inside a modal, try taking it out of the modal and see if the issue persists. If not, make sure that your bind method is called after the modal finishes opening.
If a Cropt instance needs to be hidden and then re-shown, call the `refresh()` method to recalculate properties for the displayed image.
## Browser support
Cropt is tested in the following browsers:
* Firefox
* Safari
* Chrome
* Edge
Cropt should also work in any other modern browser using an engine based on Gecko, WebKit, or Chromium.
## License
MIT