join-images/README.md

Merge multiple images into a single image

# join-images

> Merge multiple images into a single image

`join-images` is modified version of [`merge-img`][merge-img] to make it work with [`sharp`][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`][sharp] for image processing.

![figure](media/figure.png)
Image credit: https://www.pexels.com/

## Install

```bash
$ npm install sharp join-images
```

```bash
$ yarn add sharp join-images
```

## Usage

### File paths

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

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

### Buffers

```javascript
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

```javascript
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

```javascript
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](https://developer.mozilla.org/en-US/docs/Web/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.

[sharp]: https://github.com/lovell/sharp
[merge-img]: https://github.com/preco21/merge-img