Login

scaleImage(bytes, width, height, [options]) Last updated: 20. May 2026

API only function

Scales an image byte array to a target size and returns the scaled image as bytes. Supports several scaling modes and lets you preserve or convert between PNG and JPEG output formats. The optional parameters (mode, quality, format) can be supplied positionally or as a single options object — see the examples below.

See also: getEmbeddedFile Image scaling

Parameters

Name Type Description
bytes byte[]

Input image bytes (PNG, JPEG, GIF, BMP, or any format supported by the image scaler).
width number

Target width in pixels. Must be positive.
height number

Target height in pixels. Must be positive.
options (optional)objectSpecify any of the following options parameters:
• mode string or number

Scaling mode. Accepts either the enum name as a string or the numeric value:

• "ScaleToFit" (0) — proportional, never grows the image. Default.
• "ScaleToFill" (1) — fills target, may crop edges to keep aspect ratio.
• "Resize" (2) — exact target size, may distort aspect ratio.
• "SkipResize" (-1) — returns the original image unchanged.
• "ScaleAndFill" (3) — fit + white padding to exact target size.
• "ScaleAndFillBlack" (4) — fit + black padding to exact target size.
• "ConvertToJpegNoResize" (5) — re-encode without resizing.

Same modes used by the /scale-URL on embedded files.
Default is "ScaleToFit" (0).
• quality number

JPEG quality 0-100. Ignored when the output is PNG. Default 85.
• format string

Output format:

• "auto" — preserve PNG when the input starts with the PNG signature, otherwise output JPEG. Default.
• "png" — force PNG output (preserves transparency).
• "jpeg" / "jpg" — force JPEG output.

Returns

The scaled image as a byte array.

Notes:
• Throws when the input bytes are empty, are not a valid image, or when width/height are non-positive.
• "auto" format keeps PNG transparency for PNG sources and outputs JPEG for everything else.
• Mode names match the ImageScaleMode enum used elsewhere in the platform.

Example

Code example (JS)

JS is normal JavaScript either running in the browser or on the Docly™ server. 
// Image bytes — e.g. retrieved with getEmbeddedFile()
let imageBytes = docly.getEmbeddedFile(filePath, embedId);

// Simplest form — defaults: ScaleToFit, quality 85, auto format
let thumb = docly.scaleImage(imageBytes, 200, 200);

// Force PNG output to preserve transparency
let smallLogo = docly.scaleImage(imageBytes, 64, 64, { format: "png" });

// Combine several options
let avatar = docly.scaleImage(imageBytes, 100, 100, {
    mode: "ScaleToFill",
    quality: 75,
    format: "jpeg"
});