Square Image Placeholders for Avatars and Product Tiles

Square URL syntax

Using the square route for 1:1 aspect ratio placeholders

The square route takes a single size parameter and generates an image with equal width and height. This is cleaner than /NxN for cases where the aspect ratio is always 1:1 — you specify the dimension once instead of repeating it.

The URL format is /api/v1/square/{size} where size is the pixel dimension of both sides. All other parameters — background color, text color, text label — follow the same conventions as the standard dimension route.

<!-- Small avatar: 40×40 -->
<img
  src="https://fallback.pics/api/v1/square/40"
  width="40"
  height="40"
  loading="lazy"
  decoding="async"
  alt="User avatar"
/>

<!-- Medium product tile: 200×200 with label -->
<img
  src="https://fallback.pics/api/v1/square/200?text=Product"
  width="200"
  height="200"
  loading="lazy"
  alt="Product placeholder"
/>

<!-- Large team member card: 400×400 with initials -->
<img
  src="https://fallback.pics/api/v1/square/400?text=JD"
  width="400"
  height="400"
  loading="lazy"
  alt="Team member photo"
/>

Avatar placeholders

Initials-based avatar placeholders for user profiles

When a user has not uploaded a profile picture, showing initials in a colored circle is a common and readable fallback. Use the text parameter to pass one or two characters representing the user's initials, and set a background color using a hash of the user's name or ID to produce a consistent, personalized color per user.

Hash-based color selection is worth implementing: it gives each user a unique placeholder color based on their identity rather than showing the same color for every missing avatar. A simple djb2 or FNV hash of the user ID, mapped to one of six or eight brand-adjacent palette colors, produces consistent and visually differentiated avatars.

The avatar route (/api/v1/avatar/{size}) produces a circular-styled avatar placeholder with a round background shape, which is appropriate for circular avatar UI. The square route produces a rectangular placeholder that works better for square-cropped product tiles and team cards.

// Generate a consistent color for a user based on their ID
function getUserPlaceholderColor(userId: string): string {
  const colors = ['7C3AED', '3B82F6', '10B981', 'F97316', 'EF4444', '8B5CF6'];
  let hash = 0;
  for (let i = 0; i < userId.length; i++) {
    hash = (hash * 31 + userId.charCodeAt(i)) >>> 0;
  }
  return colors[hash % colors.length];
}

function getInitials(name: string): string {
  return name.split(' ').map((n) => n[0]).join('').slice(0, 2).toUpperCase();
}

function avatarUrl(user: { id: string; name: string }, size = 80): string {
  const color = getUserPlaceholderColor(user.id);
  const initials = getInitials(user.name);
  return `https://fallback.pics/api/v1/square/${size}/${color}/FFFFFF?text=${initials}`;
}

Product grids

Square product tile placeholders for ecommerce catalogs

Product grid thumbnails are commonly square, especially for fashion, beauty, and consumer electronics where the product photography is shot against a white or neutral background at a consistent aspect ratio. A 1:1 grid is easier to build and maintain than a variable-aspect-ratio grid.

Use a neutral light-gray background (E4E4E7 on light mode, 27272A on dark mode) for product tile placeholders without a text label. This mimics the appearance of an image loading and avoids showing dimensions or labels that would break the visual consistency of a product grid.

For product tiles where the category or product name is known at render time, add a short text label. This makes the placeholder scannable even before the real image loads, which can help user orientation in long lazy-loaded grids.

<!-- Product grid: neutral square placeholders (no text) -->
{products.map((product) => (
  <div key={product.id} className="product-tile">
    <img
      src={product.imageUrl ||
        `https://fallback.pics/api/v1/square/400/E4E4E7/E4E4E7`}
      width="400"
      height="400"
      loading="lazy"
      decoding="async"
      alt={product.name}
      onError={(e) => {
        e.currentTarget.src =
          `https://fallback.pics/api/v1/square/400/E4E4E7/71717A?text=${
            encodeURIComponent(product.category || 'Product')
          }`;
      }}
    />
    <p>{product.name}</p>
  </div>
))}

Icon and logo slots

App icon and integration logo placeholders

Marketplaces, app stores, and integration directories display vendor or app logos in square or circular tiles. When a vendor has not uploaded a logo, showing their company initials on a branded background is more informative than a broken image or a generic icon.

Use the same hash-based color assignment for company logos as for user avatars — consistent color per company makes logos easier to recognize across the product, even without the real logo asset. Use the first letter of the company name as the text label.

<!-- Integration logo grid with initials fallback -->
{integrations.map((integration) => (
  <div key={integration.id} className="integration-tile">
    <img
      src={integration.logoUrl ||
        `https://fallback.pics/api/v1/square/64/${getColor(integration.id)}/FFFFFF?text=${
          integration.name[0].toUpperCase()
        }`}
      width="64"
      height="64"
      alt={`${integration.name} logo`}
      onError={(e) => {
        e.currentTarget.src =
          `https://fallback.pics/api/v1/square/64/${getColor(integration.id)}/FFFFFF?text=${
            integration.name[0].toUpperCase()
          }`;
      }}
    />
    <span>{integration.name}</span>
  </div>
))}

Dark mode

Square placeholder colors for light and dark mode grids

Product grids and avatar stacks need placeholder colors that work in both light and dark mode. A single neutral gray background works acceptably in both, but purpose-built dark mode placeholders look more polished.

In light mode, use E4E4E7 (zinc-200) or F4F4F5 (zinc-100) for neutral product tile backgrounds. In dark mode, use 27272A (zinc-800) or 3F3F46 (zinc-700). For CSS-driven dark mode, set the placeholder src conditionally or use a prefers-color-scheme media query to swap the background image.

# API docs
https://fallback.pics/docs/
https://fallback.pics/placeholder-image-api/

# Related posts
https://fallback.pics/blog/banner-placeholder-iab-ad-sizes/
https://fallback.pics/blog/avatar-placeholder-generator-initials-colors-accessibility/

Caching

Square placeholder URLs and CDN cache efficiency

The square route produces deterministic output: the same URL always generates the same image. This makes it safe to cache with immutable Cache-Control headers for up to a year. For a product catalog with stable placeholder URLs, the CDN warms up quickly and subsequent page loads see near-zero latency on placeholder fetches.

Using the same placeholder URL for all products without a photo — rather than per-product dynamic URLs — maximizes cache efficiency. A single URL cached at the edge serves thousands of product cards without any repeat origin fetches.