Placeholder Tag

Generate placeholder images at build time for development, prototyping, and testing layouts before final assets are ready.

Introduction

The @placeholder tag generates placeholder images at build time, eliminating the need for actual image files during development and prototyping. This is especially useful for templates, wireframes, and when you need to test layouts before final assets are ready.

Key features:

  • Processed at build time (not runtime)
  • Replaced with actual image URLs
  • Supports three different placeholder services
  • Custom dimensions, colors, text, and styling options
  • Default service is placehold.co

Basic Usage

To use the placeholder tag, include it in an img tag's src attribute:

<img src="<!-- @placeholder 400x300 -->" alt="Placeholder image">

Required: Dimensions

Dimensions must be specified in WIDTHxHEIGHT format:

<!-- Basic placeholder -->
<img src="<!-- @placeholder 400x300 -->" alt="Image">

<!-- Square placeholder -->
<img src="<!-- @placeholder 300x300 -->" alt="Square image">

<!-- If only one dimension provided, it's used for both width and height -->
<img src="<!-- @placeholder 500 -->" alt="Square 500x500">

Output: The tag is replaced with a URL like https://placehold.co/400x300

Services

Hammer supports three placeholder image services, each with different features:

1. placehold.co (Default)

Default service - Simple, fast, supports custom colors and text.

<!-- Basic usage (default service) -->
<img src="<!-- @placeholder 400x300 -->" alt="Image">

Features:

  • Custom background and text colors
  • Custom text overlay
  • Custom fonts
  • Multiple image formats (PNG, JPG, GIF, WEBP)

2. picsum (Lorem Picsum)

Real photos - Uses actual photographs from Unsplash.

<!-- Lorem Picsum service -->
<img src="<!-- @placeholder 400x300 service=picsum -->" alt="Photo">

Features:

  • Real photographs (not generated graphics)
  • Specific image IDs for consistent images
  • Grayscale option
  • Blur effect

3. placeholders.dev

Advanced customization - More control over styling and appearance.

<!-- Placeholders.dev service -->
<img src="<!-- @placeholder 400x300 service=placeholders -->" alt="Image">

Features:

  • Custom background colors
  • Custom text colors
  • Custom text overlay
  • Custom font families

Options and Parameters

Color Options

Background and Text Colors:

<!-- Using color parameters -->
<img src="<!-- @placeholder 400x300 bgColor=ff0000 textColor=ffffff -->" alt="Red background, white text">

<!-- Using shorthand (placehold.co only) -->
<img src="<!-- @placeholder 400x300 ff0000/ffffff -->" alt="Red background, white text">

Color Format:

  • Hex colors without # (e.g., ff0000 for red, ffffff for white)
  • Works with all services

Text Overlay

Add custom text to placeholder images:

<!-- Custom text -->
<img src="<!-- @placeholder 400x300 text=Project+Image -->" alt="Project Image">

<!-- Text with spaces (use + or %20) -->
<img src="<!-- @placeholder 400x300 text=My+Project+Name -->" alt="My Project Name">
Note: Use + or URL-encoded spaces for multi-word text.

Font Customization

Specify custom fonts (service-dependent):

<!-- Custom font (placehold.co and placeholders.dev) -->
<img src="<!-- @placeholder 400x300 text=Hello font=arial -->" alt="Hello">

Image Formats

Specify output format (placehold.co only):

<!-- PNG format -->
<img src="<!-- @placeholder 400x300 .png -->" alt="PNG image">

<!-- JPG format -->
<img src="<!-- @placeholder 400x300 .jpg -->" alt="JPG image">

<!-- WEBP format -->
<img src="<!-- @placeholder 400x300 .webp -->" alt="WEBP image">

Picsum-Specific Options

Image ID (for consistent images):

<!-- Specific image by ID -->
<img src="<!-- @placeholder 400x300 service=picsum id=237 -->" alt="Specific photo">

Grayscale:

<!-- Grayscale photo -->
<img src="<!-- @placeholder 400x300 service=picsum grayscale -->" alt="Grayscale photo">

Blur Effect:

<!-- Blurred photo (blur amount 1-10) -->
<img src="<!-- @placeholder 400x300 service=picsum blur=5 -->" alt="Blurred photo">

Combined Picsum Options:

<!-- Grayscale and blurred -->
<img src="<!-- @placeholder 400x300 service=picsum grayscale blur=3 -->" alt="Grayscale blurred">

Complete Examples

Example 1: Basic Portfolio Project Image

<article class="project">
    <img src="<!-- @placeholder 400x300 -->" alt="Project screenshot">
    <h3>My Project</h3>
</article>

Example 2: Branded Placeholder with Colors

<!-- Using brand colors -->
<img src="<!-- @placeholder 600x400 bgColor=2563eb textColor=ffffff text=My+Brand -->" alt="Branded placeholder">

Example 3: Real Photo for Hero Section

