Composite image(s) over the processed (resized, extracted etc.) image.

The images to composite must be the same size or smaller than the processed image. If both top and left options are provided, they take precedence over gravity.

The blend option can be one of clear, source, over, in, out, atop, dest, dest-over, dest-in, dest-out, dest-atop, xor, add, saturate, multiply, screen, overlay, darken, lighten, colour-dodge, color-dodge, colour-burn,color-burn, hard-light, soft-light, difference, exclusion.

More information about blend modes can be found at and


  • images Array<Object> Ordered list of images to composite
    • images[].input (Buffer | String)? Buffer containing image data, String containing the path to an image file, or Create object (see bellow)
      • images[].input.create Object? describes a blank overlay to be created.
        • images[].input.create.width Number?
        • images[].input.create.height Number?
        • images[].input.create.channels Number? 3-4
        • images[].input.create.background (String | Object)? parsed by the color module to extract values for red, green, blue and alpha.
    • images[].blend String how to blend this image with the image below. (optional, default 'over')
    • images[].gravity String gravity at which to place the overlay. (optional, default 'centre')
    • images[].top Number? the pixel offset from the top edge.
    • images[].left Number? the pixel offset from the left edge.
    • images[].tile Boolean set to true to repeat the overlay image across the entire image with the given gravity. (optional, default false)
    • images[].density Number number representing the DPI for vector overlay image. (optional, default 72)
    • images[].raw Object? describes overlay when using raw pixel data.


  .flatten( { background: '#ff6600' } )
  .composite([{ input: 'overlay.png', gravity: 'southeast' }])
  .webp( { quality: 90 } )
  .then(function(outputBuffer) {
    // outputBuffer contains upside down, 300px wide, alpha channel flattened
    // onto orange background, composited with overlay.png with SE gravity,
    // sharpened, with metadata, 90% quality WebP image data. Phew!
  • Throws Error Invalid parameters

Returns Sharp