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

# Web Components

> Use Pictum icon, avatar, QR code, and placeholder custom elements in browser applications.

## Installation

Install the Web Components package with your preferred package manager.

<CodeGroup>
  ```bash npm theme={null}
  npm install @pictum/web
  ```

  ```bash pnpm theme={null}
  pnpm add @pictum/web
  ```

  ```bash bun theme={null}
  bun add @pictum/web
  ```

  ```bash yarn theme={null}
  yarn add @pictum/web
  ```
</CodeGroup>

## Icons

Use `<pictum-icon>` in markup. Use `icon()` when script code needs the image URL or canonical SVG.

<CodeGroup>
  ```html Component theme={null}
  <script type="module">
    import { definePictumElements } from "@pictum/web";

    definePictumElements();
  </script>

  <pictum-icon
    name="devicon:html5"
    alt="HTML5"
    class="size-6"
  ></pictum-icon>
  ```

  ```ts Helper theme={null}
  import { icon } from "@pictum/web";

  // Generate the URL without making a request.
  const url = icon("devicon:html5").url;

  // Fetch canonical SVG markup.
  const svg = await icon("devicon:html5").svg();
  ```
</CodeGroup>

## Avatars

Use `<pictum-avatar>` for deterministic profile images. Use `avatar()` when script code needs a selected raster URL or canonical SVG.

<CodeGroup>
  ```html Component theme={null}
  <script type="module">
    import { definePictumElements } from "@pictum/web";

    definePictumElements();
  </script>

  <pictum-avatar
    seed="customer-123"
    variant="realistic"
    gender="female"
    format="webp"
    alt="Customer"
    class="size-10"
  ></pictum-avatar>
  ```

  ```ts Helper theme={null}
  import { avatar } from "@pictum/web";

  // Generate the URL without making a request.
  const url = avatar("customer-123", {
    variant: "realistic",
    gender: "female",
    format: "webp",
  }).url;

  // Fetch canonical SVG markup.
  const svg = await avatar("ada-lovelace", {
    variant: "gradient",
  }).svg();
  ```
</CodeGroup>

## QR codes

Use `<pictum-qr-code>` for scannable text or URLs. Use `qrCode()` when script code needs the image URL or canonical SVG.

<CodeGroup>
  ```html Component theme={null}
  <script type="module">
    import { definePictumElements } from "@pictum/web";

    definePictumElements();
  </script>

  <pictum-qr-code
    value="https://pictum.dev"
    format="svg"
    alt="Open Pictum"
    class="size-32"
  ></pictum-qr-code>
  ```

  ```ts Helper theme={null}
  import { qrCode } from "@pictum/web";

  // Generate the URL without making a request.
  const url = qrCode("https://pictum.dev", {
    format: "png",
  }).url;

  // Fetch canonical SVG markup.
  const svg = await qrCode("https://pictum.dev").svg();
  ```
</CodeGroup>

## Placeholders

Use `<pictum-placeholder>` for square or custom-dimension images. Use `placeholder()` when script code needs the selected image URL or SVG markup.

<CodeGroup>
  ```html Component theme={null}
  <script type="module">
    import { definePictumElements } from "@pictum/web";

    definePictumElements();
  </script>

  <pictum-placeholder
    size="320"
    format="webp"
    density="2"
    background="#ffffff"
    color="#6d28d9"
    text="Coming soon"
    alt="Coming soon"
  ></pictum-placeholder>
  ```

  ```ts Helper theme={null}
  import { placeholder } from "@pictum/web";

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

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

Helpers return the selected representation URL immediately. Calling `.svg()` retrieves canonical SVG markup for the same asset.