Placeholders

Framework integrations provide a Placeholder component, and every integration can generate placeholder URLs or SVG markup through its placeholder() helper.

Render a placeholder

Provide size for a square, or provide width and height for a custom aspect ratio.

import { Placeholder } from "@pictum/react";

<Placeholder
  width={640}
  height={360}
  format="webp"
  density={2}
  background="#ffffff"
  color="#6d28d9"
  text="Coming soon"
  alt="Coming soon"
/>

<script setup lang="ts">
import { Placeholder } from "@pictum/vue";
</script>

<template>
  <Placeholder
    :width="640"
    :height="360"
    format="webp"
    :density="2"
    background="#ffffff"
    color="#6d28d9"
    text="Coming soon"
    alt="Coming soon"
  />
</template>

<x-placeholder
  width="640"
  height="360"
  format="webp"
  density="2"
  background="#ffffff"
  color="#6d28d9"
  text="Coming soon"
  alt="Coming soon"
/>

<script type="module">
  import { definePictumElements } from "@pictum/web";

  definePictumElements();
</script>

<pictum-placeholder
  width="640"
  height="360"
  format="webp"
  density="2"
  background="#ffffff"
  color="#6d28d9"
  text="Coming soon"
  alt="Coming soon"
></pictum-placeholder>

Use a helper

Use placeholder() when you need the selected image URL or SVG markup outside a component.

import { placeholder } from "@pictum/react";

// Generate a WebP URL without making a request.
const url = placeholder({
  width: 640,
  height: 360,
  format: "webp",
  density: 3,
  text: "Coming soon",
}).url;

// Fetch a square as SVG markup.
const svg = await placeholder({
  size: 320,
  text: "Coming soon",
}).svg();

// Generate a WebP URL without making a request.
$url = Pictum\placeholder(
    width: 640,
    height: 360,
    format: 'webp',
    density: 3,
    text: 'Coming soon',
)->url();

// Fetch a square as SVG markup.
$svg = Pictum\placeholder(
    size: 320,
    text: 'Coming soon',
)->svg();

Preview

640 x 360

640 by 360 placeholder rendered at three times pixel density and reading Coming soon

Set dimensions

Square sizes accept 16–2048 logical pixels. Custom width and height values each accept 16–4096 logical pixels. At standard density, width multiplied by height may not exceed 4,194,304 pixels. SVG output includes matching width, height, and viewBox attributes, giving it an explicit default size and aspect ratio while remaining scalable.

Render retina images

Set density to 2 or 3 for high-density JPEG, PNG, or WebP output. Pictum keeps the requested dimensions as the logical size and multiplies each raster axis by the density. For example, 640x360@3x.png contains 1920×1080 pixels while retaining the default “640 x 360” label. JPEG and PNG output also carries 144 DPI metadata for @2x or 216 DPI for @3x. Browsers still use the physical raster dimensions intrinsically, so set the logical width and height when rendering the image. Rendered dimensions may not exceed 4096 pixels on either side or 4,194,304 total pixels after applying the density multiplier. SVG is already resolution-independent and does not accept a density. Use density variants in srcset and set the image’s logical display dimensions:

<img
  src="https://pictum.dev/v1/placeholders/600x400.png"
  srcset="https://pictum.dev/v1/placeholders/600x400@2x.png 2x, https://pictum.dev/v1/placeholders/600x400@3x.png 3x"
  width="600"
  height="400"
  alt=""
/>

Customize appearance

Components and helpers accept the following options:

Option	Description	Default
`text`	Centered label up to 64 characters	Requested dimensions
`background`	Background color in `#rrggbb` format	`#f1eef8`
`color`	Text and guide color in `#rrggbb` format	`#6d28d9`
`density`	Raster pixel density: `2` or `3`.	Standard density

Choose a format

Value	Content type	Dimensions	Retina
`svg`	`image/svg+xml; charset=UTF-8`	Requested intrinsic dimensions and matching `viewBox`	Not needed
`jpg`	`image/jpeg`	Logical dimensions multiplied by density	`@2x`, `@3x`
`png`	`image/png`	Logical dimensions multiplied by density	`@2x`, `@3x`
`webp`	`image/webp`	Logical dimensions multiplied by density	`@2x`, `@3x`

Direct HTTP access

The OpenAPI reference documents dimension constraints, query customization, caching, and validation errors.

Getting started

Assets

Integrations

Render a placeholder

Use a helper

Preview

640 x 360

Set dimensions

Render retina images

Customize appearance

Choose a format

Direct HTTP access

​Render a placeholder

​Use a helper

​Preview

640 x 360

​Set dimensions

​Render retina images

​Customize appearance

​Choose a format

​Direct HTTP access

Render a placeholder

Use a helper

Preview

Set dimensions

Render retina images

Customize appearance

Choose a format

Direct HTTP access