Cropme

Cropme is a customizable and easy to use javascript image cropper plugin.

See the demo

Features

Support:

• Two-dimensional translation
• Scaling
• Free rotation
• Multi-touch support (pinch-zoom, two finger rotation, ...)
• Base64 and blob exportation
• Multiple croppers

Architecture

dist/
├── cropme.min.css   (compressed)
└── cropme.min.js    (UMD, compressed)

Installation

npm

npm install cropme

Download

Download the project and extract it in your project folder, then import it.

<link rel="stylesheet" href="path-to/cropme.css">
<script src="path-to/cropme.js"></script>

Usage

Syntax

new Cropme(element, options);

• element (HTMLElement, required): the cropper wrapping HTML element. Must be a flow content element or an image.

• options (Object, optional): The configuration options, see Options.

Example

Vanilla javascript

<div id="container"></div>

<script>
  var element = document.getElementById('container');
  var cropme = new Cropme(element);
  cropme.bind({
    url: 'images/naruto.jpg'
  });
</script>

<!-- or use image tag -->
<img src="images/naruto.jpg" id="myImage" />
<script>
  var element = document.getElementById('myImage');
  new Cropme(element);
</script>

JQuery

<div id="container"></div>

<script>
  var example = $('#container').cropme();
  example.cropme('bind', {
    url: 'images/naruto.jpg'
  });
</script>

<!-- or use image tag -->
<img src="images/naruto.jpg" id="myImage" />
<script>
  $('#myImage').cropme();
</script>

Options

Container

• Target: the container of the cropper.
• Key: container
• Parameters:
  • width (int, default: 300): the outer container width
  • height (int, default: 300): the outer container height

Example

container: {
  width: 500,
  height: 400
}

Viewport

• Target: the part that will be cropped.
• Key: viewport
• Parameters:
  • width (int, default: 100): the viewport width
  • height (int, default: 100): the viewport height
  • border (object): the viewport frame border
    • enable (bool, default: true): toggle the border
    • width (int, default: 2): the border width
    • color (string, unit: hex, rgba, hsl, default: #fff): the border color

Example

viewport: {
  width: 100,
  height: 100,
  border: {
    enable: true,
    width: 2,
    color: '#fff'
  }
}

Zoom

• Target: the image zoom options
• Key: zoom,
• Parameters:
  • min (number, default: 0.01): minimum zoom
  • max (number, default: 3): maximum zoom
  • enable (bool, default: true): enable or disable the zoom feature
  • mouseWheel (bool, default: true): enable or disable mouse wheel zoom
  • slider (bool, default: false): toggle the slider input

Example

zoom: {
  min: 0.01,
  max: 3,
  enable: true,
  mouseWheel: true,
  slider: false
}

Rotation

• Target: the image rotation
• Key: rotation
• Parameters:
  • enable (bool, default: true): enable or disable the rotation
  • slider (bool, default: false): toggle the slider input
  • position (string, default: right, available: right, left): the slider input position

Example

rotation: {
  enable: true,
  slider: false,
  position: 'right'
}

Custom class

• Target: the container class
• Parameter:
  • customClass (string, default: null): the class of the container

Example

{
  customClass: 'my-custom-class'
}

Methods

bind()

Binds an image and return a promise after the image is loaded.

Arguments

The bind() method expects an Object containing:

• url (required)
  • type: String
  • description: The url of the image to bind.
• position
  • type: Object with x and y keys.
  • description: An object that contains the x and y coordinates.
    If not specified, the image is centered horizontaly and verticaly.
• scale
  • type: number
  • description: The scale of the image, 1 is the original image size.
    If not specified, the image will takes the container's height and scale
    automaticaly.
• angle
  • description: The rotation of the image by an angle in degree
  • type: number
  • unit: degree
  • default: 0

Example

$('#myImage').cropme('bind', {
  url: 'images/naruto.jpg',
  position: {
    x: 230,
    y: 30
  },
  scale: 1.3,
  angle: 90
});

rotate()

Rotate the image to the given angle.

Arguments

• angle
  • description: The angle the image will be rotated to.
    The rotation is not relative to the current image rotation.
  • type: number
  • unit: degree

Example

$('#myImage').cropme('rotate', 90);

crop()

Returns a promise with the cropped image.

Arguments

As a parameter, the crop() function can receive:

1. An Object containing:

• type
  • type: String
  • default: base64
  • possible value: base64, blob
  • description: The image exportation format
• width
  • type: int
  • description: The width of the output images, the height will be
    proportional.
• scale
  • type: number
  • description: The size of the ouput, relative to the original image size.
    If scale has a value, the width get ignored.

2. A String specifying the exportation format (base64 or blob)

⚠️ Calling crop() without parameters returns a base64 image with
the original viewport size.

Example

// string
$('#myImage').cropme('crop', 'blob');

// object
$('#myImage').cropme('crop', {
    type: 'base64',
    width: 800
});

// no parameter
$('#myImage').cropme('crop')
    .then(function(output) {
        // here you can use the base64 output
    });

position()

Returns an object specifying the image configuration

Example

$('#myImage').cropme('position');

Output

Object {
  x: 20,
  y: 40,
  scale: 1.4,
  deg: 45
}

destroy()

Destroy the cropme instance

Example

$('#myImage').cropme('destroy');

Contributing

Thank you for your contribution to this project.

Installation

Fork the project then

npm install && npm run dev