<!-- Hero image using real photos -->
<img src="<!-- @placeholder 1200x600 service=picsum -->" alt="Hero image">

Example 4: Consistent Image Across Pages

<!-- Same photo every time using ID -->
<img src="<!-- @placeholder 400x300 service=picsum id=237 -->" alt="Consistent image">

Example 5: Profile Photo Placeholder

<!-- Square profile photo -->
<img src="<!-- @placeholder 300x300 text=Profile+Photo -->" alt="Profile photo">

Example 6: Custom Styled Placeholder

<!-- Fully customized -->
<img src="<!-- @placeholder 800x600 bgColor=1a1a1a textColor=e5e5e5 text=Coming+Soon font=roboto .png -->" alt="Coming soon">

Use Cases

1. Template Development

When creating templates before final assets are ready:

<div class="work-grid">
    <img src="<!-- @placeholder 400x300 -->" alt="Project 1">
    <img src="<!-- @placeholder 400x300 -->" alt="Project 2">
    <img src="<!-- @placeholder 400x300 -->" alt="Project 3">
</div>

2. Responsive Design Testing

Test different aspect ratios:

<!-- Mobile -->
<img src="<!-- @placeholder 375x667 -->" alt="Mobile view">

<!-- Tablet -->
<img src="<!-- @placeholder 768x1024 -->" alt="Tablet view">

<!-- Desktop -->
<img src="<!-- @placeholder 1920x1080 -->" alt="Desktop view">

3. Content Placeholders

Show where content will appear:

<img src="<!-- @placeholder 600x400 text=Article+Image -->" alt="Article image">

4. Design System Documentation

Demonstrate components with consistent placeholders:

<!-- Card component example -->
<div class="card">
    <img src="<!-- @placeholder 300x200 service=picsum id=237 -->" alt="Card image">
    <h3>Card Title</h3>
</div>

Service Comparison

Feature placehold.co (Default) picsum placeholders.dev
Image Type Generated graphics Real photos Generated graphics
Custom Colors ✅ ❌ ✅
Custom Text ✅ ❌ ✅
Custom Fonts ✅ ❌ ✅
Image Formats PNG, JPG, GIF, WEBP JPG only JPG only
Image ID ❌ ✅ ❌
Grayscale ❌ ✅ ❌
Blur Effect ❌ ✅ ❌

Best Practices

  • Use appropriate dimensions - Match the actual image dimensions you'll use
  • Choose the right service - Use picsum for realistic photos, placehold.co for branded placeholders
  • Use image IDs with picsum - For consistent images across builds, use id=
  • Replace before production - Remember to replace placeholders with actual images before deploying
  • Use descriptive alt text - Always include meaningful alt attributes
  • Test different sizes - Use placeholders to test responsive layouts

Common Patterns

Pattern 1: Grid of Placeholders

<div class="grid">
    <!-- @loop item in items -->
    <img src="<!-- @placeholder 300x300 -->" alt="<!-- @item.title -->">
    <!-- @endloop -->
</div>

Pattern 2: Hero Section

<section class="hero">
    <img src="<!-- @placeholder 1920x1080 service=picsum -->" alt="Hero image">
</section>

Pattern 3: Avatar/Profile

<img src="<!-- @placeholder 150x150 text=Avatar -->" alt="User avatar" class="avatar">

Technical Notes

  • Build-time processing: Placeholders are replaced during the build process, not at runtime
  • URL generation: The tag is replaced with a complete URL to the placeholder service
  • No external dependencies: Placeholder services are third-party and require internet access during build
  • Caching: Generated URLs are static and can be cached by browsers
  • Performance: Placeholder services are fast, but consider replacing with actual optimized images for production

Migration from @path

If you're currently using @path for missing images:

Before:

<img src="<!-- @path project1.jpg -->" alt="Project">

After:

<img src="<!-- @placeholder 400x300 -->" alt="Project">

This provides actual images during development instead of broken image links.

Frequently Asked Questions

Can placeholders be used in CSS?

No, placeholders can only be used in HTML. They are processed during build time and replaced with URLs, so they won't work in CSS files.

Are placeholders cached?

URLs generated by the placeholder tag are static, so browser caching applies normally. The placeholder services themselves may also cache images.

Can I use placeholders in production?

Technically yes, but it's not recommended. Placeholder services are third-party and may have rate limits or downtime. Always use actual optimized images for production sites.

What happens if the placeholder service is down?

Images won't load. Always have a fallback plan and replace placeholders with actual images before deploying to production.

Can I combine multiple options?

Yes, space-separated options work together. For example: <!-- @placeholder 400x300 service=picsum grayscale blur=3 -->

Next Steps

Now that you understand the placeholder tag, learn about:

  • Clever Paths - For referencing actual image assets
  • Assets - How Hammer handles image files
  • Variables - Combine with placeholders for dynamic content