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:
HTML:
-
<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:
JavaScript:
-
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.
HTML:
Minimum dimensions
You can apply minimum dimensions to a single axis or both, this example applies minimum dimensions to both axis.
HTML:
Select area ratio
You can apply a ratio to the selection area, this example applies a 4:3 ratio to the select area.
HTML:
-
<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.
HTML:
-
<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 699 comments so far, join the discussion.
Pages: [1] 2 3 4 5 6 7 8 9 10 11 … 14 » Show All
1. Kiddi - 22nd May 2006 - 12:17 pm
WOW, thanks! Been looking for a free version of a online cropper that looks nice. Kudos!
2. chris - 22nd May 2006 - 10:02 pm
GREAT!!
looks very good :D
add a slider (timeline) with some markers, and you have a great tool for a JS-driven kenburns-creator :)
3. chris - 24th May 2006 - 12:34 pm
one question about the script:
is it possible to redraw the crop-box from outside?
i tried to call “setAreaCoords, cloneCoords, drawArea”, but no success…
(working on the timeline-”project” see above)
chris
4. Dave - 24th May 2006 - 1:45 pm
Chris:
I saw your original comment on the post yesterday and did a bit of research into the kenburns effect and thought that I could knock it up quite quickly (when I had some time), but didn’t have chance to reply to your post.
Although I designate these methods as being private you should be able to do:
myCropper = new Croper.Img( ...arguments... ); myCropper.setAreaCoords( { x1: 0, y1: 0, x2: 50, y2: 50 } ); myCropper.drawArea();The
method simply returns a clone of a coords object which has the
properties to allow you to use process same coordinates as another variable by value rather than by reference.
Hope that helps, if you have any more questions don’t hesitate to ask.
5. 1 Pixel Out » Blog Archive » Need a JavaScript image cropper UI? - 25th May 2006 - 3:58 pm
[...] This is one tool to bookmark if you’re thinking of building an image cropper into one of your apps. It’s built with the Prototype and script.aculo.us frameworks (which I strongly recommend by the way), it has plenty of configuration options and it feels very slick. I love how the UI is an exact implementation of what you get in Photoshop or any other commercial graphics package. Check the demo at Dave Spurr’s blog or read more about it on his doc page. [...]
6. kiwo - 31st May 2006 - 7:35 am
The cropper is great! Thanks.
There is only one thing that I can’t figure out. I need to change image’s src attribute using javascript. And when image changes, i need to setup cropper for new image with its new size and contents. How can i disable an existing cropper to be able to create a new one for a new image?
TIA, kiwo
7. Dave - 31st May 2006 - 7:28 pm
Kiwo:
Glad that you like the cropper. I’ve just spent a few minutes playing around with trying to get the image cropper to change the image dynamically; and I have to say that, currently, it’s not possible.
It is possible to apply a new cropper to a new image (or the same image but replaced) but there are a couple of errors that are related to the fact that the HTML that was added to the DOM for the cropper isn’t been removed.
I would have to work this in as a feature, but I’d like to know if this is feature that people would like to see added: to dynamically change the image within the cropper without reloading the page.
8. Stoyan - 2nd Jun 2006 - 9:22 am
but I’d like to know if this is feature that people would like to see added: to dynamically change the image within the cropper without reloading the page.
Yes, it would be nice to add a ‘zoom’ feature.
9. Stoyan - 2nd Jun 2006 - 9:52 am
It seems that area selection is not as smooth in IE as in Mozilla. IE recalculates something constantly and the ‘hour-glass’ appears at dragging.
10. Nick - 2nd Jun 2006 - 12:37 pm
Just great !!!!! That’s going to be a killer app !! Unique interface and features, no such analog for JS on the web !!! I’ll integrate it in the CMS I’m just working on.
Hope Dave is going to continue the development – adding new features and removing bugs.
11. Dave - 2nd Jun 2006 - 1:37 pm
Stoyan:
Can you expand on what you mean by a ‘zoom’ feature?
I think I know what IE is doing (it’s actually less obvious in IE 5.5 than IE 6), the thing is on the day that I launched I changed the entire way that the dark overlay is generated to improve performance on Mac based browser (Camino especially). I’m currently looking at the features requested by kiwo so I will also fix the IE performance issues as I believe I know what is going on there.
Nick: Thanks for the kind words, it’s nice to know that people like the cropper.
12. Stoyan - 2nd Jun 2006 - 3:18 pm
Hello Dave !!!
‘Zoom’ is wrong, I meant to fit the selected area to the image area, as it were ‘crop to mask’ (photoshop). On some software the cropped image is resized to the original image size, so it looks it’s ‘zoomed’.
These days I’ll intergate this nice app of yours with phpthumb, I could host a demo if someone wishes.
13. Nick - 3rd Jun 2006 - 11:11 am
1.1.0 – More tha good News. I’ll add a link to this site everywhere I use this tool from now on.
14. Nick - 3rd Jun 2006 - 11:16 am
Remove/reset cropper didn’t work on Firefox for me.
On IE – click ‘remove cropper’ and then ‘reset cropper’. The drag the select area – the crop values (co-ordinates) do not refresh.
15. Dave - 3rd Jun 2006 - 12:54 pm
Nick:
Thanks for pointing out the IE issues with the callback, version 1.1.1 that I’ve just uploaded should fix that problem.
As for your issues in Firefox, I’ve had no problems. Maybe it was a caching issue with the JavaScript, I’ve added something to the demo that should fix that if it was the case (or just do a hard refresh). But please tell me if you’re still having problems and whether it is within the demo or the test that comes with the download.
16. Nick - 3rd Jun 2006 - 1:33 pm
All works great, thanks for the quick fix. I’ll report the bugs if I find any.
17. Nick - 3rd Jun 2006 - 1:48 pm
I would like to repeat for all those who read this post- I have been searching for crop tool for months, this is the best solution, really the finest one ever- it works in Mozilla and IE ( the most used browsers) and it can be easilly integrated. There is only one other such feature-rich and bugfree tool, but it’s in Java and it is not free.
18. Andy Skelton - 8th Jun 2006 - 10:25 pm
Howdy and thanks for the great tool! I am struggling with the ratios (when GCD is too low it breaks completely) and about to work up a patch.
Dave, if you already have something in the works please let me know.
19. Andy Skelton - 8th Jun 2006 - 11:12 pm
I have a modified version of applyRatioToAxis that handles ratios more smoothly, without the jumping effect I was seeing, regardless of their common divisors. It alleviates the need for GCD calculation. Hopefully the resultant ratio is within an acceptable margin of error. Now we can push this feature out on WordPress.com! ;-) Thanks again for the great work.
20. Mike - 9th Jun 2006 - 2:31 am
“I’d like to know if this is feature that people would like to see added: to dynamically change the image within the cropper without reloading the page.”
Yes please! I’m working on a PHP web app with a form where a user uploads several jpegs, and I want to immediately let the user crop them to a 150×150 square – before submitting the final form.
What I’ve done (tell me if I’m doing this all wrong) is made a page with several input type=’file’ form elements, hooked up the submit button to submit to an invisible iframe that moves the file into place after upload, updates the src=’’ of the image tag, then tells the parent document to display the div containing the cropper. Thus, you upload, crop, save, and move on to the next image, all on the same page.
Anyway, to do this I need to be able to change the img src=’’ of the cropper on the fly.
21. Mike Burrell - 12th Jun 2006 - 9:40 am
First off, great script!!
I setup your cropper GUI onto my dev site, and am passing the x1, y1, x2, y2, width, height vars to hidden form fields which are then passed to my PHP script below when the form is submitted.
The final photo is cropped, however I am obviously off somewhere as the cropped image isn’t exactly correct. (It appears slightly smooshed and is off a few pixels possibly.)
Any ideas on what I am doing wrong here would be greatly appreciated!!
My PHP script below:
22. Francis - 12th Jun 2006 - 4:22 pm
Do you have an idea why do I can’t see the image
(sorry for my bad english)
Thx
23. Francis - 12th Jun 2006 - 4:25 pm
Can you tell me why I can’t see the image?? It was working well before…
http://eleves_tim.cmaisonneuve.qc.ca/e0368657/help.jpg
24. Andrew Okonetchnikov - 16th Jun 2006 - 1:33 pm
Great work! Thanks!
Take a look also on my JS “ModalBox” component here: http://okonet.ru/projects/modalbox/
Maybe you’ll have some suggestions too. Thanks again!
25. Jake - 19th Jun 2006 - 5:10 pm
This is the coolest script on the web since…, well, probably ever! It works so smoothly and beautifully and has saved me hours and hours of time.
Thought you should know, the cursor for the western handle is set to “e-resize” when you probably want “w-resize”.
26. Georgi Kostov - 20th Jun 2006 - 6:22 am
Very good code. I’m really impressed. I need to use it and I’m concerned about the license for using the code as it will probably go into a commercial app.
27. Aron - 27th Jun 2006 - 2:23 pm
Has anyone made a ASP or C# script that actually crops the image?
I see the PHP script above, I may just make the .net version.
28. Dave - 29th Jun 2006 - 8:28 pm
All:
Sorry for the late response to all of your comments, I’ve been away on holiday and have only just recently returned.
Mike:
I’ve not got around to implementing the server side part of the cropper yet, but when I do I’ll make them (CF & PHP) available here. Looking at your script I can’t see any problems, can you email me more details & some example screen shots/code.
Francis:
Do you have more information, browser version etc. or a live example URL, also what do you mean by it was working well before, is this since an upgrade to a newer version of the cropper UI?
Jake:
Thanks for the kind words on the cropper… I may just use that as a pull out quote one day. Also thanks for the heads up on the resize handle cursor problem, I’ve amended it and it will be in the next release.
Georgi:
The BSD License allows proprietary commercial use, and for the software released under the license to be incorporated into proprietary commercial products, but the copyright must be retained and all conditions met. If you do use it in a commercial piece of software that is successful to some degree then it might be good karma to leave an appropriate donation.
Either way keep in touch and if you could give me a heads up with what you’re using it in that’d be great, it’s nice to see your work out in the wild.
Andrew:
Again, thanks for the kind words on the cropper. I had a quick peek at the ModalBox demo on your page and it looks pretty sweet, good luck with it, I also quite liked the design of the pages – although it took me a few seconds to find the demo link.
Aron:
As I said above I haven’t got around to implementing the server side parts of the cropper I had planned to completment the UI, but when I do I will only be implementing them in CF & PHP. If you create a .Net version of the server side part and wish to release it then I’ll link to it from here if you wish.
Phew, that was quite a bit to catch up on… now to sort out my email…
29. John - 2nd Jul 2006 - 12:02 pm
Nice work!
well, if you could add two buttons to zoom in/out background image, it would be perfect!
30. Robert - 3rd Jul 2006 - 10:38 pm
Great work. I wonder how did you manage to do this in 1 and 1/2 weeks…
Here is my problem: I am trying to implement your cropper in C# .NET. My image (to be cropped) is inside Panel object (which is actually DIV element 400×400px) and if image is bigger then DIV element then I have scroll bars. If I move these scrollbars then drawing of the crop area doesn’t work properly. And error is actually the offset for which I moved the scroll bar. I guess I need to compensate for this movement. Where in your code I need to add these values: vertical and horizontal offset? Is there quick solution to my problem?
Second question is… what is the minimum required for cropper UI to work. Are all those JS files necessary. I am asking because I deleted some of them and everythig was still working fine. (I only need basic cropping functionality)
Thanks.
31. Robert - 5th Jul 2006 - 3:07 pm
OK, I did some reading on script.aculo.us. Please, disregard my second question. :-)
32. Stoyan - 6th Jul 2006 - 5:42 pm
Press the ‘Remove Cropper’ buton twice on IE and the image dissapears !
I want also to reset the coordinates on ‘Cropper Remove’ how to do that ?
33. Stoyan - 8th Jul 2006 - 5:56 am
Is it possible to define default selected area (wich appears oninit), without using area ratio ?
34. nation-x - 10th Jul 2006 - 3:41 pm
I looked at the cropper.js until my head hurt. :) I need to know how to do this… Let’s say I have an image that is 1000×1100… what I would like to do is set the width attribute of the testImage to 500px and crop by aspect ratio with a minimum width and height of 120px. How can I accomplsh this using this cropper? Can I get some help with this? I would greatly appreciate it.
35. bala - 10th Jul 2006 - 4:04 pm
Image Cropper features are good, but i need dynamic feature to upload and crop and update the server image with crop image. How I will do this? Guide me
36. Uberdoer - 10th Jul 2006 - 5:59 pm
Stunning. Well done Dave. You’ll be getting a donation from me for sure!
A few more examples would be good, including a bit on resetting and removing a previous crop region.
37. Dave - 10th Jul 2006 - 9:20 pm
All:
Thanks for your continued kind comments. I’ve also started up a private bug/feature request list for the cropper due to the huge ammount of interest in it, these I will assign priority as I deem fit or based on demand.
John:
I can kind of see the point in having a zoom function, but I can’t see it being worth the overhead to the script at the moment. Maybe if I get more requests in the same vein.
Robert:
“Great work. I wonder how did you manage to do this in 1 and 1/2 weeks…” Erm dedication and doing little else other than this in the majority of my spare time, I wouldn’t like to count the hours I spent on it, but if I were to put standard 9-5 working days against it I’d say 3 or 4 days max. So it’s not that bad, it’s always easier when you get into a groove with something like this.
As for your first question, the cropper doesn’t take scroll offsets into account, you should be able to tweak it quite easily to account for those. I have added this to the feature request list.
Stoyan:
Thanks for the heads up on the ‘remove cropper’ bug, and the feature request, which I’ve added to my list.
Nation-x:
I’m sorry the JavaScript made your head hurt, I feel the uncompressed one is fairly heavily commented and should give good pointers as to what does what. As for your feature request I’m not quite sure what you require, is it that you have a maximum area for the cropper UI (500×500) and any image larger than this would need to be resized? This will make cropping a little different as you’d have to work out the ratio of the cropper to the resized image, but it is do-able. If you clarify your requirements I may add it to the feature request list.
Bala:
At the moment this is just the JavaScript UI, I do have plans to develop the server-side part of a cropping tool & release this, but I’m not sure when I can squeeze that in.
Uberdoer:
Thanks for your very kind comment. I don’t know how much further I can take the examples – I have multiple live ones and the download comes with 6 different examples, or would you just like to see a couple of tutorial like examples?
38. nation-x - 11th Jul 2006 - 1:13 am
Sorry… I wasn’t trying to say anything bad about the javascript. :) It’s awesome… I just haven’t been working with javascript for awhile.
What I asking about is using aspect ratio for the cropper when the cropper UI has a maximum width of 500px (as an example) but the image is 1000px. handling the thumbnail isn’t an issue. If I am using a minimum width and height (say 120×120) then when I crop the image I can just crop the selected area and then resize the thumb to 120×120. What I noticed is that the preview window is actually showing the correct representation of what I have selected but the cropper UI is showing the large image in the selection. I suppose I could resize the image first before it’s displayed in the cropper UI, but I was hoping that it could just be done without resizing. I think the key is to use the image from the preview area inside of the selection but I am a PHP developer and haven’t worked with javascript in years… and your javascript isn’t simple… it would take me a month to know it intimately enough to modify it to do what I need… lol.
On the other side of that… I am more then willing to chip in the PHP to crop the images. :) I have a sweet class I put together from a couple of different sources. You can see it here. http://php.amnuts.com/forums/viewtopic.php?t=253
39. Bane - 14th Jul 2006 - 9:58 am
This is really great and usefull tool!
I have just one question, if you set minimum height and width than crop area is constrained to that ratio. Is it possible to set both minimum height and width without having constrained crop area?
40. Adam Roth - 17th Jul 2006 - 4:25 am
I tried to call cropper.setAreaCoords(...), and cropper.drawArea(...) as mentioned above, but I end up getting $( this.overlay ) has no properties. Any ideas? I need to draw the cropping box based on previously saved cropping coordinates.
41. Adam Roth - 17th Jul 2006 - 4:28 am
...or better yet, can I pass in starting coordinates for the cropping box when creating the cropping obj?
42. Neil - 18th Jul 2006 - 2:51 pm
I’ve taken the example and thrown a wrapper div around it, gave it a width, relative position and margins and the selector goes a bit wacky.
http://www.susan-deaux.com/z/cropper/tests/example-Preview.htm
43. Neil - 18th Jul 2006 - 3:00 pm
After playing a bit more it seems that the wrapper’s position: relative is giving the cropper the most problems.
44. Dave - 19th Jul 2006 - 8:05 pm
Nation-x:
Thanks, that script looks quite good, some of it I’ve seen before and am already using in some areas. Your other request has been added to the feature/bug list.
Bane:
I’ve added the ability to set minimum dimensions without applying a ratio constraint to the feature request list.
Adam:
That error sounds like you are trying to call the methods before the cropper has been attached. It should work for you once it’s attached, I’ve added your request of being able to set cropper dimensions & position on init to the feature request list.
Neil:
The wrapper needs to have a relative position as the select area etc. are all then positioned absolutely within that container, I’ve added extra testing of things like placing other wrappers around the cropper with different positioning, margins & padding etc. the bug list.
45. Reynold - 24th Jul 2006 - 3:54 am
Hey this is a great script. Just wondering when the image gets so large (say above 2000), it would be nice if I could instead crop a zoomed version of the image. I just tried with this cropper and , however, it doesn’t seem like the zoomed one. Instead, the script displays the original size image in the cropper window.
46. Dave - 24th Jul 2006 - 7:24 pm
Just a quick note to say that I’ve added a link to the list of feature requests & bugs for the image cropper. These are all areas I intend to address at some point, note they are not in priority order.
47. bala - 25th Jul 2006 - 8:26 pm
Can you tell me how to upload that cropped image into the server in ASP?
48. Skylog » Blog Archive » links for 2006-07-27 - 27th Jul 2006 - 6:28 am
[...] JavaScript Image Cropper UI, using Prototype & script.aculo.us (tags: javascript) [...]
49. aNieto2K - » Prototype JavaScript Image Cropper UI - 29th Jul 2006 - 3:19 pm
[...] Se trata solo de una demo, pero no deja a nadie indiferente el poder de prototype y lo que podemos llegar a hacer usando una librerÃa tan completa como pesada como script.aculo.us. Sin duda las aplicaciones web están cambiando y cada dÃa más y pasos más agigantados. Esto es una muestra de ello. [...]
50. Adam Roth - 31st Jul 2006 - 9:10 pm
I’d like to set another callback when I double click on the cropping area (which would then make the AJAX call to the server). Does the cropper currently support this functionality? Might it?
Leave a comment
No HTML please, only textile. For code please use [lang]...[/lang] tags (e.g. [html]...[/html] for HTML)