Guide · Open source
How to use smartcrop.js: install, crop images and tips
Updated · written with AI from the project's own documentation and checked against our catalogue data
Smartcrop.js is an open-source JavaScript library (MIT licence) that looks at an image and suggests the best rectangle to crop it to a given width and height. It can run in the browser, in Node, or through a command-line tool. This guide shows you how to install it, run a first crop, tune the options and avoid the common pitfalls.
smartcrop.jsjwagner/smartcrop.js · ★ 13k · MIT Install options & downloads Quick start
- 1Install the package. Make sure Node.js is available, then run npm install smartcrop in your project.
- 2Load an image. Get an image element or canvas that smartcrop can draw, and make sure it is served with CORS clearance if it comes from another domain.
- 3Call smartcrop.crop. Pass the image and an options object with the width and height you want.
- 4Read topCrop. Use the x, y, width and height values from result.topCrop to crop the image.
- 5Adjust options. Try minScale, boost and ruleOfThirds if the crop does not look right.
What smartcrop.js does and when to use it
Smartcrop.js analyzes an image and ranks candidate crops so that the interesting content stays in frame. It looks for edges, skin-like colors and saturated areas. The README describes the algorithm as fairly simple image processing, not a machine learning model.
It suits web developers who generate thumbnails from user-uploaded photos, and projects that need crops without sending images to a server. It is a poor fit where highly accurate subject detection is required, or where you need to crop large galleries on page load.
- Good fit: thumbnails from user uploads, crops done in the browser.
- Good fit: simple automatic cropping without a machine learning model.
- Poor fit: projects needing highly accurate subject detection.
- Poor fit: batch processing of large galleries on page load.
Install smartcrop.js with npm
The package-manager route needs Node.js, because the install runs through npm. You can also download smartcrop.js directly from the git repository instead of using npm.
- Prerequisite: Node.js (for npm install).
- Alternative: download smartcrop.js from the project's git repository.
npm install smartcropRun your first crop
Pass an image and the width and height of the crop you want. smartcrop.crop returns a promise. When it resolves, the result contains topCrop, which holds the x, y, width and height of the best crop in pixels.
Use that data to crop the image yourself. The library suggests the crop; it does not change the image for you.
smartcrop.crop(image, { width: 100, height: 100 }).then(function(result) {
console.log(result);
});Tune the options
The main cropOptions are width, height, minScale, boost and ruleOfThirds. Setting minScale to 1.0 prevents crops smaller than necessary, which lowers the risk of chopping things off. Setting ruleOfThirds to false turns off the rule of thirds composition weight.
The boost option takes an array of regions you want to favor, such as faces. Each region has x, y, width, height and a weight in the range [0, 1]. The impact of a boost is proportional to its weight and area.
- width and height: the size of the crop you want.
- minScale: set to 1.0 to avoid smaller-than-needed crops.
- boost: regions to favor, each with a weight from 0 to 1.
- ruleOfThirds: set to false to disable the rule of thirds weighting.
Add face detection to improve crops
The algorithm alone is simple, so the README suggests adding face detection so faces get priority. Face detection results can be passed in as boost regions. The README names tracking.js as the lighter choice for the browser; opencv.js is much heavier. It also notes that these libraries are based on the older Viola-Jones framework.
smartcrop-cli is cited as an example of how to integrate face detection.
- tracking.js: recommended by the README for the client side because it is small and simple.
- opencv.js: compiled from C++ and very heavy, according to the README.
- node-opencv: an option on the server side, with known issues noted in the README.
Use smartcrop.js in Node or from the command line
In Node you can use smartcrop through smartcrop-gm (ImageMagick via gm) or smartcrop-sharp (libvips via sharp). The smartcrop-cli project offers a command-line interface and can be read as an example of using smartcrop from Node.
- smartcrop-gm: uses ImageMagick via gm.
- smartcrop-sharp: uses libvips via sharp.
- smartcrop-cli: command-line interface to smartcrop.js.
Avoid CORS errors and browser limits
Browser origin rules apply to the image source. You may not use cross-domain images without CORS clearance, so host images on a domain you control or set up CORS headers. The README also says smartcrop requires Promise support, and recommends a polyfill for old browsers or setting smartcrop.Promise to another promise library.
Canvas support is documented by caniuse.com/canvas. The README says it is fine to run smartcrop on one image, but suboptimal to run it on an entire gallery on page load. Its benchmark reports under 20 ms to find a square crop of a 640x427px picture on an i7 machine, which is a rough figure from the author.
- Cross-domain images need CORS clearance.
- Promises are required; use a polyfill if needed.
- Run it per image rather than across a whole gallery on page load.
What people use it for
- Generating thumbnails from user-uploaded photos in the browser.
- Creating automatic crops for a slide show, as shown in the project's Ken Burns demo.
- Testing crop choices with your own images in the smartcrop.js testbed.
- Adding face regions as boosts so faces are kept in frame.
Frequently asked questions
How do I install smartcrop.js?
Run npm install smartcrop. The README says you can also download smartcrop.js directly from the git repository. Node.js is needed for the npm route.
Is smartcrop.js free to use?
Yes. The project is licensed under MIT, as listed on its repository page. Check the license file in the repository for full terms.
Why does smartcrop.js give a CORS error?
Browser origin rules apply to image sources. You cannot use cross-domain images without CORS clearance, so serve the image from a domain you control or configure CORS headers on the image server.
Does smartcrop.js use machine learning?
No. The README describes the algorithm as fairly simple image processing. The author notes that a machine learning version is in progress, but it is not what the current library uses.
Can I use smartcrop.js for face detection?
Smartcrop.js does not do face detection itself. The README suggests adding a face detection library such as tracking.js, then passing face regions in as boost options.
What are the alternatives to smartcrop.js?
The project lists comparable projects including dont-crop, smartcrop-sharp, smartcrop-cli and smartcrop.py. dont-crop avoids cropping altogether by padding images with matching gradients and colors.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use smartcrop.js if you are a web developer who needs simple, automatic, browser-side crops for thumbnails and do not want a machine learning model or a server. Pick something else if you need accurate subject detection, or if you plan to crop large galleries on page load or work with cross-domain images you cannot configure.
Install options & downloads