dile-image-cropper

Web Component to crop images in the browser, built on top of Cropper.js v2. It works on its own, without any upload logic: you give it an image, the user selects an area, and you export the result as a canvas, a Blob or a File.

Cropper.js is lazy loaded: importing the component only registers dile-image-cropper. The Cropper.js code is downloaded the first time a cropper has an image to display.

Installation

npm i @dile/image-cropper

Usage

Import the component:

import '@dile/image-cropper/image-cropper.js';

Use the component, with an image URL or a File object:

<dile-image-cropper src="/images/photo.jpg" aspectRatio="1"></dile-image-cropper>

const cropper = document.querySelector('dile-image-cropper');
cropper.file = inputFile.files[0];
// later...
const croppedFile = await cropper.getFile();

The image stays fixed inside the crop area. The user moves and resizes the selection, which is always kept within the bounds of the image.

Properties

Note: When the output type is image/jpeg, the exported image gets a white background, since JPEG does not support transparency.

Methods

• getCanvas(): Returns a promise that resolves to an HTMLCanvasElement with the cropped area.
• getBlob(): Returns a promise that resolves to a Blob with the cropped image, using outputType and outputQuality.
• getFile(fileName): Returns a promise that resolves to a File with the cropped image. The name is fileName or the name of the file property, with the extension that matches the output type (e.g. photo.png exported as JPEG becomes photo.jpg).
• reset(): Restores the initial selection.

The export methods reject if there is no image loaded.

Events

• dile-image-cropper-ready: Dispatched when the image is loaded and the initial selection is set. detail contains the selection: { x, y, width, height }, in pixels relative to the crop area.
• dile-image-cropper-change: Dispatched every time the selection changes. detail contains { x, y, width, height }.
• dile-image-cropper-error: Dispatched when the image cannot be loaded. detail contains { error }.

cropper.addEventListener('dile-image-cropper-change', async () => {
  preview.src = URL.createObjectURL(await cropper.getBlob());
});

CSS Custom Properties

Use with dile-image-uploader

The dile-image-uploader component of @dile/crud can use this component to crop images before uploading them, through its crop property.

dile-image-cropper demos

Free crop

<script type="module">
  import '@dile/image-cropper/image-cropper.js';
</script>
<dile-image-cropper src="/images/random-user.jpg"></dile-image-cropper>

Avatar with export

<script type="module">
  import { LitElement, html, css } from 'lit';

  class AvatarCropperDemo extends LitElement {
    static styles = css`
      .result {
        display: flex;
        align-items: center;
        gap: 1rem;
        margin-top: 1rem;
      }
      img {
        width: 96px;
        height: 96px;
        border-radius: 50%;
      }
    `;
    static properties = { preview: { state: true } };

    render() {
      return html`
        <input type="file" accept="image/*" @change=${this.selectFile}>
        <dile-image-cropper
          id="cropper"
          aspectRatio="1"
          outputWidth="256"
          outputHeight="256"
          round
        ></dile-image-cropper>
        <div class="result">
          <button @click=${this.crop}>Crop</button>
          ${this.preview ? html`<img src="${this.preview}" alt="Cropped avatar">` : ''}
        </div>
      `;
    }

    get cropper() {
      return this.shadowRoot.getElementById('cropper');
    }

    selectFile(e) {
      this.cropper.file = e.target.files[0] || null;
    }

    async crop() {
      const blob = await this.cropper.getBlob();
      this.preview = URL.createObjectURL(blob);
    }
  }
  customElements.define('avatar-cropper-demo', AvatarCropperDemo);
</script>
<avatar-cropper-demo></avatar-cropper-demo>