File Uploader built-in image editor

Editing images right in a browser is the closest path for your app to receive better images. And those, in turn, provide higher engagement rates and conversions. The quality of visuals becomes an even greater concern when you want to perfect images sent by your users before they get to your site or app.

There are a dozen on-the-fly effects you can apply right away: crop, rotate, flip, adjust brightness, exposure, gamma, contrast, saturation, vibrance, warmth, apply photo filters, and just magical enhance.

How it works

Image operations available for application are based on our Image processing feature. Editor outputs a CDN URL holding image UUIDs and operations applied by a user while editing in the form of URL directives.

Every image first gets to your Uploadcare storage. Then we show an image preview in the File Uploader dialog via a CDN URL provided on file upload. When a user applies image processing operations, we inject the corresponding URL directives. Once the editing is complete, editor outputs the new CDN URL which includes all the applied operations.

For example, if a user chooses to apply grayscale and clicks rotate once, here is what we will get in the output:

1
https://ucarecdn.com/:UUID/-/preview/-/grayscale/-/rotate/270/

Note: The preview operation will appear in the output URL by default due to the image processing operation limitations.

Usage example

Image editor comes together with the File Uploader. All modes include a built-in cloud image editor.

1
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@uploadcare/file-uploader@v1/web/uc-cloud-image-editor.min.css">
2
3
<!-- Script connection: -->
4
<script type="module">
5
  import * as UC from "https://cdn.jsdelivr.net/npm/@uploadcare/file-uploader@v1/web/uc-cloud-image-editor.min.js";
6
  UC.defineComponents(UC);
7
8
  const callback = (text) => (event) => {
9
    console.log(`${text}`, event.detail);
10
    alert(`${text}. See results in console.`);
11
  };
12
  const instance = document.querySelector('#my-editor');
13
  instance.addEventListener('apply', callback('Apply'));
14
  instance.addEventListener('cancel', callback('Cancel'));
15
  instance.addEventListener('change', callback('Change'));
16
</script>
17
18
<!-- CSS context properties: -->
19
<style>
20
  body {
21
    height: 100vh;
22
    width: 100vw;
23
    margin: 0;
24
  }
25
</style>
26
27
<!-- Config element: -->
28
<uc-config ctx-name="my-editor"></uc-config>
29
30
<!-- Cloud image editor element with an image uuid -->
31
<uc-cloud-image-editor
32
  id="my-editor"
33
  ctx-name="my-editor"
34
  uuid="7c167b79-9f27-4489-8032-3f3be1840605"
35
></uc-cloud-image-editor>
36
37
<!-- Cloud image editor element with an image cdn-url -->
38
<uc-cloud-image-editor
39
  id="my-editor"
40
  ctx-name="my-editor"
41
  cdn-url="https://ucarecdn.com/7c167b79-9f27-4489-8032-3f3be1840605/-/mirror/-/crop/1121x543/374,266/-/preview/"
42
></uc-cloud-image-editor>

Configuration

Attributes

uuid

Type: string

Defines the UUID of the image to be edited. The image must be stored in your Uploadcare project.

cdn-url

Type: string

Defines the CDN URL of the image to be edited. The image must be stored in your Uploadcare project. You can use the previous result from the editor for subsequent actions. All transformations supported by the editor will be processed, and those not supported will be cut out.

crop-preset

Type: string

Defines the crop behavior. Expected format: 'width:height'. For example, '1:1' stands for the square crop. Empty string '' means free crop.

tabs

Type: comma separated string

Defines the list of tabs in the cloud image editor. Order matters.
Available values:

• crop - image cropping, rotating, mirroring, and flipping
• tuning - color adjustment
• filters - photo filters

Events

apply

Type: CustomEvent<ApplyResult>

1
export type Transformations = {
2
  enhance?: number | undefined
3
  brightness?: number | undefined
4
  exposure?: number | undefined
5
  gamma?: number | undefined
6
  contrast?: number | undefined
7
  saturation?: number | undefined
8
  vibrance?: number | undefined
9
  warmth?: number | undefined
10
  rotate?: number | undefined
11
  mirror?: boolean | undefined
12
  flip?: boolean | undefined
13
  filter?:
14
    | {
15
        name: string
16
        amount: number
17
      }
18
    | undefined
19
  crop?:
20
    | {
21
        dimensions: [number, number]
22
        coords: [number, number]
23
      }
24
    | undefined
25
}
26
export type ApplyResult = {
27
  originalUrl: string
28
  cdnUrlModifiers: string
29
  cdnUrl: string
30
  transformations: Transformations
31
}

Fires when a user clicks the Apply button. Returns an object with the following properties:

• originalUrl — the original image URL (without any URL directives applied)
• cdnUrlModifiers — the URL directives applied by a user
• cdnUrl — the URL of the edited image
• transformations — the object with the applied image processing operations

change

Type: CustomEvent<ChangeResult>

1
export type ChangeResult = {
2
  originalUrl: string
3
  cdnUrlModifiers: string
4
  cdnUrl: string
5
  transformations: Transformations
6
}

It fires when a user applies any transformation. The payload signature is the same as for apply event.

cancel

Type: CustomEvent<void>

Fires when a user clicks the Cancel button.