jquery.drag'n'crop

View the Project on GitHub lukaszfiszer/drag-n-crop

jquery.drag-n-crop

Build Status

A jQuery plugin for croping images by dragging, inspired by Facebook cover photo.

It aims to be minimalistic and very easy to use for the end-user. It allows to crop the image only in one dimension (no zooming!). A typical usecase would be to crop rectangular images into squares. If you search for a more advanced croping plugin, there are some other plugins available.

Quick demo!

jquery.drag-n-crop

Dependencies

Installation

  1. Include drag'n'crop JS and CSS files (+ and its dependencies, if you dont have them already) on your site. <script src='jquery.drag-n-crop.js'></script> (...) <link rel="stylesheet" href="jquery.drag-n-crop.css">
  2. Wrap the photo you want to crop in a element with desired width and height <div style="width: 200px; height:200px"><img src="/path/to/photo.jpg" id="photo"/></div>
  3. Initialize the plugin $('#photo').dragncrop();

jQuery drag'n'crop automatically resizes your photo.

API

jQuery.drag'n'crop is build using jQuery widget factory, providing a standard way of interacting with the plugin. It inherits all default options, events and methods but also provides some custom ones, described below:

Init options

You can customize behaviour of the plugin by passing an option object on initialization, example:

$('#photo').dragncrop({
  centered: true,
  overflow: true
});

Here's the complete list of available options

Options Description Default
position set initial position of the image (see position) undefined
centered center image in the container on init false
overflow show image oveflow when dragging false
overlay show oveflow with a semi-transparent overlay when dragging false
instruction show text instruction on image false
instructionText customize instruction text 'Drag to crop'
instructionHideOnHover hide instruction when hovering over image true

Position object

drag'n'crop provides a position object describing the coordinates of the image inside the container with the following structure

{
  offset : [x, y],
  dimension : [x, y]
}

Because jquery.drag'n'crop crops only in one dimension, only x or y changes for a given image - the second is always expected to be 0.

If you set the position (either via position option on init, or with move method), you must provide the coordinates in one of two formats. Example:

$('#horizontal-image').dragncrop({
  position: {offset: [1,0]} // position image on the right
});

Events

Event listener function are passed to the constructor in the same way as options. They are invoke every time an event is triggered. Example:

$('#photo').dragncrop({
  start: function() {
    console.log('Dragging started!!')
  }
});

Here's the complete list of events emitted by the plugin:

Event Description Arguments
start when dragging of the image started event, position
drag when dragging occures event, position
stop when dragging finished (user released the mouse button) event, position

Instance methods

Instance methods are invoked by calling the plugin function with the method name provided as a first argument followed by other arguments:

$("#photo").dragncrop('move', {offset:{[0,0.2]});

Available methods for drag'n'crop plugin:

Method Name Description Arguments Returns
move Move image programatically to the given position position undefined
getPosition retrieves the current position of the image none position
destroy Destroy and cleanup the plugin. none undefined

Examples

See http://lukaszfiszer.github.io/drag-n-crop/examples.html

Release History

0.1.0 - initial release