scaleImage(bytes, width, height, [options]) Last updated: 13. 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.

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)	object	Specify 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"
});