Setting up Image Editing with the Input element

The <image-input> custom element is a tiny wrapper around the <input type="file"> element.

It's the easiest and fastest way to add image editing and uploading functionality to a webpage.

<!DOCTYPE html>

<link rel="stylesheet" href="image-input.css" />

<image-input name="my-field"></image-input>

<script src="image-input.js"></script>

This will automatically create a <input type="file"> element with an accept attribute that filters for images and a name attribute set to my-field.

When an image is selected the editor will automatically open in a modal.

All serializable image editor properties can be assigned to the image-input field.

<image-input image-crop-aspect-ratio="1"></image-input>

This also works:

<image-input utils='["crop", "finetune", "filter"]'></image-input>

If we have multiple fields on the page, we can set a global ImageInput property on the window to share configuration options between fields.

    window.ImageInput = {
        imageCropMinSize: {
            width: 256,
            height: 256,

<image-input name="my-field"></image-input>

If we add a file input element to the image-input element it'll use that element as the file field. If the accept attribute is omitted or doesn't filter images it's automatically added to the field.

    <input type="file" name="my-field" />

Image Input properties

The <image-input> field accepts the following additional properties.

Property Default value Description
Used as name attribute on the internal file input element.
Used as accept attribute on the internal file input element.
Used as capture attribute on the internal file input element.
Optional URL location of the upload handler for async file uploads.
Custom fields to add to the store upload action. FieldName is the name used in the form post.
'{filename} uploaded successfully'
The label to use for the success message.
The label to use on the input reset button. Defaults to the × symbol.


Set to a target URL and the editor will upload files to that URL when the editing has completed.

If the store property is omitted the output file will be stored in the file field value. At the time of this writing this doesn't work on Safari.


If store is not set but post fields have been defined the store value is set to an empty string.

The example below will add a field called "action" with value "upload" to the FormData.

<image-input post-custom-data="abcd"></image-input>

Is equal to a field posted like this:

<input type="hidden" name="custom-data" value="abcd" />

or a field added like this:

const fd = FormData();
fd.append('custom-data', 'abcd');

The attribute name without the post- part is used as the field name.

'post-custom-data' -> 'custom-data'
'post-customData' -> 'customData'
'post-custom_data' -> 'custom_data'

Next step

With the editor set up, we can continue to configure the editor to our liking with the available instance properties