Function Updated 23 Oct 2026

`scaleImage(bytes, width, height, [options])`

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 JPEG, PNG, WebP and AVIF output formats. The optional parameters (mode, quality, format) can be supplied positionally or as a single options object — see the examples below.

Note: scaleImage runs server-side and is controlled entirely by your own code. It is NOT subject to Images.SizePolicy in site.json — only URL-based scaling (/photo.jpg/WxHxM/...) is enforced against the allowed-sizes policy. See the 'Image output formats (WebP / AVIF)' section on the Image scaling page. scaleImage is not subject to the image size policy; to enable and register the sizes that ARE enforced (URL-based scaling), see the KB article Restrict and register image sizes.

Parameters

bytesbyte[]required

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

widthnumberrequired

Target width in pixels. Must be positive.

heightnumberrequired

Target height in pixels. Must be positive.

optionsobjectoptional

Specify any of the following options parameters:

modestring 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).

qualitynumber

Output quality 0-100. Applies to lossy formats (JPEG, WebP, AVIF). Ignored when the output is PNG.

Omit it and the quality comes from Images.Quality in site.json, resolved for the format actually being written — the same setting and the same defaults that URL-based scaling uses, so both paths behave identically. With nothing configured the built-in defaults apply: JPEG 85, WebP 78, AVIF 50. An explicit value here always wins.

formatstring

Output format:

• "auto" — preserve PNG when the input starts with the PNG signature, otherwise output JPEG. Falls back to Images.DefaultFormat from site.json when that is set. Default.
• "png" — force PNG output (preserves transparency). Encoded with GDI+.
• "jpeg" / "jpg" — force JPEG output. Encoded with GDI+ (fastest).
• "webp" — force WebP output (Magick.NET). Better compression than JPEG with universal browser support today.
• "avif" — force AVIF output (Magick.NET). Best compression; supported by modern browsers. Recommended for the highest performance score.

An explicit format always wins over Images.DefaultFormat. quality also applies to WebP/AVIF.

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

Normal JavaScript, running in the browser or on the Docly™ server.

if(false) { // Show code only, can't run

    // Image bytes — e.g. retrieved with getEmbeddedFile()
    let imageBytes = docly.getEmbeddedFile(filePath, embedId);
    
    // Simplest form — defaults: ScaleToFit, auto format, and the quality
    // from site.json (Images.Quality), or the built-in default per 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"
    });
    
    // Modern formats: WebP (positional args) and AVIF (options object)
    let webp = docly.scaleImage(imageBytes, 1200, 800, 0, 80, "webp");
    let avif = docly.scaleImage(imageBytes, 800, 600, { quality: 60, format: "avif" });
}