DOCSEARCHbyAlgolia
Submit Docs

placeholders.dev

repository·main·Indexed 41 days ago

https://github.com/cherry/placeholders.dev

A high-performance placeholder image generation service deployed on Cloudflare Workers. It allows developers to generate custom-sized, styled SVG images via simple URL requests or query parameters across 330+ edge locations. Version 1.0.0 includes support for custom dimensions, colors, typography, and WebMCP for AI agent integration.

Tokens
2.1K
Snippets
5
Records
8
Agent score
51%

What's inside placeholders.dev

  1. Use WebMCP for AI agent integration

    main

    placeholders.dev implements the draft WebMCP navigator.modelContext API. This allows AI agents to interact with the service via tools without manual setup. The tools are implemented in public/webmcp.js and perform URL construction locally in the browser.

    Available WebMCP Tools

    • generate_placeholder_image_url: Builds a validated image URL from API options and returns HTML/Markdown snippets. It validates inputs (e.g., rejecting unparseable colors) and renders the result on the page.
    • explain_placeholder_image_url: Deconstructs an existing URL into its constituent options, resolves defaults, and identifies ignored parameters.

  2. Develop and deploy placeholders.dev

    main

    Use the following npm scripts to manage the development lifecycle of the Cloudflare Worker:

    Local Development

    Start a local server for testing using wrangler dev:

    npm run start:dev

    Deployment

    • Publish to staging: npm run publish:staging (pushes to placeholders-staging.workers.dev)
    • Publish to dev: npm run publish (pushes to placeholders-dev.workers.dev)
    • Publish to production: npm run publish:prod (publishes to placeholders.dev via Workers)
    npm run start:dev
npm run publish
npm run publish:staging
npm run publish:prod

  3. Generate placeholder images with placeholders.dev

    main

    placeholders.dev is a high-performance service that generates custom placeholder images on the fly at Cloudflare's Edge. You can generate images using simple URL paths or by providing specific query parameters to customize dimensions, text, and colors.

    URL Formats

    • Basic path: https://images.placeholders.dev/{width}
    • Dimension path: https://images.placeholders.dev/{width}x{height}
    • Query parameter path: https://images.placeholders.dev/?width={width}&height={height}&text={text}&bgColor={bgColor}&textColor={textColor}
    https://images.placeholders.dev/350x150
https://images.placeholders.dev/?width=1055&height=100&text=Hello%20World&bgColor=%23434343&textColor=%23dfdfde

  4. Generate SVG placeholders via API

    main

    The placeholders.dev service allows you to generate SVG placeholder images via URL patterns and query parameters.

    URL Patterns

    • Size-based path: You can specify dimensions directly in the URL path.
      • /350 sets both width and height to 350.
      • /350x150 sets width to 350 and height to 150.
    • API endpoint: In development environments, the API is accessed via the /api prefix.
    • Production subdomain: In production, images are served from images.placeholders.dev.

    Query Parameters

    The following options can be passed as query parameters to customize the SVG:

    • width: Image width
    • height: Image height
    • text: The text to display in the placeholder
    • dy: Vertical offset for the text
    • fontFamily: Font family name
    • fontWeight: Font weight
    • fontSize: Font size
    • bgColor: Background color
    • textColor: Text color
    • darkBgColor: Background color for dark mode
    • darkTextColor: Text color for dark mode
    • textWrap: Whether to wrap text

    Response Headers

    • Content-Type: image/svg+xml; charset=utf-8
    • Access-Control-Allow-Origin: * (CORS enabled)
    • X-Worker-Cache: Set to true if the response was served from the Cloudflare edge cache.
    • Cache-Control: Managed by the service to optimize delivery.
    // Example: Requesting a 350x150 placeholder with custom text and background
