imgAreaSelect

imgAreaSelect is a jQuery plugin for selecting a rectangular area of an image. It allows web developers to easily implement image cropping functionality, as well as other user interface features, such as photo notes (like those on Flickr).

Example

Click and drag on the image to select a rectangular area.

Selection coordinates:
X₁:
Y₁:
X₂:
Y₂:

Selection dimensions:
Width:
Height:

Want more examples?

Usage

Download the script, unzip it, and place it in the <head> section of your HTML document:

Then, to enable selection on an image, use the imgAreaSelect method:

The argument passed to the method is an options object. The available options are:

`aspectRatio`	a string of the form "width:height" which represents the aspect ratio to maintain example: `"4:3"`
`autoHide`	if set to `true`, selection area will disappear when selection ends default: `false`
`borderColor1`	selection border color default: `"black"`
`borderColor2`	selection border color default: `"white"`
`borderOpacity`	selection border opacity default: `0.5`
`borderWidth`	selection border width (in pixels) default: `1`
`classPrefix`	a string that is prepended to class names assigned to plugin elements (see below for details) default: `"imgareaselect"`
`disable`	if set to `true`, the plugin is disabled (the selection area remains visible, unless `hide` is also present)
`enable`	if set to `true`, the plugin is re-enabled
`handles`	if set to `true`, resize handles are shown on the selection area; if set to `"corners"`, only corner handles are shown default: `false`
`hide`	if set to `true`, selection area is hidden
`imageHeight`	true height of the image (if scaled with the CSS `width` and `height` properties)
`imageWidth`	true width of the image (if scaled with the CSS `width` and `height` properties)
`keys`	enables/disables keyboard support (see below for details) default: `false`
`maxHeight`	maximum selection height (in pixels)
`maxWidth`	maximum selection width (in pixels)
`minHeight`	minimum selection height (in pixels)
`minWidth`	minimum selection width (in pixels)
`movable`	determines whether the selection area should be movable default: `true`
`outerColor`	outer (unselected) area color default: `"black"`
`outerOpacity`	outer area opacity default: `0.2`
`parent`	a jQuery selector string that specifies the parent element that the plugin will be appended to default: `"body"`
`persistent`	if set to `true`, clicking outside the selection area will not start a new selection (ie. the user will only be able to move/resize the existing selection area) default: `false`
`resizable`	determines whether the selection area should be resizable default: `true`
`selectionColor`	selection area color default: `"white"`
`selectionOpacity`	selection area opacity default: `0`
`show`	if set to `true`, selection area is shown
`x1` `y1`	coordinates of the top left corner of the initial selection area
`x2` `y2`	coordinates of the bottom right corner of the initial selection area
`zIndex`	zIndex value to be assigned to plugin elements; normally, imgAreaSelect figures it out automatically, but there are a few cases when it's necessary to set it explicitly
`onSelectStart`	callback function called when selection starts
`onSelectChange`	callback function called when selection changes
`onSelectEnd`	callback function called when selection ends

The plugin creates several div elements that represent the selection area, the borders, the resize handles, and the outer (unselected) area. These elements have specific class names, so you can access them with jQuery selectors.

`imgareaselect-selection`	the selection area
`imgareaselect-border1` `imgareaselect-border2`	the selection border (there are two `div`s, one for each color)
`imgareaselect-handle`	the resize handles
`imgareaselect-outer`	the outer area, which is actually composed of four `div`s, all sharing the same class name

Additionally, with the classPrefix option, you can change the default imgareaselect class name prefix to something else. This might be useful when you have multiple plugins on one page.

Callback Functions

The callback functions (onSelectStart, onSelectChange, and onSelectEnd) are passed two arguments. First argument is a reference to the image, the second is an object representing the selection. The object has six properties:

`x1` `y1`	coordinates of the top left corner of the selected area
`x2` `y2`	coordinates of the bottom right corner of the selected area
`width`	selection width
`height`	selection height

Here's an example of a callback function that might be executed on selection end:

function selectionEnd(img, selection) { alert('width: ' + selection.width + '; height: ' + selection.height); }

Resetting Options Dynamically

If you call the imgAreaSelect method again with a new set of options, the new options are applied dynamically to the existing selection. For example, the following code could be used to implement a button that toggles the selection area on every click:

$('button#toggle').toggle( function () { $('img#example').imgAreaSelect({ show: true }); }, function () { $('img#example').imgAreaSelect({ hide: true }); } );

Keyboard Support

When the keys option is set to true, the selection area can be moved/resized using the keyboard. By default, the following keys are used:

arrow keys	move selection area by 10 pixels
`Shift` + arrow keys	move selection area by 1 pixel
`Ctrl` + arrow keys	resize selection area by 10 pixels
`Shift` + `Ctrl` + arrow keys	resize selection area by 1 pixel

You can override these key bindings by setting the keys option to an object that defines the desired key settings. The object may have the following properties:

`arrows`	defines the behavior of the arrow keys
`shift`	defines the behavior of the Shift key
`ctrl`	defines the behavior of the Ctrl key
`alt`	defines the behavior of the Alt key

Each of these properties can be set to the number of pixels (≥1) by which the selection area should be moved/resized when the specific key is pressed, or the string "resize", which indicates that the key should switch to resize mode. Example:

$('img#example').imgAreaSelect({ keys: { arrows: 15, ctrl: 5, shift: 'resize' } });

With these settings, pressing the arrow keys alone will move the selection area by 15 pixels, holding Ctrl will move the area by 5 pixels, and holding Shift will switch to resizing.

Known Issues

~~Move/resize cursors are not displayed correctly in Opera~~, and it seems to be a browser bug (thanks to Arjan Eising for input on this issue). Fixed in version 0.7

Download

imgareaselect-0.8.zip – a zip archive containing the plugin source and license files. Minified version included.

License

Dual licensed under the MIT and GPL licenses.

Links

imgAreaSelect on jQuery Plugins
PHP &jQuery image upload and crop tutorial at WebMotionUK

odyniec.net