join-images

Merge multiple images into a single image

join-images is modified version of merge-img to make it work with sharp library.

join-images merges given images into a single image in right order. This will be helpful in a situation when you have to generate a preview of multiple images into a single image. This module is based on sharp for image processing.

Image credit: https://www.pexels.com/

Install

$ npm install sharp join-images

$ yarn add sharp join-images

Usage

File paths

const joinImages = require('join-images');

joinImages(['image-1.png', 'image-2.jpg']).then((img) => {
  img.toFile('out.png');
});

Buffers

const fs = require('node:fs');
const joinImages = require('join-images');

const sources = ['image-1.png', 'image-2.jpg'].map((source) => fs.readFileSync(source));

joinImages(sources).then((img) => {
  img.toFile('out.png');
});

Object inputs

const fs = require('node:fs');
const joinImages = require('join-images');

joinImages([
  { src: fs.readFileSync('image-1.png'), offsetX: 10 },
  { src: fs.readFileSync('image-2.png'), offsetY: 20 },
]).then((img) => {
  img.toFile('out.png');
});

Sharp pipelines

const joinImages = require('join-images');
const sharp = require('sharp');

const sources = ['image-1.png', 'image-2.jpg'];

joinImages(sources.map((source) => sharp(source).trim())).then((img) => {
  img.toFile('out.png');
});

API

joinImages(images[, options])

• images Array of (String | Object | Buffer | Sharp) - List of images to concat. If String is passed, it will be considered to the file path. If Sharp is passed, the rendered output of that sharp pipeline is used. An Object entry can have following options:
  • src String or Buffer - A single image source to concat.
  • offsetX Number (optional) - x offset to affect this image. Default is 0.
  • offsetY Number (optional) - y offset to affect this image. Default is 0.
• options Object (optional)
  • direction String (vertical|horizontal) - Direction of the merged image.`.
  • color (String | Object) - Default background color represented by RGBA hex value. Default is { alpha: 0.5, b: 0, g: 0, r: 0 }.
  • align String - Aligning of given images. If the images are not all the same size, images will be sorted to largest image. Possible values are start, center and end. Default is start.
  • offset Number - Offset in pixels between each image. Default is 0.
  • margin (Number | String | Object) - Margin of the result image. If Number or String is passed, it will be considered as standard css shorthand properties (e.g. '40 40 0 10'). An Object entry can have following options:
    • top Number (optional) - Margin on top side of result image. Default is 0.
    • right Number (optional) - Margin on right side of result image. Default is 0.
    • bottom Number (optional) - Margin on bottom side of result image. Default is 0.
    • left Number (optional) - Margin on left side of result image. Default is 0.

Returns a Promise that contains sharp object.