Astro

SSR

Installation

Install the Astro 7+ package with your preferred package manager.

npm install @pictum/astro

pnpm add @pictum/astro

bun add @pictum/astro

yarn add @pictum/astro

Agent skill

Install the Astro integration skill for coding agents that support Agent Skills:

npx skills add usepictum/skills@astro

Configuration

Components use the production Pictum API by default. Add the integration when every component should use another deployment:

import pictum from "@pictum/astro";
import { defineConfig } from "astro/config";

export default defineConfig({
  integrations: [
    pictum({ baseUrl: "https://assets.example.com/v1" }),
  ],
});

Pass options={{ baseUrl }} to one component to override this setting. Helpers imported from @pictum/astro are direct framework-independent helpers and do not read the Astro integration configuration; pass baseUrl to those calls explicitly.

Icons

Render an icon with Icon, or use icon() in the frontmatter script when you need its URL or SVG markup.

---
import { Icon } from "@pictum/astro/components";
---

<Icon
  name="devicon:astro"
  aria-label="Astro"
  class="size-6"
/>

import { icon } from "@pictum/astro";

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

// Fetch canonical SVG markup.
const svg = await icon("devicon:astro").svg();

Icon fetches and caches canonical SVG markup during rendering, then emits inline SVG.

Avatars

Render a generated avatar or portrait with Avatar, or use avatar() to pass the selected image URL to another service. Generated avatars also provide canonical SVG markup.

---
import { Avatar } from "@pictum/astro/components";
---

<Avatar
  seed="customer-123"
  variant="portrait"
  gender="female"
  format="webp"
  size={256}
  alt="Customer"
  class="size-10"
/>

import { avatar } from "@pictum/astro";

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

// Fetch canonical SVG markup.
const svg = await avatar("ada-lovelace", {
  variant: "monogram",
}).svg();

QR codes

Render scannable text or URLs with QrCode, or use qrCode() when frontmatter code needs the image URL or canonical SVG.

---
import { QrCode } from "@pictum/astro/components";
---

<QrCode
  value="https://pictum.dev"
  format="svg"
  quietZone={false}
  foreground="#4c1d95ff"
  background="#ede9fe"
  aria-label="Open Pictum"
  class="size-32"
/>

import { qrCode } from "@pictum/astro";

// Generate the URL without making a request.
const url = qrCode("https://pictum.dev", {
  format: "svg",
  quietZone: false,
  foreground: "#4c1d95ff",
  background: "#ede9fe",
}).url;

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

Placeholders

Render square or custom-dimension images with Placeholder, or use placeholder() when frontmatter code needs the selected image URL or SVG markup.

---
import { Placeholder } from "@pictum/astro/components";
---

<Placeholder
  size={320}
  format="webp"
  density={2}
  background="#ffffff"
  color="#6d28d9"
  text="Coming soon"
  alt="Coming soon"
/>

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

// 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();

Avatar, QR code, and placeholder components render native images; placeholders also include their logical width and height. Helpers return an asset immediately. Reading .url makes no request; .svg() fetches canonical SVG markup and is unavailable for portrait avatars.

Getting started

Assets

Integrations

Reference

Installation

Agent skill

Configuration

Icons

Avatars

QR codes

Placeholders

​Installation

​Agent skill

​Configuration

​Icons

​Avatars

​QR codes

​Placeholders

Installation

Agent skill

Configuration

Icons

Avatars

QR codes

Placeholders