node-merge-images

Merge multiple images into one with ImageMagick. Supports vertical/horizontal merging, custom spacing, free-form positioning, and grid layouts.

Supported OS

• Linux
• macOS

Requirements

ImageMagick CLI tools must be installed on your system.

macOS (Homebrew):

brew install imagemagick

Linux (apt):

sudo apt-get install imagemagick

Linux (yum):

sudo yum -y install ImageMagick

Installation

npm install node-merge-images

Usage

// CommonJS
const mergeImages = require('node-merge-images');

// ESM
import mergeImages from 'node-merge-images';

Vertical merge (default)

await mergeImages(['1.jpg', '2.jpg', '3.jpg'], 'output.jpg');

Horizontal merge

await mergeImages(['1.jpg', '2.jpg', '3.jpg'], 'output.jpg', {direction: 'horizontal'});

Vertical merge with spacing

Spacing is filled with the background color ('#000' in this example).

await mergeImages(['1.jpg', '2.jpg', '3.jpg'], 'output.jpg', {offset: 30, background: '#000'});

Horizontal merge with spacing

await mergeImages(['1.jpg', '2.jpg', '3.jpg'], 'output.jpg', {
  direction: 'horizontal',
  offset: 30,
  background: '#000',
});

Merging images of different sizes

When images have different dimensions, the output adjusts to the largest width (vertical) or height (horizontal).

Vertical:

await mergeImages(['1.jpg', '2.jpg', 'wide.jpg'], 'output.jpg', {background: '#000'});

Horizontal:

await mergeImages(['1.jpg', '2.jpg', 'tall.jpg'], 'output.jpg', {direction: 'horizontal', background: '#000'});

Free-form positioning

Place each image at exact (x, y) coordinates on an auto-sized canvas.

await mergeImages(['bg.jpg', 'icon.png', 'label.png'], 'output.jpg', {
  positions: {
    0: {x: 0, y: 0},
    1: {x: 10, y: 20},
    2: {x: 100, y: 50},
  },
});

Grid layout

Arrange images in a grid by specifying the number of columns.

// 3-column grid (rows auto-calculated)
await mergeImages(
  ['1.jpg', '2.jpg', '3.jpg', '4.jpg', '5.jpg', '6.jpg'],
  'output.jpg',
  {grid: 3},
);

// Explicit 3x2 grid with spacing
await mergeImages(
  ['1.jpg', '2.jpg', '3.jpg', '4.jpg'],
  'output.jpg',
  {grid: {columns: 3, rows: 2}, offset: 10, background: '#000'},
);

API

mergeImages(inputPaths, outputPath[, options])

Returns Promise<void>.

Parameters

| Parameter | Type | Default | Description | |---|---|---|---| | inputPaths | string[] | required | Paths of images to merge. | | outputPath | string | required | Output path for the merged image. | | options.direction | 'vertical' \| 'horizontal' | 'vertical' | Merge direction (append mode). | | options.background | string | 'white' | Background color. Accepts color names, hex ('#ff0000'), rgb(), etc. | | options.offset | number | 0 | Spacing in pixels between images. | | options.positions | Record<number, {x, y}> | — | Place each image at (x, y) coordinates. | | options.grid | number \| {columns, rows?} | — | Arrange images in a grid layout. |

Note: positions and grid cannot be used together. When positions is set, direction and offset are ignored. When grid is set, direction is ignored.

Errors

| Error | Condition | |---|---| | TypeError | inputPaths is not an array or is empty. | | TypeError | outputPath is empty. | | TypeError | direction is not 'vertical' or 'horizontal'. | | TypeError | offset is negative. | | TypeError | One or more input files do not exist. | | TypeError | positions and grid are both specified. | | Error | ImageMagick command execution failed. |

Testing

npm test

Author

shumatsumonobu

• GitHub
• X
• Facebook

Changelog

See CHANGELOG.md.

License

MIT