7 days of WordPress plugins, themes & templates - for free!* Unlimited asset downloads! Start 7-Day Free Trial
  1. Code
  2. Web Development

How to Create a jQuery Image Cropping Plugin from Scratch - Part I

Scroll to top
Read Time: 15 mins

Web applications need to provide easy-to-use solutions for uploading and manipulating rich content. This process can create difficulties for some users who have minimal photo editing skills. Cropping is one of the most used photo manipulation techniques, and this step-by-step tutorial will cover the entire development process of an image cropping plug-in for the jQuery JavaScript library.

Step 1. Setting Up The Workspace

First, we are going to set up our project workspace for this tutorial. Begin by creating a hierarchy of directories and empty files named as exemplified in the image below:

Directory tree

Next, you'll need to download the jQuery JavaScript library and place it inside the /resources/js/ folder. The image used in this tutorial must be named example.jpg and placed inside the /resources/images/ folder. You can use this image (thanks to gsso-stock), provided with the source files of this tutorial, or one of your own. And the last file is the outline.gif file, which must be placed inside the /resources/js/imageCrop/ folder.

Step 2. Creating The Test Page

To test our plug-in, we'll need to attach it to an image. Before starting to work at it, we'll create a simple page containg that image.


Open up the index.html file in your favorite text editor and write the following code.

There's nothing fancy here: just plain HTML code. We have loaded a stylesheet for the page, jQuery, our plug-in files (which are currently empty) and placed an image inside the document.


Now edit style.css as shown above.

We've customized the aspect of our page by changing the background color and adding some basic styling to the title and image.

Step 3. Writing A Basic jQuery Plug-In

Let's begin by creating a basic jQuery plug-in.

"Learn more about how to write your own plug-in, via this post. It outlines the basics, best practices and common pitfalls to watch out for as you begin writing your plug-in."

Open /resources/js/imageCrop/jquery.imagecrop.js and add the following code.

We have just extended jQuery by adding a new function property to the jQuery.fn object. Now we have a very basic plug-in that iterates over each object and attaches imageCrop when the object is loaded. Note that the cached images don't fire load sometimes, so we reset the src attribute to fix this issue.

Step 4. Adding Customizable Options

Allowing for customization options makes a plug-in far more flexible for the user.

We have defined an array with the default options, then merged them with the custom options by calling the setOptions function. Let's go further and write the body of this function.

The $.extend() function merges the content of two or more objects together into the first object.

The Options

The following list describes each option of the plug-in.

  • allowMove - Specifies if the selection can be moved (default value is true).
  • allowResize - Specifies if the selection can be resized (default value is true).
  • allowSelect - Specifies if the user can make a new selection (default value is true).
  • minSelect - The minimum area size to register a new selection (default value is [0, 0]).
  • outlineOpacity - The outline opacity (default value is 0.5).
  • overlayOpacity - The overlay opacity (default value is 0.5).
  • selectionPosition - The selection position (default value is [0, 0]).
  • selectionWidth - The selection width (default value is 0).
  • selectionHeight - The selection height (default value is 0).

Step 5. Setting Up The Layers

On this step, we'll modify the DOM to get prepared for the next step: the plug-in's interface.

Layers overviewLayers overviewLayers overview

First, we'll initialize the image layer.

Now initialize an image holder.

As you can see, the holder layer has the same size as the image and a relative position. Next, we call the .wrap() function to place the image inside the holder.

Above the image will be the overlay layer.

This layer is the same size as the image, but also has been given absolute positioning. We get the value for the opacity from the options.overlayOpacity and let jQuery apply it. This element has also an id, so we can change its properties through the plug-in's stylesheet. At the bottom, we call the .insertAfter() method to place the overlay layer right after the image.

The next layer is the trigger layer; we'll place it after the overlay layer, just as we did with the previous ones.

The background color doesn't really matter but it must be different than transparent (which is by default). This layer is invisible from the user but it will handle some events.

We'll place the outline layer above the trigger layer.

And finally the last layer.

The .attr() method returns the value of a specified attribute. We used it to get the image src, and set it as the background for the selection layer.

Absolute Positioning Inside Relative Positioning

You might already know this, but an element with a relative positioning provides you with the control to absolutely position elements inside of it. This is why the holder layer has a relative position and all of its children an absolute position.

An excellent explanation of this trick is covered in this article.

