custom-image-placeholder

A lightweight, zero-dependency Node.js utility to generate custom SVG placeholder image markup and Base64 Data URLs. Ideal for UI mockups, testing, image fallback states, and dynamic web application placeholders.

Features

• 🚀 Zero dependencies — extremely fast, lightweight, and runtime-agnostic (works in Node.js and modern browsers).
• 🎨 Fully Customisable — adjust dimensions, text, background color, text color, font family, and font size.
• 📐 Smart Sizing — automatically scales text font size based on image width and height if not custom specified.
• 🛡️ XML Safe — handles special characters in text (e.g. <, >, &, ") safely.
• 📦 Multiple Outputs — exports raw SVG XML markup or Base64-encoded Data URL strings (e.g., data:image/svg+xml;base64,...).

Installation

npm install custom-image-placeholder

Usage

const { generateSvg, generateDataUrl } = require('custom-image-placeholder');

// 1. Generate Raw SVG String
const svg = generateSvg({
  width: 400,
  height: 200,
  text: 'Hero Banner Mockup',
  bgColor: '#4f46e5', // indigo
  textColor: '#ffffff'
});

console.log(svg);
/* Output:
<svg xmlns="http://www.w3.org/2000/svg" width="400" height="200" viewBox="0 0 400 200">
  <rect width="100%" height="100%" fill="#4f46e5"/>
  <text x="50%" y="50%" dominant-baseline="middle" text-anchor="middle" font-family="sans-serif" font-size="25" fill="#ffffff">
    Hero Banner Mockup
  </text>
</svg>
*/

// 2. Generate Base64 Data URL (Perfect for HTML img src)
const dataUrl = generateDataUrl({
  width: 200,
  height: 200,
  bgColor: '#e2e8f0',
  textColor: '#475569'
});

console.log(dataUrl);
// Output: "data:image/svg+xml;base64,PHN2ZyB4bWxucz0..."

Options API

Both generateSvg(options) and generateDataUrl(options) accept the same configuration properties:

| Option | Type | Default | Description | |---|---|---|---| | width | number | 300 | Width of the image in pixels. | | height | number | 150 | Height of the image in pixels. | | text | string | "${width}x${height}" | Center text value. | | bgColor | string | '#cccccc' | Background color code (HEX, RGB, HSL, or name). | | textColor | string | '#333333' | Text color code (HEX, RGB, HSL, or name). | | fontSize | number | Auto-calculated | Size of the text in pixels. | | fontFamily | string | 'sans-serif' | Font family name. |

License

MIT