omni-compress - v2.3.10
    Preparing search index...

    Interface ImageOptions

    Options for compressImage().

    interface ImageOptions {
        format?: "webp" | "avif" | "jpeg" | "png" | "auto";
        quality?: number;
        maxSizeMB?: number;
        maxWidth?: number;
        maxHeight?: number;
        minWidth?: number;
        minHeight?: number;
        width?: number;
        height?: number;
        resize?: "contain" | "cover" | "fill" | "inside" | "outside" | "none";
        position?: string;
        withoutEnlargement?: boolean;
        convertTypes?: string | string[];
        convertSize?: number;
        beforeDraw?: (
            canvas: HTMLCanvasElement | OffscreenCanvas,
            ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D,
        ) => void;
        drew?: (
            canvas: HTMLCanvasElement | OffscreenCanvas,
            ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D,
        ) => void;
        checkOrientation?: boolean;
        retainExif?: boolean;
        preserveMetadata?: boolean;
        strict?: boolean;
        useWorker?: boolean;
        onProgress?: (percent: number) => void;
        signal?: AbortSignal;
    }
    Index

    Properties

    format? quality? maxSizeMB? maxWidth? maxHeight? minWidth? minHeight? width? height? resize? position? withoutEnlargement? convertTypes? convertSize? beforeDraw? drew? checkOrientation? retainExif? preserveMetadata? strict? useWorker? onProgress? signal?

    Properties

    format?: "webp" | "avif" | "jpeg" | "png" | "auto"

    Target output format. Default: 'auto' (converts PNG/JPEG to WebP).

    quality?: number

    Encoder quality from 0.0 (worst) to 1.0 (best). Default: 0.8.

    maxSizeMB?: number

    Target output file size in megabytes. When set, the library runs a binary search over quality values (up to 6 passes) to find the highest quality that produces output ≤ maxSizeMB. Applies to lossy formats only (WebP, JPEG, AVIF). PNG is lossless and ignores this option.

    If the target cannot be reached at minimum quality (0.05), the smallest achievable result is returned with a console warning.

    // Enforce a 500 KB output ceiling
    const { blob, quality } = await compressImage(file, {
      format: 'webp',
      maxSizeMB: 0.5,
    });
    console.log(`Final quality: ${quality}`);
    maxWidth?: number

    Resize output width to at most this many pixels (maintains aspect ratio).

    maxHeight?: number

    Resize output height to at most this many pixels (maintains aspect ratio).

    minWidth?: number

    Scale up if output width is below this value (maintains aspect ratio).

    minHeight?: number

    Scale up if output height is below this value (maintains aspect ratio).

    width?: number

    Exact output canvas width in pixels. Use with resize to control fitting.

    height?: number

    Exact output canvas height in pixels. Use with resize to control fitting.

    resize?: "contain" | "cover" | "fill" | "inside" | "outside" | "none"

    Resize mode when both width and height are set.

    • 'contain' (default): scale to fit within the canvas, letterbox if needed.
    • 'cover': scale to fill the canvas, cropping the overflow.
    • 'fill': stretch to fill the canvas exactly, ignoring aspect ratio.
    • 'inside': scale down to fit within bounds; never upscales; no letterbox.
    • 'outside': scale to cover bounds without cropping; may exceed bounds in one dimension.
    • 'none': draw the image at its current size; canvas is cropped/padded.
    position?: string

    Anchor point for letterboxing (contain) or cropping (cover). Default: 'center'. Accepts: 'center', 'top', 'right', 'bottom', 'left', 'top-left', 'top-right', 'bottom-left', 'bottom-right'. Also accepts compass direction aliases: 'north', 'east', 'south', 'west', etc.

    withoutEnlargement?: boolean

    When true, the image is never upscaled beyond its original dimensions, even when the target canvas is larger. Also disables minWidth/minHeight. Default: false.

    convertTypes?: string | string[]

    MIME type(s) eligible for auto format conversion (e.g. 'image/png'). When the input's MIME type matches one of these AND the file size is below convertSize, the format is locked to the input format (no conversion). Default: [] (no restriction).

    convertSize?: number

    Minimum file size (bytes) that triggers convertTypes auto-conversion. Files below this threshold keep their original format. Default: 5242880 (5 MB).

    beforeDraw?: (
        canvas: HTMLCanvasElement | OffscreenCanvas,
        ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D,
    ) => void

    Called on the canvas context after the canvas is created and filled, but before the image bitmap is drawn. Useful for applying background colours or watermarks. Browser fast path only (no-op on FFmpeg / Node paths).

    drew?: (
        canvas: HTMLCanvasElement | OffscreenCanvas,
        ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D,
    ) => void

    Called on the canvas context after the image bitmap has been drawn, but before the canvas is encoded. Useful for overlays or post-processing. Browser fast path only (no-op on FFmpeg / Node paths).

    checkOrientation?: boolean

    When true (default), EXIF orientation is applied automatically so the image is upright. Set to false to preserve the raw pixel orientation.

    retainExif?: boolean

    When true, the original EXIF metadata is re-injected into the JPEG output. Only applies to JPEG input compressed to JPEG output on the browser fast path. Default: false.

    preserveMetadata?: boolean

    When true, EXIF/metadata is preserved in the output. Default: false (stripped).

    strict?: boolean

    If the compressed image is larger than the original, return the original. Default: false.

    useWorker?: boolean

    Explicitly force Web Worker usage (true) or Main Thread usage (false). If omitted, the library chooses based on file size and operation type.

    onProgress?: (percent: number) => void

    Called with progress 0–100 during heavy-path (FFmpeg) operations.

    signal?: AbortSignal

    Cancel the operation. Throws AbortError when signalled.

    Settings

    Member Visibility

    On This Page

    Properties