> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://uploadcare.com/docs/llms.txt.

# File Uploader built-in image editor

> Edit images directly in the browser.

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.

![File Uploader Editor](https://23dr6evpmc.ucarecd.net/577bccb3-b63c-4e7c-9add-6dcacf193702/-/quality/lightest/-/resize/1460x/)

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 \[#info]

Image operations available for application are based on our
[Image processing feature](https://uploadcare.com/cdn/image-processing/). 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:

```cdn
https://:subdomain.ucarecd.net/:UUID/-/preview/-/grayscale/-/rotate/270/
```

Note: The `preview` operation will appear in the output URL by default due
to the image processing operation [limitations](/docs/transformations/image/#limits).

## Usage example \[#usage]

Image editor comes together with the [File Uploader](/docs/file-uploader/).
All modes include a built-in cloud image editor.

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@uploadcare/file-uploader@v1/web/uc-cloud-image-editor.min.css">

<!-- Script connection: -->
<script type="module">
  import * as UC from "https://cdn.jsdelivr.net/npm/@uploadcare/file-uploader@v1/web/uc-cloud-image-editor.min.js";
  UC.defineComponents(UC);

  const callback = (text) => (event) => {
    console.log(`${text}`, event.detail);
    alert(`${text}. See results in console.`);
  };
  const instance = document.querySelector('#my-editor');
  instance.addEventListener('apply', callback('Apply'));
  instance.addEventListener('cancel', callback('Cancel'));
  instance.addEventListener('change', callback('Change'));
</script>

<!-- CSS context properties: -->
<style>
  body {
    height: 100vh;
    width: 100vw;
    margin: 0;
  }
</style>

<!-- Config element: -->
<uc-config ctx-name="my-editor"></uc-config>

<!-- Cloud image editor element with an image uuid -->
<uc-cloud-image-editor
  id="my-editor"
  ctx-name="my-editor"
  uuid="7c167b79-9f27-4489-8032-3f3be1840605"
></uc-cloud-image-editor>

<!-- Cloud image editor element with an image cdn-url -->
<uc-cloud-image-editor
  id="my-editor"
  ctx-name="my-editor"
  cdn-url="https://1nnim0cit9.ucarecd.net/7c167b79-9f27-4489-8032-3f3be1840605/-/mirror/-/crop/1121x543/374,266/-/preview/"
></uc-cloud-image-editor>
```

#### [File Uploader image editor example](https://codesandbox.io/s/docs-cloud-editor-basic-example-y3fgy7)

View in CodeSandbox

## 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](/docs/effects-enhancements/#image-colors-operations)
* `filters` - [photo filters](/docs/effects-enhancements/#image-photo-filters)

### Events

#### apply

Type: `CustomEvent<ApplyResult>`

```ts
export type Transformations = {
  enhance?: number | undefined
  brightness?: number | undefined
  exposure?: number | undefined
  gamma?: number | undefined
  contrast?: number | undefined
  saturation?: number | undefined
  vibrance?: number | undefined
  warmth?: number | undefined
  rotate?: number | undefined
  mirror?: boolean | undefined
  flip?: boolean | undefined
  filter?:
    | {
        name: string
        amount: number
      }
    | undefined
  crop?:
    | {
        dimensions: [number, number]
        coords: [number, number]
      }
    | undefined
}
export type ApplyResult = {
  originalUrl: string
  cdnUrlModifiers: string
  cdnUrl: string
  transformations: Transformations
}
```

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>`

```ts
export type ChangeResult = {
  originalUrl: string
  cdnUrlModifiers: string
  cdnUrl: string
  transformations: Transformations
}
```

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.

### Custom masks

You can add a mask to guide users in cropping their images to meet upload requirements.
This is especially useful for avatars, profile photos, and documents.

To enable this feature, upload your mask image to Uploadcare storage and use its
CDN URL in the [`cloudImageEditor.maskHref` option](/docs/file-uploader/options/#cloud-image-editor-mask-href)
of the File Uploader configuration.

The image used as a mask should ideally include transparency (opacity),
as the editor does not apply it by default.

Users can select and crop their images freely, but the overlay provides a visual guide.
If you want to enforce a specific aspect ratio during cropping, use
the [`cloudImageEditor.cropPreset` option](/docs/file-uploader/image-editor/#crop-preset)
alongside your mask to lock the desired ratio.