React

The @freeplaceholder/react package provides type-safe <Placeholder> and <Avatar> components for React.

Installation

bash

npm install https://github.com/freeplaceholder/react

Placeholder Component

tsx

import { Placeholder } from "@freeplaceholder/react";

function Hero() {
  return (
    <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	thin, light, normal, medium, semibold, bold, extrabold, black
opacity	number	0–100
blur	number	Gaussian blur 0–100 px
brightness	number	0–200 (100 = normal)
contrast	number	0–200 (100 = normal)
hueRotate	number	0–360 degrees
invert	boolean	Invert colors
saturate	number	0–200 (100 = normal)
sepia	boolean	Sepia tone
grayscale	boolean	Grayscale filter
border	number	Border width in px
borderColor	string	Border hex color
borderStyle	BorderStyle	solid, dashed, dotted, double, none
rounded	`Rounded \	number`	sm, md, lg, xl, 2xl, 3xl, full, or px
lazy	boolean	Enable lazy loading (default: true)

All standard <img> HTML attributes are also supported.

Avatar Component

tsx

import { Avatar } from "@freeplaceholder/react";

function UserCard({ user }) {
  return (
    <Avatar
      name={user.name}
      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

If you need just the URL without a component:

tsx

import { avatarUrl, placeholderUrl, snippetUrl } from "@freeplaceholder/react";

const src = placeholderUrl({ width: 600, height: 400, bg: "3b82f6" });
const avatar = avatarUrl({ name: "John Doe", size: 256, format: "png" });
const og = snippetUrl({ title: "Hello", subtitle: "World", cta: "Learn more", format: "png" });

TypeScript

All types are exported for use in your own components:

tsx

import type {
  PlaceholderComponentProps,
  AvatarComponentProps,
  FontWeight,
  BorderStyle,
  TextAlign,
} from "@freeplaceholder/react";

Overriding Base URL

tsx

import { configure } from "@freeplaceholder/react";

configure({ baseUrl: "https://my-custom-instance.com" });