VercelImage

Turn a hi-res origin image into a responsive image using Vercel's Image Optimization API.

Properties

Property	Type	Required	Description
`src`	`string`	yes	URL to origin image.
`alt`	`string`	yes	Alt text (not caption) .
`sizes`	`string`	no	Size hints. If not specified, it defaults to `"100vw"`.
`intrinsicWidth`	`number`	no	Optimize generated `srcset` when provided.
`aspectRatio`	`string \| number`	no	Override intrinsic aspect ratio. `"1 / 1"` or `1.0`, not `1`.
`loading`	`'lazy' \| 'eager'`	no	Defaults to `"lazy"`.
`class`	`string`	no	Tailwind v4 classes.

Examples

Origin image in the cloud

The default use case for VercelImage is that the origin image is hosted in the cloud:

<script lang="ts">
	import { VercelImage } from '$lib/components/index.js';
</script>

<VercelImage
	src="https://unsplash.com/photos/XWHqMeAAzTI/download?ixid=M3wxMjA3fDB8MXxhbGx8fHx8fHx8fHwxNzUwMzY0ODYyfA&force=true"
	alt="Cube houses in Rotterdam."
	sizes="(max-width: 1024px) 100vw, 1024px"
	aspectRatio="16 / 9"
/>

Local origin images

If your origin image is part of your SvelteKit website’s repository, we can import it and obtain its root-relative path. VercelImage can handle root-relative paths because Vercel’s Image Optimization API supports them.

The following example renders a local origin image:

<script lang="ts">
	import { VercelImage } from '$lib/components/index.js';
	import { stripOrigin } from '$lib/utils/index.js';
	import src from './adrien-milcent-XWHqMeAAzTI-unsplash.jpg';

	const rootRelativePath = stripOrigin(src);
</script>

<VercelImage
	src={rootRelativePath}
	alt="Cube houses in Rotterdam."
	sizes="(max-width: 1024px) 100vw, 1024px"
	aspectRatio="4 / 3"
/>

Note that VercelImage suppresses the generation of srcset while in dev mode. The browser then sees an img tag with only a src prop containing a root-relative path. This ensures that images are rendered during dev.