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

# Avatars

> Render generated and realistic avatars through Pictum integrations or direct image URLs.

Pictum integrations render generated avatars as native framework components. You can also use framework-independent helpers or direct image URLs, including realistic portraits.

## See the output

Every preview is loaded from `https://pictum.dev` through a normal image URL.

<Columns cols={3}>
  <Card title="Identicon">
    <img src="https://pictum.dev/v1/avatars/identicon/ada-lovelace.svg" alt="Identicon avatar generated from the seed ada-lovelace" width="160" height="160" />
  </Card>

  <Card title="Gradient">
    <img src="https://pictum.dev/v1/avatars/gradient/ada-lovelace.webp" alt="Gradient avatar generated from the seed ada-lovelace" width="160" height="160" />
  </Card>

  <Card title="Initials">
    <img src="https://pictum.dev/v1/avatars/initials/ada-lovelace.png" alt="Initials avatar showing AL for the seed ada-lovelace" width="160" height="160" />
  </Card>

  <Card title="Realistic (any)">
    <img src="https://pictum.dev/v1/avatars/realistic/studio-atlas.webp" alt="Realistic portrait selected across all genders with the seed studio-atlas" width="160" height="160" />
  </Card>

  <Card title="Realistic (female)">
    <img src="https://pictum.dev/v1/avatars/realistic/female/studio-orchid.webp" alt="Realistic female portrait selected with the seed studio-orchid" width="160" height="160" />
  </Card>

  <Card title="Realistic (male)">
    <img src="https://pictum.dev/v1/avatars/realistic/male/studio-harbor.webp" alt="Realistic male portrait selected with the seed studio-harbor" width="160" height="160" />
  </Card>
</Columns>

## Use your integration

Choose your framework to install its Pictum package and render a generated avatar. Each component forwards native image attributes, including `alt`, `width`, and `height`.

<Tabs>
  <Tab title="React" icon="https://pictum.dev/v1/icons/devicon/react.svg">
    ```bash theme={null}
    pnpm add @pictum/react
    ```

    ```tsx theme={null}
    import { Avatar } from "@pictum/react";

    export function ProfileAvatar() {
      return (
        <Avatar
          seed="ada-lovelace"
          variant="gradient"
          format="webp"
          alt="Ada Lovelace"
          width={48}
          height={48}
        />
      );
    }
    ```

    Continue with the [React integration guide](/integrations/react).
  </Tab>

  <Tab title="Vue" icon="https://pictum.dev/v1/icons/devicon/vuejs.svg">
    ```bash theme={null}
    pnpm add @pictum/vue
    ```

    ```vue theme={null}
    <script setup lang="ts">
    import { Avatar } from "@pictum/vue";
    </script>

    <template>
      <Avatar
        seed="ada-lovelace"
        variant="gradient"
        format="webp"
        alt="Ada Lovelace"
        width="48"
        height="48"
      />
    </template>
    ```

    Continue with the [Vue integration guide](/integrations/vue).
  </Tab>

  <Tab title="Laravel" icon="https://pictum.dev/v1/icons/devicon/laravel.svg">
    ```bash theme={null}
    composer require pictum/laravel
    ```

    ```blade theme={null}
    <x-avatar
      seed="ada-lovelace"
      variant="gradient"
      format="webp"
      alt="Ada Lovelace"
      width="48"
      height="48"
    />
    ```

    Continue with the [Laravel integration guide](/integrations/laravel).
  </Tab>

  <Tab title="Svelte" icon="https://pictum.dev/v1/icons/devicon/svelte.svg">
    ```bash theme={null}
    pnpm add @pictum/svelte
    ```

    ```svelte theme={null}
    <script lang="ts">
    import { Avatar } from "@pictum/svelte";
    </script>

    <Avatar
      seed="ada-lovelace"
      variant="gradient"
      format="webp"
      alt="Ada Lovelace"
      width="48"
      height="48"
    />
    ```

    Continue with the [Svelte integration guide](/integrations/svelte).
  </Tab>

  <Tab title="Astro" icon="https://pictum.dev/v1/icons/devicon/astro.svg">
    ```bash theme={null}
    pnpm add @pictum/astro
    ```

    ```astro theme={null}
    ---
    import { Avatar } from "@pictum/astro/components";
    ---

    <Avatar
      seed="ada-lovelace"
      variant="gradient"
      format="webp"
      alt="Ada Lovelace"
      width="48"
      height="48"
    />
    ```

    Continue with the [Astro integration guide](/integrations/astro).
  </Tab>
