Default dog avatars for pet profiles

A profile with no photo looks empty. A good default is the breed's head portrait, shown until the owner uploads a picture of their own dog. It gives the profile a face, matches every other default in the list, and signals that a real photo can replace it.

The pattern

Pick the avatar in this order:

1. The owner's uploaded photo, if there is one.
2. The head portrait of the dog's breed, if you know the breed and the catalog has it.
3. A neutral placeholder of your own design.

The second step is a default, not a substitute. A profile card with the breed head and a small "Illustration" label tells a visitor that the owner has not added a photo yet. When they upload one, you replace it with no change to the layout.

Why the head portrait

The head view is made for this. Like all views in the set, it is on a square, transparent canvas, so it fits a round or square avatar without cropping. A tinted background color of your own shows through the transparency, so you can color the frame by species, account type or theme. Every breed uses the same format, so a list of avatars lines up.

The images are AI-generated illustrations of one adult dog. They show no real dog and are not a breed standard. That is a good reason to label them. Under or beside the avatar, write "Breed illustration" or similar, and keep the owner's own photo clearly separate when they add it.

Sizes

Previews come in two sizes, 512 and 1024 pixels, both WebP. Choose by where the avatar shows:

• List rows and comment threads, up to about 64 CSS pixels: the 512 file. It stays sharp on high density screens.
• Profile header, about 128 to 256 CSS pixels: the 512 file is enough on standard screens. Use 1024 when the avatar is large or the screen is high density.

Do not pick 1024 for a long list. It sends more bytes than the layout can use. Preview files carry a one-year immutable cache header, so repeat visits cost little once a file is cached.

Unknown and mixed breeds

Some owners do not know the breed, and many dogs are mixes. The catalog has crossbreed entries such as doodles, and each breed has a crossbreed flag you can use to tag them. It has no generic "mixed breed" entry. So when the profile says "mixed" or "unknown", do not map it to the nearest breed. That would put the wrong face on someone's pet. Show your own neutral placeholder instead: a silhouette, a paw, or the initials of the pet's name.

Seven breeds have several colors. For an avatar, the breed's default_variant is enough. Let the owner pick a color only if you have a place for it.

A mapping function with a fallback

Store the breed slug in your pet record, such as golden-retriever, not the display name. The function below builds the avatar URL, and the image falls back to the placeholder if the request fails (for example, on a slug that no longer exists).

const BASE = "https://dogimage.dev";
const PLACEHOLDER = "/img/pet-placeholder.svg"; // your own file

let breedMap = null;

async function loadBreeds() {
  if (breedMap) return breedMap;
  const res = await fetch(`${BASE}/api/v1/breeds`);
  if (!res.ok) throw new Error(`Breed list failed: ${res.status}`);
  const { breeds } = await res.json();
  breedMap = new Map(breeds.map((b) => [b.slug, b]));
  return breedMap;
}

export async function avatarFor(pet) {
  if (pet.photoUrl) return { src: pet.photoUrl, isIllustration: false };
  const breeds = await loadBreeds();
  const breed = pet.breedSlug ? breeds.get(pet.breedSlug) : null;
  if (!breed) return { src: PLACEHOLDER, isIllustration: false };
  return {
    src: `${BASE}/api/v1/images/${breed.slug}/${breed.default_variant}/head?size=512`,
    isIllustration: true,
    creditHref: `${BASE}/dogs/${breed.slug}`,
    creditText: `${breed.name} image: Dog Image API`,
    alt: `Illustration of a ${breed.name}`,
  };
}

export function renderAvatar(el, avatar, petName) {
  const img = document.createElement("img");
  img.src = avatar.src;
  img.alt = avatar.alt ?? petName;
  img.width = 64;
  img.height = 64;
  img.onerror = () => { img.src = PLACEHOLDER; };
  el.append(img);
}

Call loadBreeds once per page, then reuse the map for every pet in a list. The URL redirects to the WebP preview, which an <img> tag follows. Cross-origin reads of the breed list are allowed, so this runs in the browser with no key.

Credit link and labels

Preview use requires a visible credit link next to the image or on the same page. For a list of many avatars, one line in the page footer or a "Breed illustrations" note near the list is enough, as long as it is visible and links to Dog Image API. On a single profile page, use the exact snippet from the breed page:

<a href="https://dogimage.dev/dogs/beagle">Beagle image: Dog Image API</a>

If you would rather not show a credit link, download full-size files on a server or in a build step and host them yourself. Full-size files need a key and a plan, and you read the key from DOG_IMAGE_API_KEY. Check the pricing page for what a plan covers and the license for what the files may be used for. For a native app version of this pattern, see SwiftUI pet profile breed images. To look at the heads, open any breed on the breeds page.