Skip to content
Get packs

smartcrop.js

A JavaScript library that picks a sensible crop point in an image, for browsers and Node.js.

GitHub Download v2.0.5
Stars
13k
Forks
571
Licence
MIT
Language
JavaScript
Last update
2.6 years ago
Type
Library

No commits in over a year — check for forks or alternatives before adopting.

What it is

Smartcrop.js is a JavaScript library that analyzes an image and suggests the best rectangle to crop it to a given width and height. It looks for edges, skin-like colors, and saturated areas, then ranks candidate crops so the interesting content stays in frame. It can run in the browser, in Node, or through a command-line tool.

  • Generate square or fixed-size thumbnails from photos on a website
  • Create Ken Burns style slideshow transitions, as shown in the README demos
  • Test crops on your own images with the included testbed page
  • Pick a crop in Node.js using smartcrop-gm or smartcrop-sharp

Great for

  • Web developers who generate thumbnails from user-uploaded photos
  • Developers who want simple automatic cropping without a machine learning model
  • Projects that run in the browser and need crops without sending images to a server
  • Developers who want to add face detection to improve crop choices

Not ideal for

  • Projects needing highly accurate subject detection, since the README describes the algorithm as fairly simple image processing and the author notes a machine learning version is still in progress
  • Batch processing of large galleries on page load, because the README advises it is suboptimal for that
  • Teams needing cross-domain images without CORS setup, because browser origin rules apply to image sources
Step-by-step guide: how to use smartcrop.jsInstall, first run, examples, tips and FAQs

How to get it

  1. 1

    Install with a package manager

    You'll need: Node.js (for npm install)

    Install from npm

    npm install smartcrop
  2. 2

    Run it

    • Install the package with npm install smartcrop, or download smartcrop.js from the repository
    • Load an image in the browser or Node.js environment
    • Call smartcrop.crop(image, { width: 100, height: 100 }) with your target size
    • Read result.topCrop from the promise to get x, y, width, and height
    • Use those values to crop the image with your own drawing or image code
  3. 3

    Get the most out of it

    • Add face detection through a library such as tracking.js, using the boost option to give faces more weight
    • Set minScale to 1.0 to avoid crops smaller than needed and reduce the risk of cutting off content
    • Turn off the rule of thirds weight with ruleOfThirds: false if you prefer centered compositions
    • Use the testbed demo to compare results on your own images before choosing settings
    • For Node.js, use smartcrop-gm or smartcrop-sharp depending on whether you prefer ImageMagick or libvips

Downloads

Source code (.zip)main branch · straight from GitHubRelease v2.0.5Release notes and sourceOfficial website & docs29a.ch/2014/04/03/smartcrop-content-aware-image-cropping

Strengths

  • Small, short codebase that the README says can be reviewed quickly
  • Runs in browsers and Node.js, with CommonJS, AMD, and global module support
  • Simple promise-based API: pass an image and a width and height

Trade-offs

  • Based on basic image processing rather than modern machine learning, so results may miss the true subject in some images
  • Needs a Promise implementation in older browsers, and face detection requires adding a separate library
  • The README notes the project is a small personal project, so maintenance expectations should be modest

How it compares

ProjectStarsTypeLevelUpdatedBest for
smartcrop.js (this)13kLibrarybeginner2.6 years agoWeb developers who generate thumbnails from user-uploaded photos
cropperjs13.9kLibraryintermediate21 days agoWeb developers adding image cropping to a site or web app
filepond16.4kLibraryintermediate9 days agoWeb developers who need a polished upload widget in a site or app
caire10.9kCLIintermediate7 days agoDevelopers who need to resize images inside a Go program
supervision51.5kLibraryintermediate4 days agoPython developers building apps on top of object detection or segmentation models
albumentations15.3kLibrarybeginner1.4 years agoMachine learning engineers training image classification or segmentation models with limited data

Stats synced from GitHub. The assessment above was drafted with AI from the project's README on 2026-10-29 and may miss recent changes — check the README before relying on a command. MIT licence: free to use, modify and distribute, including commercially, as long as you keep the copyright notice.