Step 6. Updating The Interface

First, we'll initialize some variables.

The selectionExists will inform us if a selection exists. The selectionOffset will contain the offset relative to the image origin, and the selectionOrigin will indicate the origin of the selection. Things will be much more clear after a few steps.

The following conditions are required if the selection exists when the plug-in is loaded.

Next we'll call the updateInterface() function for the first time to initialize the interface.

We'll write the body of this function shortly. Right now, let's take care of our first event.

We call .mousedown() if options.allowSelect is true. This will bind an event handler to the mousedown event of the trigger layer. So, if a user clicks the image, the setSelection() will be invoked.

The first function, getElementOffset(), returns the left and top coordinates of the specified object relative to the document. We've retrieved this value by calling the .offset() method. The second function, getMousePosition(), returns the current mouse position, but relative to the image position. So, we'll work with values that are only between 0 and the image width/height on the x/y-axis, respectively.

Let's write a function to update our layers.

This function checks the value of the selectionExists variable, and determines if the overlay layer should be displayed or not.

The updateTriggerLayer() function changes the cursor to crosshair or default, depending on the options.allowSelect value.

Next, we'll write the updateSelection() function. It will update not only the selection layer, but the outline layer as well.

First, this function sets the properties of the outline layer: the cursor, the display, the size and its position. Next comes the selection layer; the new value of the background position will make the images overlap seamlessly.

Now, we need a function to update the cursor when needed. For example, when we make a selection, we want the cursor to remain a crosshair no matter which layer we are over.

Yes, it's as simple as it looks. Just change the cursor type to the specified one!

And now, the last function of this step; we need it to update the plug-in's interface in different situations - on selecting, on resizing, on releasing the selection, and even when the plug-in initializes.

As you can see, the updateInterface() function filters some cases and calls the necessary functions we've just written.

Step 7. Setting The Selection

Up until now, we took care of the customization options and the interface, but nothing related to how the user interacts with the plug-in. Let's write a function that sets a new selection when the image is clicked.

First, the setSelection function calls two methods: event.preventDefault() and event.stopPropagation(). This prevents the default action and any parent handlers from being notified of the event. The .mousemove() method binds an event handler to the mousemove event. This will call the resizeSelection() function every time the user moves the mouse pointer. To notify that a new selection is being made, the selectionExists variable is made true and the selection size is set to 0. Next, we get the selection origin by calling our previously written function, getMousePosition(), and pass its value to the options.selectionPosition. Finally, we call the updateInterface() function to update the plug-in's interface according to the changes made.

Step 8. Resizing The Selection

In the previous step, we wrote a function for setting a new selection. Let's now write a function for resizing that selection.

To resize the selection, we need to retrieve the current mouse position. Because the returned value is relative to the image size, we need to take care only of the negative values. It will never exceed the image bounds. As you know, we can't have a negative value for the width or height properties of an element. To solve this, we call Math.abs() to get the absolute value and then we reposition the selection.

Step 9. Releasing The Selection

And now the final function:

When the selection is being released, the releaseSelection() function removes the previously attached event handlers in the setSelection() function by calling the .unbind() method. Next, it updates the selection origin and tests the minimum size accepted for the selection to exist.

Now, we are almost ready. Close this file and prepare for the next step.

Step 10. Styling The Plug-In

Open the /resources/js/imageCrop/jquery.imagecrop.css stylesheet, and add the following lines.

There's nothing complicated here; we've added some styling to the overlay and outline layers.

Step 11. Testing The Final Result

To test our plug-in, we need to attach it to an image. Let's do that and edit the index.html page.

Open the script tag ...

... and write the following JavaScript code.

We've attached our plug-in to the image element with the example id, and set some custom options. We used the .ready() method to determine when the DOM is fully loaded.

Plug-in previewPlug-in previewPlug-in preview

And that's it! Save the file and open up your browser to test it out.

What's Next

Now we have a basic image cropping jQuery plug-in that allows us to select an area of an image. In the next tutorial, we'll add more customization options, build a preview pane, write some server-side scripting to crop the image... and much more. I hope you've enjoyed the time we've spent together and found this tutorial to be useful. Thanks for reading!

Did you find this post useful?
Want a weekly email summary?
Subscribe below and we’ll send you a weekly email summary of all new Code tutorials. Never miss out on learning about the next big thing.
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.