> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pictum.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Placeholders

> Create square or custom-dimension SVG, JPEG, PNG, or WebP placeholder images.

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.

<CodeGroup>
  ```tsx React theme={null}
  import { Placeholder } from "@pictum/react";

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

  ```vue Vue theme={null}
  <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>
  ```

  ```blade Laravel theme={null}
  <x-placeholder
    width="640"
    height="360"
    format="webp"
    density="2"
    background="#ffffff"
    color="#6d28d9"
    text="Coming soon"
    alt="Coming soon"
  />
  ```

  ```html Web theme={null}
  <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>
  ```
</CodeGroup>

## Use a helper

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

<CodeGroup>
  ```ts JavaScript theme={null}
  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();
  ```

  ```php PHP theme={null}
  // 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();
  ```
</CodeGroup>

## Preview

<Card title="640 x 360">
  <img src="https://pictum.dev/v1/placeholders/640x360@3x.png?background=%23ffffff&color=%236d28d9&text=Coming%20soon" alt="640 by 360 placeholder rendered at three times pixel density and reading Coming soon" width="640" height="360" />
</Card>

## 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:

```html theme={null}
<img
  src="https://pictum.dev/v1/placeholders/600x400.png"
  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

<Info>
  The [OpenAPI reference](/api-reference/overview) documents dimension constraints, query customization, caching, and validation errors.
</Info>