// https://images.placeholders.dev/350x150?text=Hello+World&bgColor=%23ff0000

  5. Configure environment variables for placeholders.dev

    main

    The Env interface defines the environment variables available to the application.

    • ASSETS: A Fetcher used to retrieve assets.
    • PLACEHOLDERS_ANALYTICS (optional): An AnalyticsEngineDataset used for analytics tracking.

  6. Reference the placeholders.dev API options

    main

    When using the full query parameter path, you can customize the image using the following options:

    OptionDescriptionDefault
    widthWidth of generated image300
    heightHeight of generated image150
    textText to display on generated imageImage dimensions
    fontFamilyFont to use for the textsans-serif
    fontWeightFont weight to use for the textbold
    fontSizeFont size (20% of shortest dimension, rounded down)Calculated
    dyVertical centering adjustment (35% of font size)Calculated
    bgColorBackground color of the image#ddd
    textColorColor of the text (supports rgba or hsla)rgba(0,0,0,0.5)
    textWrapWrap text to fit within the imagefalse

  7. Generate SVG placeholders with `simpleSvgPlaceholder()`

    main

    The simpleSvgPlaceholder function generates an SVG string or a Data URI representing a placeholder image. It is useful for creating dynamic, customizable image placeholders for development or testing.

    By default, it returns a Data URI (data:image/svg+xml...). If you set the dataUri option to false, it returns the raw, minified SVG string instead.

    import { simpleSvgPlaceholder } from './simple-svg-placeholder';

// Default usage (returns a Data URI)
const placeholderUri = simpleSvgPlaceholder();

// Custom usage (returns a Data URI with specific dimensions and text)
const customUri = simpleSvgPlaceholder({
  width: 500,
  height: 300,
  text: 'Custom Placeholder',
  bgColor: '#f0f0f0',
  textColor: '#333'
});

// Get raw SVG string instead of Data URI
const rawSvg = simpleSvgPlaceholder({
  dataUri: false,
  text: 'Raw SVG'
});

  8. Configure `simpleSvgPlaceholder` options

    main

    The Options object allows you to customize the appearance and behavior of the generated SVG.

    Dimensions and Text

    • width (number): The width of the SVG. Defaults to 300.
    • height (number): The height of the SVG. Defaults to 150.
    • text (string): The text to display inside the placeholder. Defaults to "${width}×${height}".
    • padding (string): CSS padding value used when textWrap is enabled. Defaults to '0.5em'.

    Typography

    • fontFamily (string): CSS font family. Defaults to 'sans-serif'.
    • fontWeight (string | number): CSS font weight. Defaults to 'bold'.
    • fontSize (number): Font size in pixels. Defaults to 20% of the smaller dimension.
    • lineHeight (number): Line height for text wrapping. Defaults to 1.2.
    • dy (number): Vertical offset for the <text> element (used when textWrap is false). Defaults to fontSize * 0.35.

    Colors and Dark Mode

    • bgColor (string): Background color. Defaults to '#ddd'.
    • textColor (string): Text color. Defaults to 'rgba(0,0,0,0.5)'.
    • darkBgColor (string): Background color used when the user's system is in dark mode (prefers-color-scheme: dark).
    • darkTextColor (string): Text color used when the user's system is in dark mode.

    Behavior and Encoding

    • textWrap (boolean): If true, uses an HTML <div> inside a <foreignObject> to allow text wrapping. If false, uses a standard SVG <text> element (single line).
    • dataUri (boolean): If true, returns a data:image/svg+xml URI. If false, returns the raw SVG string. Defaults to true.
    • charset (string): The character set for the Data URI. Defaults to 'UTF-8'.
    type Options = {
	width?: number;
	height?: number;
	text?: string;
	dy?: number;
	fontFamily?: string;
	fontWeight?: string | number;
	fontSize?: number;
	lineHeight?: number;
	bgColor?: string;
	textColor?: string;
	darkBgColor?: string;
	darkTextColor?: string;
	dataUri?: boolean;
	charset?: string;
	textWrap?: boolean;
	padding?: string;
};