The @freeplaceholder/astro package provides <Placeholder> and <Avatar> Astro components that render at build time with zero client-side JavaScript.
Installation
bash
npm install https://github.com/freeplaceholder/astroPlaceholder Component
astro
---
import Placeholder from "@freeplaceholder/astro/Placeholder.astro";
---
<Placeholder
width={800}
height={400}
text="Hero Banner"
format="webp"
bg="3b82f6"
textColor="ffffff"
fontWeight="bold"
rounded="lg"
/>Placeholder Props
| Prop | Type | Description | |
|---|---|---|---|
| width | number | Image width in px (required) | |
| height | number | Image height in px (required) | |
| format | ImageFormat | Output format: svg, png, jpg, webp | |
| bg | string | Background hex color | |
| gradient | GradientDirection | to-t, to-tr, to-r, to-br, to-b, to-bl, to-l, to-tl, radial | |
| from | string | Gradient start color — hex without # | |
| via | string | Gradient middle color — hex without # | |
| to | string | Gradient end color — hex without # | |
| textColor | string | Text hex color | |
| text | string | Custom text overlay | |
| textSize | number | Font size in px | |
| textAlign | TextAlign | left, center, right | |
| textTransform | TextTransform | uppercase, lowercase, capitalize, none | |
| textDecoration | TextDecoration | underline, overline, line-through, none | |
| letterSpacing | `LetterSpacing \ | string` | tighter, tight, wide, wider, widest, or px |
| fontWeight | FontWeight | Font weight | |
| opacity | number | 0–100 | |
| grayscale | boolean | Grayscale filter | |
| blur | number | Gaussian blur 0–100 px | |
| brightness | number | 0–200 | |
| contrast | number | 0–200 | |
| hueRotate | number | 0–360 degrees | |
| invert | boolean | Invert colors | |
| saturate | number | 0–200 | |
| sepia | boolean | Sepia tone | |
| border | number | Border width in px | |
| borderColor | string | Border hex color | |
| borderStyle | BorderStyle | Border style | |
| rounded | `Rounded \ | number` | Border radius |
| lazy | boolean | Enable lazy loading (default: true) |
Additional HTML <img> attributes are spread onto the rendered element.
Avatar Component
astro
---
import Avatar from "@freeplaceholder/astro/Avatar.astro";
---
<Avatar
name="John Doe"
size={64}
format="png"
fontWeight="bold"
border={2}
borderColor="ffffff"
/>Avatar Props
| Prop | Type | Description | |
|---|---|---|---|
| name | string | Name to derive initials from (required) | |
| size | number | Square dimensions in px (default: 128) | |
| format | ImageFormat | Output format | |
| bg | string | Background hex color | |
| gradient | GradientDirection | to-t, to-tr, to-r, to-br, to-b, to-bl, to-l, to-tl, radial | |
| from | string | Gradient start color — hex without # | |
| via | string | Gradient middle color — hex without # | |
| to | string | Gradient end color — hex without # | |
| textColor | string | Text hex color | |
| textDecoration | TextDecoration | underline, overline, line-through, none | |
| letterSpacing | `LetterSpacing \ | string` | Letter spacing |
| fontWeight | FontWeight | Font weight | |
| opacity | number | 0–100 | |
| blur | number | Gaussian blur 0–100 px | |
| brightness | number | 0–200 | |
| contrast | number | 0–200 | |
| hueRotate | number | 0–360 degrees | |
| invert | boolean | Invert colors | |
| saturate | number | 0–200 | |
| sepia | boolean | Sepia tone | |
| grayscale | boolean | Grayscale filter | |
| border | number | Border width in px | |
| borderColor | string | Border hex color | |
| borderStyle | BorderStyle | Border style | |
| rounded | `Rounded \ | number` | Border radius |
| lazy | boolean | Enable lazy loading (default: true) |
URL Helpers
For use in frontmatter or scripts:
astro
---
import { avatarUrl, placeholderUrl, snippetUrl } from "@freeplaceholder/astro";
const hero = placeholderUrl({ width: 1920, height: 1080, format: "webp", grayscale: true });
const avatar = avatarUrl({ name: "Alice", size: 96 });
const og = snippetUrl({ title: "Hello", format: "png" });
---
<img src={hero} alt="Hero" />
<img src={avatar} alt="Alice" />
<img src={og} alt="" width="1200" height="630" />Overriding Base URL
astro
---
import { configure } from "@freeplaceholder/astro";
configure({ baseUrl: "https://my-custom-instance.com" });
---