placeholdjs

placeholdjs

CLI tool to generate placeholder images locally with custom dimensions, colors, text and batch processing.

Features

• 📐 Custom Dimensions - Generate images of any size
• 🎨 Custom Colors - Set background and text colors with hex values
• ✏️ Custom Text - Add custom text or auto-display dimensions
• 📦 Batch Processing - Generate multiple images at once
• 🖼️ Multiple Formats - PNG, JPG, WebP support
• 🔲 Border Option - Add borders to images
• ⚡ Offline - Works without internet connection

Installation

npm install -g placeholdjs

Usage

Basic

# Generate 800x600 placeholder (saved to ~/.placehold/exports/)
placehold 800x600

# Specify output path
placehold 400x300 -o avatar.png

# Different format
placehold 1920x1080 -f jpg -o banner.jpg

Custom Colors

# Custom background
placehold 500x500 -b "#3498db" -o blue.png

# Custom background and text color
placehold 800x600 -b "#2c3e50" -c "#ecf0f1" -o dark.png

# Using short hex
placehold 300x300 -b "#f00" -c "#fff" -o red.png

Custom Text

# Custom text
placehold 800x400 -t "Hero Image" -o hero.png

# Custom text with font size
placehold 400x200 -t "Avatar" -s 24 -o avatar.png

# Auto font size (default)
placehold 1200x630 -t "Open Graph Image" -o og.png

With Border

# Add border
placehold 300x300 --border -o bordered.png

# Border with colors
placehold 500x500 -b "#fff" --border -o card.png

Batch Processing

# Generate 10 placeholders
placehold 400x300 --batch 10

# Batch with custom output directory
placehold 800x600 --batch 5 -o ./placeholders/

# Batch with styling
placehold 300x200 --batch 20 -b "#e74c3c" -f webp

Options

Option	Alias	Description	Default
--output	-o	Output file path	~/.placehold/exports/
--format	-f	Output format (png, jpg, webp)	png
--background	-b	Background color (hex)	#CCCCCC
--color	-c	Text color (hex)	#666666
--text	-t	Custom text to display	dimensions
--fontsize	-s	Font size (px) or "auto"	auto
--border	-	Add border to image	false
--batch	-	Number of images to generate	-
--version	-v	Show version	-
--help	-h	Show help	-

Output Directory

By default, images are saved to ~/.placehold/exports/. Override with -o:

# Default directory
placehold 800x600
# Output: ~/.placehold/exports/hold-800x600-1703698800000.png

# Custom path
placehold 800x600 -o ./images/hero.png
# Output: ./images/hero.png

# Custom filename (in default directory)
placehold 800x600 -o myimage.png
# Output: ~/.placehold/exports/myimage.png

Color Formats

Supports hex colors in multiple formats:

• #RGB → #F00 (red)
• #RRGGBB → #FF0000 (red)
• #RGBA → #F00F (red, full opacity)
• #RRGGBBAA → #FF0000FF (red, full opacity)

Use Cases

Web Development

# Product thumbnails
placehold 300x300 --batch 20 -o ./products/

# Hero banners
placehold 1920x600 -t "Hero Banner" -o hero.png

# Avatar placeholders
placehold 100x100 -b "#3498db" -c "#fff" -t "U" -o avatar.png

Social Media

# Open Graph
placehold 1200x630 -t "OG Image" -o og.png

# Twitter Card
placehold 1200x600 -t "Twitter Card" -o twitter.png

# Instagram Post
placehold 1080x1080 -o instagram.png

Prototyping

# Mobile screens
placehold 375x812 -t "iPhone" -o iphone.png
placehold 390x844 -t "iPhone 14" -o iphone14.png

# Desktop
placehold 1920x1080 -t "Desktop" -o desktop.png

Why placeholdjs?

Feature	placeholdjs	Online Services
Offline	✅	❌
No rate limits	✅	❌
Batch generation	✅	Limited
Custom fonts	✅	Limited
Privacy	✅ Local	❌ Server
Speed	✅ Instant	Depends on network

License

MIT © CasDevSilva