Getting Started

FreePlaceholder.com is a free API for generating placeholder images and avatars. There are no accounts, no API keys, and no rate limits. Just construct a URL and use it anywhere images are accepted.

Placeholder Images

Add dimensions to the URL to generate a placeholder image.

https://freeplaceholder.com/{width}x{height}

For example, https://freeplaceholder.com/600x400 generates a 600x400 SVG image.

Choose a format

Append a file extension to choose the output format:

Custom colors

Add hex colors (without #) using query parameters:

https://freeplaceholder.com/600x400?bg=3b82f6&text-color=ffffff

If no colors are provided, the API generates a unique, accessible color pair from the URL.

Custom text

https://freeplaceholder.com/600x400?text=Hello+World&text-size=32

Avatars

Generate avatar images from any name:

https://freeplaceholder.com/avatar/John+Doe

This produces a square avatar with the initials "JD" and a deterministic color palette. Append .png, .jpg, or .webp for raster formats. Use ?size=256 to control dimensions (default: 128px, max: 1024px). Use ?rounded=full for a circular avatar.

Snippet images (Open Graph)

Build share-card style images with **title**, **subtitle**, **call to action**, and an optional **logo** URL.

https://freeplaceholder.com/snippet
https://freeplaceholder.com/snippet.png

Default size is **1200×630** (Open Graph). Override with ?width= and ?height= (same min/max as placeholder images). Default output format is **PNG**; use /snippet.svg, /snippet.webp, etc., or ?format=.

Snippet query parameters

All Tailwind-style parameters for colors, gradients, typography, filters, and borders apply the same way as placeholder images (except text, which is not used on snippets).

TypeScript URL builder

Use snippetUrl() from @freeplaceholder/core (or any framework package) the same way as placeholderUrl():

import { snippetUrl } from "@freeplaceholder/core";

const ogImage = snippetUrl({
  title: "Ship faster",
  subtitle: "API-first placeholders",
  cta: "Read the docs",
  format: "png",
});

Limits

• Max image dimensions: 4096 x 4096
• Max avatar size: 1024 x 1024
• Supported formats: SVG, PNG, JPEG, WebP

Lazy Loading

All framework components support native lazy loading via the lazy prop. When enabled (the default), the component renders with loading="lazy" and shows a lightweight inline SVG placeholder matching the bg color while the full image loads.

<Placeholder width={600} height={400} bg="3b82f6" />       {/* lazy by default */}
<Placeholder width={600} height={400} lazy={false} />       {/* eager loading */}

Query Parameters

All query parameters are named after Tailwind CSS utility classes.