Nuxt 3 Image Component Fallbacks and Error Handling

Setup

Configure @nuxt/image for external domains

@nuxt/image is installed separately from Nuxt core and requires a provider configured in nuxt.config.ts. For simple external URLs and fallback.pics, the ipx provider or no provider at all works fine — the URLs are fully formed public endpoints.

Add fallback.pics and any other external image domains to the image.domains array so @nuxt/image can proxy or optimize them if needed.

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/image'],
  image: {
    domains: ['fallback.pics', 'your-cdn.example.com'],
  },
});

Error event

Handle NuxtImg load errors with the error event

NuxtImg emits an error event when the image fails to load. Bind a handler to swap src to a fallback URL. Use a ref to track the resolved source and prevent repeated error triggers.

The error event receives a native Event object. Use it to log which URL failed — useful for monitoring broken media in production dashboards.

<script setup>
const props = defineProps<{ imageSrc: string; alt: string }>();
const fallbackSrc = 'https://fallback.pics/api/v1/800x450/7C3AED/FFFFFF?text=Image+Unavailable';
const src = ref(props.imageSrc);

function onImageError() {
  if (src.value !== fallbackSrc) src.value = fallbackSrc;
}
</script>

<template>
  <NuxtImg
    :src="src"
    :alt="alt"
    width="800"
    height="450"
    @error="onImageError"
  />
</template>

Composable

Create a useImageFallback composable

Wrapping the fallback logic in a composable keeps components clean and makes the behavior testable in isolation. The composable returns a reactive src ref and an onError handler.

Accept the fallback URL as an optional parameter so the same composable covers different image slot sizes across the app.

// composables/useImageFallback.ts
export function useImageFallback(initial: string, fallback?: string) {
  const DEFAULT = 'https://fallback.pics/api/v1/800x450?text=Not+Found';
  const src = ref(initial);
  const resolvedFallback = fallback ?? DEFAULT;

  function onError() {
    if (src.value !== resolvedFallback) src.value = resolvedFallback;
  }

  return { src, onError };
}

// In a component
const { src, onError } = useImageFallback(props.imageSrc);

Server-side

Resolve fallbacks server-side in useAsyncData

When fetching content from an API, check for null or missing image fields during the useAsyncData call and substitute a fallback URL before the page renders. This prevents the broken-image icon from flashing on first paint.

Computing the fallback on the server also means social crawlers and link-preview bots see the correct og:image value — a client-side error handler does not help those cases.

// pages/blog/[slug].vue
const { data: post } = await useAsyncData('post', () =>
  $fetch(`/api/posts/${route.params.slug}`)
);

const postImage = computed(() => {
  if (!post.value) return 'https://fallback.pics/api/v1/1200x630?text=Loading';
  return post.value.image
    ?? `https://fallback.pics/api/v1/1200x630.jpg?text=${encodeURIComponent(post.value.title)}`;
});

Avatar fallbacks

User avatars with initials from the avatar route

Avatar slots in user profiles, comment sections, and admin dashboards fail when no profile photo is set. The fallback.pics avatar route accepts a text parameter for initials.

Generate initials from the user's name server-side and embed them in the fallback URL. For consistent visual output, derive a background color from the user ID.

function avatarUrl(user: { name: string; image?: string }) {
  if (user.image) return user.image;
  const initials = user.name
    .split(' ')
    .map(n => n[0])
    .join('')
    .toUpperCase()
    .slice(0, 2);
  return `https://fallback.pics/api/v1/avatar/80?text=${initials}`;
}

Performance

Prevent CLS with explicit dimensions on NuxtImg

Nuxt 3 with @nuxt/image injects width and height attributes automatically when you supply them as props. Always set these on NuxtImg — even when the image source might change to a fallback.

Keep fallback URL dimensions consistent with the main image dimensions. If the fallback.pics URL produces a different aspect ratio, you will get layout shift even after the error state is resolved.

Further reading

Docs and related patterns

The fallback.pics API reference covers all URL parameters. For Vue-specific onerror patterns without Nuxt, see the implementation guides.

https://fallback.pics/docs/
https://fallback.pics/placeholder-image-api/
https://fallback.pics/blog/fix-broken-images-html-onerror/
https://fallback.pics/blog/react-image-fallback-patterns/