# FreePlaceholder.com

> Free placeholder image and avatar API. No signup required. Generate images of any size and format with customizable colors and text. Powered by deterministic color hashing for unique, accessible color pairs.

## Placeholder Images

Generate placeholder images by specifying dimensions in the URL.

### Basic Usage

- `https://freeplaceholder.com/{width}x{height}` — SVG placeholder (default)
- `https://freeplaceholder.com/{width}x{height}.png` — PNG format
- `https://freeplaceholder.com/{width}x{height}.jpg` — JPEG format
- `https://freeplaceholder.com/{width}x{height}.webp` — WebP format

### Custom Colors

Specify hex colors (without #) using query parameters:

- `https://freeplaceholder.com/600x400?bg=3b82f6&text-color=ffffff` — Blue background, white text

### Query Parameters

All query parameters are named after [Tailwind CSS](https://tailwindcss.com) utility classes.

| Parameter | Description | Example |
|-----------|-------------|---------|
| `bg` | Background hex color (without #) | `?bg=3b82f6` |
| `text-color` | Text hex color (without #) | `?text-color=ffffff` |
| `text` | Custom text overlay | `?text=Hello` |
| `text-size` | Font size in pixels | `?text-size=32` |
| `text-align` | Text alignment: left, center, right | `?text-align=left` |
| `text-transform` | Transform: uppercase, lowercase, capitalize | `?text-transform=uppercase` |
| `text-decoration` | Decoration: underline, overline, line-through | `?text-decoration=underline` |
| `letter-spacing` | Spacing: tighter, tight, wide, wider, widest, or px | `?letter-spacing=wide` |
| `font-weight` | Font weight (Tailwind values) | `?font-weight=bold` |
| `opacity` | Opacity 0–100 | `?opacity=50` |
| `blur` | Gaussian blur in px (0–100) | `?blur=4` |
| `brightness` | Brightness 0–200 (100 = normal) | `?brightness=120` |
| `contrast` | Contrast 0–200 (100 = normal) | `?contrast=150` |
| `hue-rotate` | Hue rotation 0–360 degrees | `?hue-rotate=90` |
| `invert` | Invert colors | `?invert` |
| `saturate` | Saturation 0–200 (100 = normal) | `?saturate=150` |
| `sepia` | Sepia tone filter | `?sepia` |
| `grayscale` | Grayscale filter | `?grayscale` |
| `border` | Border width in px | `?border=4` |
| `border-color` | Border hex color (without #) | `?border-color=000000` |
| `border-style` | Border style | `?border-style=dashed` |
| `rounded` | Border radius: sm, md, lg, xl, 2xl, 3xl, full, or px | `?rounded=lg` |
| `format` | Output format: svg, png, jpg, webp | `?format=png` |

**Font weight values:** thin, extralight, light, normal, medium, semibold, bold, extrabold, black

**Border style values:** solid (default), dashed, dotted, double, none

**Letter spacing values:** tighter, tight, normal, wide, wider, widest (or a number in px)

**Rounded values:** none, sm (2px), md (6px), lg (8px), xl (12px), 2xl (16px), 3xl (24px), full (or a number in px)

### Examples

- `https://freeplaceholder.com/600x400` — 600x400 SVG with auto-generated colors
- `https://freeplaceholder.com/1920x1080.png` — Full HD PNG placeholder
- `https://freeplaceholder.com/300x200?bg=0ea5e9&text-color=ffffff&text=Banner` — Cyan with "Banner" text
- `https://freeplaceholder.com/800x600?text=Loading...&text-size=48` — Custom text and size
- `https://freeplaceholder.com/600x400?font-weight=bold&border=4&border-color=000000` — Bold text with border
- `https://freeplaceholder.com/600x400?grayscale&opacity=80` — Grayscale at 80% opacity
- `https://freeplaceholder.com/600x400?blur=3&brightness=120` — Blurred with boosted brightness
- `https://freeplaceholder.com/600x400?text-transform=uppercase&letter-spacing=wide` — Uppercase with wide spacing
- `https://freeplaceholder.com/600x400?rounded=lg&border=2` — Rounded corners with border

### Limits

- Max dimensions: 4096x4096
- Min dimensions: 1x1
- Supported formats: SVG, PNG, JPEG, WebP

## Snippet images (Open Graph)

- `https://freeplaceholder.com/snippet` — 1200×630 PNG share image (default size and format)
- `https://freeplaceholder.com/snippet.svg`, `https://freeplaceholder.com/snippet.webp`, etc. — other formats via path extension
- Query: `title`, `subtitle`, `cta`, `logo` (public `https` URL to a PNG/JPEG/GIF/WebP logo), plus `width` / `height` overrides
- Same Tailwind-style styling parameters as placeholders (`bg`, `gradient`, `text-color`, `font-weight`, filters, borders, etc.); `text` is not used

Use `snippetUrl()` from `@freeplaceholder/core` or any framework package to build URLs in TypeScript.

## Avatars

Generate avatar images from names or initials.

### Basic Usage

- `https://freeplaceholder.com/avatar/{name}` — SVG avatar (default)
- `https://freeplaceholder.com/avatar/{name}.png` — PNG format
- `https://freeplaceholder.com/avatar/John+Doe` — Avatar with initials "JD"
- `https://freeplaceholder.com/avatar/alice` — Avatar with initial "A"

### Query Parameters

| Parameter | Description | Default | Example |
|-----------|-------------|---------|---------|
| `size` | Avatar dimensions (square) | 128 | `?size=256` |
| `bg` | Background hex color (without #) | auto | `?bg=6366f1` |
| `text-color` | Text hex color (without #) | auto | `?text-color=ffffff` |
| `text-decoration` | Decoration: underline, overline, line-through | none | `?text-decoration=underline` |
| `letter-spacing` | Letter spacing (Tailwind values or px) | auto | `?letter-spacing=wide` |
| `font-weight` | Font weight (Tailwind values) | semibold | `?font-weight=bold` |
| `opacity` | Opacity 0–100 | 100 | `?opacity=50` |
| `blur` | Gaussian blur in px (0–100) | 0 | `?blur=2` |
| `brightness` | Brightness 0–200 (100 = normal) | 100 | `?brightness=120` |
| `contrast` | Contrast 0–200 (100 = normal) | 100 | `?contrast=150` |
| `hue-rotate` | Hue rotation 0–360 degrees | 0 | `?hue-rotate=90` |
| `invert` | Invert colors | false | `?invert` |
| `saturate` | Saturation 0–200 (100 = normal) | 100 | `?saturate=150` |
| `sepia` | Sepia tone filter | false | `?sepia` |
| `grayscale` | Grayscale filter | false | `?grayscale` |
| `border` | Border width in px | 0 | `?border=3` |
| `border-color` | Border hex color (without #) | auto | `?border-color=ffffff` |
| `border-style` | Border style | solid | `?border-style=dashed` |
| `rounded` | Border radius: sm, md, lg, xl, 2xl, 3xl, full, or px | none | `?rounded=full` |
| `format` | Output format: svg, png, jpg, webp | svg | `?format=png` |

### Examples

- `https://freeplaceholder.com/avatar/John+Doe` — "JD" avatar with hashed colors
- `https://freeplaceholder.com/avatar/alice.png?size=256` — 256px PNG avatar for "alice"
- `https://freeplaceholder.com/avatar/Bob?bg=ef4444&text-color=ffffff` — Red avatar for "Bob"
- `https://freeplaceholder.com/avatar/Eve?grayscale&border=3&border-color=ffffff` — Grayscale with border

### Limits

- Max size: 1024x1024
- Default size: 128x128

## Color Hashing

When no custom colors are provided, the API uses a deterministic hash of the request path to generate a unique color palette. The same URL always produces the same colors. Foreground colors are automatically chosen for WCAG AA contrast compliance.

## Caching

All image responses include aggressive cache headers (`Cache-Control: public, max-age=31536000, immutable`). Responses are served through CloudFront CDN for fast global delivery. Identical URLs always produce identical images, making caching safe and effective.

## Integration

### HTML

```html
<img src="https://freeplaceholder.com/600x400.png" alt="Placeholder" width="600" height="400">
<img src="https://freeplaceholder.com/avatar/John+Doe.png" alt="John Doe" width="128" height="128">
```

### Markdown

```markdown
![Placeholder](https://freeplaceholder.com/600x400.png)
![Avatar](https://freeplaceholder.com/avatar/John+Doe.png)
```

### CSS

```css
.hero {
  background-image: url('https://freeplaceholder.com/1920x1080.svg');
}
```