img-grid

Generate image grids from URLs (and highlight images).

Installation

npm install @visualizevalue/img-grid

Usage

import { grid } from '@visualizevalue/img-grid'
import { writeFileSync } from 'fs'

// Define image URLs with optional IDs
const images = [
  { url: 'https://example.com/image1.jpg', id: 'img1' },
  { url: 'https://example.com/image2.jpg', id: 'img2' },
  { url: 'https://example.com/image3.jpg', id: 'img3' },
  { url: 'https://example.com/image4.jpg', id: 'img4' },
]

// Create a grid with default options
const buffer = await grid(images)

// Or highlight specific images (makes them 2×2)
const highlightedBuffer = await grid(images, {
  highlight: ['img2', 'img3'], // Images with these IDs will be 2×2
  maxWidth: 1920, // Maximum width of output image
  concurrency: 10, // Maximum concurrent downloads
  background: '#000', // Fills background, padding, gutters, and letterboxing
  padding: 16, // Space around the whole grid, in pixels
  gutter: 8, // Gap between cells (rows and columns), in pixels
  pixelated: true, // Nearest-neighbour resize — keeps pixel art crisp
  format: 'webp', // Output as png (default), jpeg, or webp
  quality: 80, // Quality for jpeg/webp
  onError: (img, err) => console.warn(`failed: ${img.url}`, err),
})

// Save to file
writeFileSync('grid.png', buffer)

Features

• Packs images into a compact, near-square grid
• Supports highlighting specific images (makes them 2×2)
• Configurable background color, padding around the grid, and gutter between cells
• Optional nearest-neighbour scaling to keep pixel art crisp (pixelated)
• Downloads images concurrently (with a configurable limit)
• Leaves a blank cell for failed downloads instead of failing the grid
• Output as PNG, JPEG, or WebP
• Resizes all images to fit grid cells

Options

| Option | Default | Description | | ------------- | ----------- | -------------------------------------------------- | | highlight | [] | Array of image IDs to highlight (make 2×2) | | maxWidth | 1920 | Maximum width of output image in pixels | | concurrency | 10 | Maximum concurrent image downloads | | background | '#000' | Fills background, padding, gutters, letterboxing | | padding | 0 | Space around the whole grid, in pixels | | gutter | 0 | Gap between cells (rows and columns), in pixels | | pixelated | false | Nearest-neighbour resize; keeps pixel art crisp | | format | 'png' | Output format: 'png', 'jpeg', or 'webp' | | quality | sharp's | Quality (1–100) for jpeg/webp; ignored for png | | onError | undefined | (img, error) => void called when an image fails |