</Tabs>

### Standalone integrations

Use browser-native custom elements, framework-independent helpers, or direct image URLs.

<Tabs>
  <Tab title="HTTP" icon="globe">
    ```html theme={null}
    <img
      src="https://pictum.dev/v1/avatars/gradient/ada-lovelace.webp"
      alt="Ada Lovelace"
      width="48"
      height="48"
    />
    ```

    Review the [HTTP API reference](/api-reference/overview).
  </Tab>

  <Tab title="JavaScript" icon="https://pictum.dev/v1/icons/devicon/javascript.svg">
    ```bash theme={null}
    pnpm add @pictum/core
    ```

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

    const url = avatar("ada-lovelace", {
      variant: "gradient",
      format: "webp",
    }).url;
    ```

    Continue with the [JavaScript integration guide](/integrations/javascript).
  </Tab>

  <Tab title="PHP" icon="https://pictum.dev/v1/icons/skill-icons/php-light.svg">
    ```bash theme={null}
    composer require pictum/php
    ```

    ```php theme={null}
    $url = Pictum\avatar(
        'ada-lovelace',
        variant: 'gradient',
        format: 'webp',
    )->url();
    ```

    Continue with the [PHP integration guide](/integrations/php).
  </Tab>

  <Tab title="Web Components" icon="https://pictum.dev/v1/icons/devicon/html5.svg">
    ```bash theme={null}
    pnpm add @pictum/web
    ```

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

      definePictumElements();
    </script>

    <pictum-avatar
      seed="ada-lovelace"
      variant="gradient"
      format="webp"
      alt="Ada Lovelace"
      width="48"
      height="48"
    ></pictum-avatar>
    ```

    Continue with the [Web Components integration guide](/integrations/web-components).
  </Tab>
</Tabs>

## Choose an avatar type

### Generated avatars

Generated avatars are available through every integration component and helper. The same seed and variant always return the same design.

| Variant     | Result                              | Best for                      |
| ----------- | ----------------------------------- | ----------------------------- |
| `identicon` | Symmetric 5x5 pattern               | Compact abstract identities   |
| `gradient`  | Seeded palette, direction, and glow | Colorful profile placeholders |
| `initials`  | One or two characters from the seed | Recognizable names and labels |

### Realistic portraits

Realistic portraits are currently served through direct image URLs. Use them as a native image source in any framework or application.

<CodeGroup>
  ```html Any gender theme={null}
  <img
    src="https://pictum.dev/v1/avatars/realistic/customer-123.webp"
    alt="Customer profile"
  />
  ```

  ```html Female theme={null}
  <img
    src="https://pictum.dev/v1/avatars/realistic/female/customer-123.webp"
    alt="Customer profile"
  />
  ```

  ```html Male theme={null}
  <img
    src="https://pictum.dev/v1/avatars/realistic/male/customer-123.webp"
    alt="Customer profile"
  />
  ```
</CodeGroup>

The API hashes each seed into the current portrait catalog without storing the seed. Catalog updates may remap existing seeds, and cached responses can continue showing the previous portrait until they expire.

## Configure avatars

<AccordionGroup>
  <Accordion title="Choose a seed" icon="fingerprint" defaultOpen>
    Seeds accept 1-128 ASCII letters, numbers, and URL-safe separators. A seed must start and end with a letter or number.

    Use a stable opaque identifier that contains no sensitive information. Avatar URLs are public, cacheable, and may appear in logs or browser history.
  </Accordion>

  <Accordion title="Choose an image format" icon="images">
    | Format | Generated | Realistic | Use case                                     |
    | ------ | --------- | --------- | -------------------------------------------- |
    | `svg`  | Yes       | No        | Scalable generated avatars and inline markup |
    | `jpg`  | Yes       | Yes       | Compact opaque raster delivery               |
    | `png`  | Yes       | Yes       | Broad raster compatibility                   |
    | `webp` | Yes       | Yes       | Compact raster delivery                      |

    Generated raster avatars use a 256x256 source by default. Realistic avatars preserve their catalog source dimensions.
  </Accordion>
</AccordionGroup>

## Next steps

<Columns cols={2}>
  <Card title="Explore integrations" icon="blocks" href="/integrations/react">
    Review complete component and helper examples for your framework.
  </Card>

  <Card title="Use the HTTP API" icon="waypoints" href="/api-reference/overview">
    Inspect avatar routes, formats, caching headers, and errors.
  </Card>
</Columns>