Media Utils

lightning/mediaUtils

Given an input image (as a file handle or a blob) this method will resize and compress the image according to the specified options, and return a Blob object containing the resulting image data.

For Use In

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App

The lightning/mediaUtils module provides the processImage function. In your component's Javascript file, import the function from the lightning/mediaUtils module.

Resizes and compresses image files.

Call this function by passing in an input image and a set of options to be used to process the input image, as further described below. It returns a promise that resolves to a Blob object containing the output image data.

Parameter	Type	Description
`input`	`file` or `blob`	Defines the input image.
`options`	`object`	An object that defines the options to be used when processing the input image. Optional parameter containing a number of flags. If this parameter or any of its flags are omitted, default values will be used.
`options.resizeMode`	`string`	Determines how the image will be resized. Valid values: `fill`: This is the default. The image will be resized to fill the target dimension. If necessary, the image will be stretched or squished to fit. `contain`: The image keeps its aspect ratio but will be resized to fit within the target dimension. `none`: The image will not be resized and will retain its original dimension.
`options.resizeStrategy`	`string`	Determines how to resize the image. Ignored if `resizeMode` is `none`. Valid values: `reduce`: Only resize if the image is larger than the target size (smaller images won't be resized). `enlarge`: Only resize if the image is smaller than the target size (larger images won't be resized). `always`: This is the default. Always resize the image to the target size regardless of the original image dimensions.
`options.targetWidth`	`number`	The target width when resizing an image. Defaults to original image width if omitted. Ignored if `resizeMode` is `none`.
`options.targetHeight`	`number`	The target height when resizing an image. Defaults to original image height if omitted. Ignored if `resizeMode` is `none`.
`options.compressionQuality`	`number`	A number between 0-1 that determines the compression quality. If omitted then the browser/webview picks a default value as it sees fit. Note that this parameter will be considered as a suggested compression quality, however the browser/webview may choose to override this value if it deems it necessary. For example if the value is larger than 1 or if it is considered to be too small by the browser/webview, then it will override the value to something that it deems more appropriate.
`options.imageSmoothingEnabled`	`boolean`	Determines whether scaled images are smoothed. Defaults to `true`.
`options.preserveTransparency`	`boolean`	Determines whether transparency info should be preserved. Defaults to `true`. If input is GIF/PNG and this is `true`, output will be PNG. For all other cases the output will be a JPEG.
`options.backgroundColor`	`string`	Defines a CSS color as described in the MDN color reference. Defaults to `white`. When `preserveTransparency` is set to `false`, the output image has its background set to this color before the input image is resized and drawn on top.

Consider an example where you upload files to a Salesforce org using a lightning-input component.

In your Javascript file, use processImage to reduce image sizes and hence reduce the bandwidth used to upload the images, as illustrated below:

The mediaUtils library is not meant to be used for processing arbitrarily large images. This library uses JavaScript APIs and the HTML5 Canvas element to process the image. It is limited by the browser, the Canvas element, and the hardware limitations of your device, like the amount of available memory.

Most desktop browsers require the input image to have a dimension of 32,767 x 32,767 pixels or smaller, while other desktop browsers have a lower limit. However, this limit can be significantly lower on mobile devices. Also, note that the mediaUtils library needs to convert the input images to an uncompressed bitmap in the device memory before they can be processed further. This means that the byte-size of your input image increases after it is converted to an uncompressed bitmap. This is especially true with JPEG images, where the image is compressed using a JPEG compression algorithm to reduce their byte-size. When you convert a JPEG image back to an uncompressed bitmap, the byte-size of the resulting bitmap may be much larger than the original image. This can stop the mediaUtils library from processing your input image because there is not enough memory (especially on mobile devices where device memory is often smaller than desktops).

For these reasons, consider limiting the dimension and byte-size of the images that you pass to the mediaUtils library. A good starting point is 4,096 x 4,096 pixels and 10 MB in size. You can then experiment and adjust these limits based on your use-case scenarios.