sharp/docs/api-composite.md

overlayWith

Overlay (composite) an image over the processed (resized, extracted etc.) image.

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

Parameters

• overlay (Buffer | String) Buffer containing image data or String containing the path to an image file.
• options [Object]
  • options.gravity [String] gravity at which to place the overlay. (optional, default 'centre')
  • options.top [Number] the pixel offset from the top edge.
  • options.left [Number] the pixel offset from the left edge.
  • options.tile [Boolean] set to true to repeat the overlay image across the entire image with the given gravity. (optional, default false)
  • options.cutout [Boolean] set to true to apply only the alpha channel of the overlay image to the input image, giving the appearance of one image being cut out of another. (optional, default false)
  • options.raw [Object] describes overlay when using raw pixel data.
    • options.raw.width [Number]
    • options.raw.height [Number]
    • options.raw.channels [Number]

Examples

sharp('input.png')
  .rotate(180)
  .resize(300)
  .flatten()
  .background('#ff6600')
  .overlayWith('overlay.png', { gravity: sharp.gravity.southeast } )
  .sharpen()
  .withMetadata()
  .quality(90)
  .webp()
  .toBuffer()
  .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