Composite

Node

Overlay images, add watermarks, and composite layers.

composite()

.composite(input: string | Buffer, options?: CompositeOptions): Pipeline

.composite(input: string | Buffer, options?: CompositeOptions): Pipeline

Overlay another image on top of the current image.

Prop	Type	Default	Description
input	`string \| Buffer`	—	Path to the overlay image or a Buffer.
gravity	`Gravity`	`'center'`	Position: `'north'`, `'south'`, `'east'`, `'west'`, `'center'`, `'northeast'`, etc.
top	`number`	—	Vertical offset in pixels from top. Overrides gravity.
left	`number`	—	Horizontal offset in pixels from left. Overrides gravity.
blend	`BlendMode`	`'over'`	Blend mode: `'over'`, `'multiply'`, `'screen'`, `'add'`, `'saturate'`, etc.
opacity	`number`	`1`	Overlay opacity 0–1.
tile	`boolean`	`false`	Tile the overlay across the entire image.

await img('photo.jpg')
  .composite('watermark.png', {
    gravity: 'southeast',
    opacity: 0.7,
  })
  .webp({ quality: 85 })
  .toBuffer()

await img('photo.jpg')
  .composite('watermark.png', {
    gravity: 'southeast',
    opacity: 0.7,
  })
  .webp({ quality: 85 })
  .toBuffer()

await img('photo.jpg')
  .composite('logo.png', {
    top: 20,
    left: 20,
  })
  .toBuffer()

await img('photo.jpg')
  .composite('logo.png', {
    top: 20,
    left: 20,
  })
  .toBuffer()

await img('photo.jpg')
  .composite('pattern.png', {
    tile: true,
    opacity: 0.15,
    blend: 'multiply',
  })
  .toBuffer()

await img('photo.jpg')
  .composite('pattern.png', {
    tile: true,
    opacity: 0.15,
    blend: 'multiply',
  })
  .toBuffer()

composite() is Node only — the WASM browser engine does not support multi-image compositing in v1.