Details
| Version | 1.2.1 |
|---|---|
| Last updated | 6th October 2009 |
| Requirements |
|
| Demo | View demo page |
| Links | |
| License | BSD License |
| Changelog |
|
About
The JavaScript image cropper UI allows the user to crop an image using an interface with the same features and styling as found in commercial image editing software, and is is based on the Prototype JavaScript framework and script.aculo.us.
Initially I performed quite a lot of searching for some ready made solutions to meet my requirements, but found none that had the complete feature set that I required or any complete versions based on Prototype.
So after a week and a half of work, I present the JavaScript image cropper UI, built on Prototype & script.aculo.us.
Features
![]()
- Un-obtrusive
- Based on Prototype and script.aculo.us
- Image editing package styling & functionality, the crop area functions and looks like those found in popular image editing software
- Dynamic inclusion of required styles
- Drag to draw areas
- Shift drag to draw/resize areas as squares
- Selection area can be moved
- Selection area can be resized using resize handles
- Allows dimension ratio limited crop areas
- Allows minimum dimension crop areas
- Allows maximum dimensions crop areas, if both min & max set as the same value then we'll get a fixed cropper size on the axes as appropriate and the resize handles will not be displayed as appropriate
- Allows dynamic preview of resultant crop (if minimum width & height are provided), this is implemented as a subclass so can be removed if not required
- Movement of selection area by arrow keys (shift + arrow key will move selection area by 10 pixels)
- All operations stay within bounds of image
- All functionality & display compatible with most popular browsers supported by Prototype, tested in:
- PC: IE 6 & 5.5, Firefox 1.5, Opera 8.5 (see known issues) & 9.0b
- MAC: Camino 1.0, Firefox 1.5, Safari 2.0
Usage
Extract to a directory of your choosing e.g. 'scripts/cropper/' and include the script and the required Prototype & script.aculo.us scripts:
-
<script type="text/javascript" src="scripts/cropper/lib/prototype.js" language="javascript"></script>
-
<script type="text/javascript" src="scripts/cropper/lib/scriptaculous.js?load=effects,builder,dragdrop" language="javascript"></script>
-
<script type="text/javascript" src="scripts/cropper/cropper.js" language="javascript"></script>
Options
- ratioDim obj
- The pixel dimensions to apply as a restrictive ratio, with properties x & y.
- minWidth int
- The minimum width for the select area in pixels.
- minHeight int
- The mimimum height for the select area in pixels.
- maxWidth int
- The maximum width for the select areas in pixels (if both minWidth & maxWidth set to same the width of the cropper will be fixed)
- maxHeight int
- The maximum height for the select areas in pixels (if both minHeight & maxHeight set to same the height of the cropper will be fixed)
- displayOnInit int
- Whether to display the select area on initialisation, only used when providing minimum width & height or ratio.
- onEndCrop func
- The callback function to provide the crop details to on end of a crop.
- captureKeys boolean
- Whether to capture the keys for moving the select area, as these can cause some problems at the moment.
- onloadCoords obj
- A coordinates object with properties x1, y1, x2 & y2; for the coordinates of the select area to display onload
The callback function
The callback function is a function that allows you to capture the crop co-ordinates when the user finished a crop movement, it is passed two arguments:
- coords, obj, coordinates object with properties x1, y1, x2 & y2; for the coordinates of the select area.
- dimensions, obj, dimensions object with properities width & height; for the dimensions of the select area.
An example function which outputs the crop values to form fields:
-
function onEndCrop( coords, dimensions ) {
-
$( 'x1' ).value = coords.x1;
-
$( 'y1' ).value = coords.y1;
-
$( 'x2' ).value = coords.x2;
-
$( 'y2' ).value = coords.y2;
-
$( 'width' ).value = dimensions.width;
-
$( 'height' ).value = dimensions.height;
-
}
Basic interface
This basic example will attach the cropper UI to the test image and return crop results to the provided callback function.
Minimum dimensions
You can apply minimum dimensions to a single axis or both, this example applies minimum dimensions to both axis.
Select area ratio
You can apply a ratio to the selection area, this example applies a 4:3 ratio to the select area.
-
<img src="test.jpg" alt="Test image" id="testImage" width="500" height="333" />
-
-
<script type="text/javascript" language="javascript">
-
Event.observe( window, 'load', function() {
-
new Cropper.Img(
-
'testImage',
-
{
-
ratioDim: {
-
x: 220,
-
y: 165
-
},
-
displayOnInit: true,
-
onEndCrop: onEndCrop
-
}
-
);
-
} );
-
</script>
With crop preview
You can display a dynamically produced preview of the resulting crop by using the ImgWithPreview subclass, a preview can only be displayed when we have a fixed size (set via minWidth & minHeight options). Note that the displayOnInit option is not required as this is the default behaviour when displaying a crop preview.
-
<img src="test.jpg" alt="Test image" id="testImage" width="500" height="333" />
-
<div id="previewWrap"></div>
-
-
<script type="text/javascript" language="javascript">
-
Event.observe( window, 'load', function() {
-
new Cropper.ImgWithPreview(
-
'testImage',
-
{
-
previewWrap: 'previewWrap',
-
minWidth: 120,
-
minHeight: 120,
-
ratioDim: { x: 200, y: 120 },
-
onEndCrop: onEndCrop
-
}
-
);
-
} );
-
</script>
Known Issues
- Safari animated gifs, only one of each will animate, this seems to be a known Safari issue.
- After drawing an area and then clicking to start a new drag in IE 5.5 the rendered height appears as the last height until the user drags, this appears to be the related to another IE error (which has been fixed) where IE does not always redraw the select area properly.
- Lack of CSS opacity support in Opera before version 9 mean we disable those style rules, if Opera 8 support is important you & you want the overlay to work then you can use the Opera rules in the CSS to apply a black PNG with 50% alpha transparency to replicate the effect.
- Styling & borders on image, any CSS styling applied directly to the image itself (floats, borders, padding, margin, etc.) will cause problems with the cropper. The use of a wrapper element to apply these styles to is recommended.
- overflow: auto or overflow: scroll on parent will cause cropper to burst out of parent in IE and Opera when applied (maybe Mac browsers too) I'm not sure why yet.
SEO Agency advanced JavaScript experience can enhance your site functionality. Adding the JavaScript Image Cropper is a good way to improve the user experience.
Next Steps
Feature Requests & Bug Reports
Please check the existing list of feature requests & bugs and the discussion list before posting requests or reporting bugs.
Leave a Tip
If you find this code useful you can leave a donation towards the continued development & support.
Comments
There have been 667 comments so far, join the discussion.
Pages: « 34 … 14 13 12 11 10 [9] 8 7 6 5 4 … 1 » Show All
180. Dan - 5th Mar 2007 - 3:33 pm
Or indeed (like graphic apps), getting a callback when the crop is double-clicked so we can perform a server crop function.
179. Dave - 5th Mar 2007 - 3:31 pm
Raanan:
It would be a fairly simple addition to make the cropper submit the form when a user presses enter, you should be able to make it some part of the callback etc. and just have an event observer on the cropper.
However thinking this through as I type my answer, you’d have to be sure that the user was interacting with the cropper and not with any other part of the page; if that is the sole role of your page (just cropping an image) then that would be fine. I don’t think this is something that I would add this to the release version because of that complexity (unless a few more people request the feature).
Hope that helps.
178. Raanan Avidor - 5th Mar 2007 - 2:30 pm
Hi.
Great app! Is there a way that when you hit Enter the crop will take place?
177. Dan - 2nd Mar 2007 - 11:55 am
I fixed most of my issues by removing all the tables, so the div for the image editing is on its own inside the body tag. If its any table cells it just doesnt work right and there are loads of different issues (white with grey, black, nothing appearing etc).
176. Dan - 2nd Mar 2007 - 11:27 am
Found an issue that I can reproduce on your imagepreview samples. If you turn off “displayOnInit: true, ” then the preview never appears.
175. Dan - 2nd Mar 2007 - 11:21 am
Great work Dave, brilliant. I have a little bug that I just cant figure out.
If i set minwidth/height or set displayoninit when i have set ratioDim then I get a black image and just the selection is 0 opacity but i get 50% opacity along the X-Axis. Basically anything above or below the selection is black.
I am using IE7 and the code I am using is virtually identical to your examples.
174. arginin - 1st Mar 2007 - 2:25 pm
Hello,
I work with the cropper. I want crop mutilple pictures on one page. Support the cropper that? On the Bug/Featurelist I found following entry:
00015 – Test with multiple croppers (see comment by Luis Bolson)
Where can I find the comment from Luis Bolson?
Thanks for help
173. Dave - 28th Feb 2007 - 10:23 am
Matt:
That’s a pretty sweet implementation, although I was a little confused with the second step (when making the thumbnail) until I realised what limits were in place on the dimensions.
I haven’t had chance to look at the code yet but there may be some features I might feed into the original, although I also had an idea to have a section which linked to customised versions of the script.
I’m glad you found it useful and hope it was fairly straight forward to customise to your needs.
172. Matt Barnicle - 28th Feb 2007 - 12:31 am
Made a mistake on my last post..
“disableCropPreview (boolean) – Only useful when displayOnInit is true”
should read:
“disableCropRedraw (boolean) – Only useful when displayOnInit is true”
171. Matt Barnicle - 28th Feb 2007 - 12:27 am
Hi Dave, everyone.. I’ve completed a proof of concept for my work. I made some additions to the cropper.js that may very well be useful to some people. First, an overview of what our app needed..
We needed an interface to upload a larger photo (gt or equal to 640×480), choose an area of the photo to scale down to 400×300 (could be the entire image uncropped), then take a selection of that scaled down image to make a thumbnail. That thumbnail has certain restrictions on it, and we needed more flexibility in the preview pane, so I had to add some things to the code…
So, I disabled the listener on the drag pane, per Dave’s suggestion (thanks Dave). And I added some config options as outlined below:
You can see a demo here:
http://gattomatto.net/work/jsCropperUI/
This demo includes backend PHP code that does the cropping and redisplays the cropped images. View the source to find the location of cropper.js which I modified to support these features.
Feel free to copy this file and offer any feedback on this. As this will be an important part of the code library on our site, I welcome critiques to make the code better.
– Matt
170. Dave - 27th Feb 2007 - 6:29 pm
Sommerschwede:
This is possible, but not out of the box. I have seen someone demo this and I believe it is somewhere in the comments.
169. Sommerschwede - 27th Feb 2007 - 5:53 pm
hello!
is there an way to have two or more Previews (ImgWithPreview) (differnt skalings/sizes) of one crop?
168. Bjarke - 26th Feb 2007 - 10:04 am
The problem only occurs in IE 7. In Firefox there is no problem! The flow is as follows:
I execute the LoadCropper-function, and the cropper works fine. I execute the LoadCropper-function again and picture goes all white. If I click inside the white area where the picture should be, it turns grey.
The Code:
var CropObject = null;
function LoadCropper()
{
if( CropObject == null )
{
CropObject = new Cropper.Img( ‘target-img’, { onEndCrop: onEndCrop } );
}
else
{
CropObject.remove();
CropObject = null;
CropObject = new Cropper.Img( ‘target-img’, { onEndCrop: onEndCrop } );
}
}
I hope this helps.
Best regards Bjarke
167. Dave - 25th Feb 2007 - 6:15 pm
All:
Sorry for the very late response to some of your posts and questions, I’ve been busier than usual lately.
Simon:
It is possible to change the aspect ratio without reloading the page, however you have to remove & re-add the cropper to do this.
Kristinn:
Thanks for your kind words about the cropper I’m glad it has proved helpful to you. Also thanks for the heads up on the little bug, I work with a cropper.js file and then the ANT scripts compress it for the release and rename the original to cropper.uncompressed.js – which is why I’ve never come across the bug.
Matt:
Thanks for your kind comments, you should easily be able to remove the ability to draw a new crop (resize in your case) area by removing the event listener on the drag pane. Can’t remember exactly without digging into the code, if you need any more help just ask.
Once again thank you all for your kind comments about the cropper.
166. Matt Barnicle - 24th Feb 2007 - 12:47 am
Great app, truly amazing.. I’ve been modifying it to adapt to our specific needs. I’m actually building an interface to use this as a resizer instead of a cropper. So it loads up the image inside of the dotted line interface and when you resize it, the image resizes with it. It’s working well, but I have one question I can’t figure out so far. Is there a way to disable the user from being able to draw another resize box? That would break the flow of our interface. Should be easy if I know what I’m doing, but I can’t seem to figure it out..
– Matt
165. Kristinn S. - 19th Feb 2007 - 7:55 am
First of all I would like to thank you David for this awesome plugin.
Though this might help someone…
While trying to make some changes to this plugin I changed the loaded script to cropper.uncompressed.js, and noticed that suddenly the cropper wasn’t working. Took me some time to notice that on line 356 there is a regular expression which only matches “cropper.js”, so for developers you might want to change line 356 & 357 to:
if( s.src.match( /cropper(\.uncompressed)?\.js/ ) ) {
var path = s.src.replace( /cropper(\.uncompressed)?\.js(.*)?/, ‘’ );
this will match “cropper.js” & “cropper.uncompressed.js”, which would make the stylesheet cropper.css load properly.
and thanks again for this, saved me TONS of work!
164. Rainer Schleevoigt - 13th Feb 2007 - 9:51 am
After realisation of a cropper in combination with convert http://familientagebuch.de/rainer/2006/50.html#5 we now finished a creater of USEMAPs with this technique (http://familientagebuch.de/rainer/2006/51.html#4). In future we plan to crop a polygon from a picture.
Rainer
163. amzad - 10th Feb 2007 - 11:35 am
using this DocType in my HTML page
Drag Drop
Not work in firefox
162. Simon - 2nd Feb 2007 - 10:17 pm
Nice! Is it possible to change aspect ratio, remove aspect ratio without reloading the page?
161. Markit - 27th Jan 2007 - 11:36 pm
This is an Excellent App, but I found a bug!
If you use the keypad to move the Boundbox, then onEndCrop is never executed unless you click on it afterwards
Leave a comment
No HTML please, only textile. For code please use [lang]...[/lang] tags (e.g. [html]...[/html] for HTML)