<!-- Generated by documentation.js. Update this documentation by updating the source code. -->

## 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`.

If the overlay image contains an alpha channel then composition with premultiplication will occur.

### Parameters

-   `overlay` **([Buffer][1] \| [String][2])** Buffer containing image data or String containing the path to an image file.
-   `options` **[Object][3]?** 
    -   `options.gravity` **[String][2]** gravity at which to place the overlay. (optional, default `'centre'`)
    -   `options.top` **[Number][4]?** the pixel offset from the top edge.
    -   `options.left` **[Number][4]?** the pixel offset from the left edge.
    -   `options.tile` **[Boolean][5]** set to true to repeat the overlay image across the entire image with the given `gravity`. (optional, default `false`)
    -   `options.cutout` **[Boolean][5]** 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.density` **[Number][4]** integral number representing the DPI for vector overlay image. (optional, default `72`)
    -   `options.raw` **[Object][3]?** describes overlay when using raw pixel data.
        -   `options.raw.width` **[Number][4]?** 
        -   `options.raw.height` **[Number][4]?** 
        -   `options.raw.channels` **[Number][4]?** 
    -   `options.create` **[Object][3]?** describes a blank overlay to be created.
        -   `options.create.width` **[Number][4]?** 
        -   `options.create.height` **[Number][4]?** 
        -   `options.create.channels` **[Number][4]?** 3-4
        -   `options.create.background` **([String][2] \| [Object][3])?** parsed by the [color][6] module to extract values for red, green, blue and alpha.

### Examples

```javascript
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][7]** Invalid parameters

Returns **Sharp** 

[1]: https://nodejs.org/api/buffer.html

[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String

[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object

[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number

[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean

[6]: https://www.npmjs.org/package/color

[7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error