Display

Image

A responsive image that reserves its space (no layout shift), loads lazily, and preloads the one above-the-fold image.

<script>
  import { Image } from "@codeatlasdev/ui";
</script>

<Image src="/hero.avif" alt="Dashboard overview" width={1200} height={630} priority />

width and height are the intrinsic pixel size of the file. The browser derives the aspect ratio from them before the image arrives, so nothing jumps when it loads, and max-width: 100% with height: auto keeps that ratio on small screens. Images are loading="lazy" and decoding="async" by default.

Use priority on the one image that is the largest thing visible on first paint (the LCP element). It loads eagerly, sets fetchpriority="high" and adds a <link rel="preload" as="image"> to <head>. Never put it on more than one image per page.

Fixed ratio

The 800 by 600 file renders at 360px wide and keeps its 4:3 box.

Code

<script lang="ts">
  import { Image } from '@codeatlasdev/ui';

  // A 4:3 placeholder, inlined so the demo needs no asset.
  const src =
    "data:image/svg+xml;utf8," +
    encodeURIComponent(
      `<svg xmlns='http://www.w3.org/2000/svg' width='800' height='600'><defs><linearGradient id='g' x1='0' y1='0' x2='1' y2='1'><stop offset='0' stop-color='#c47a15'/><stop offset='1' stop-color='#2b5fd9'/></linearGradient></defs><rect width='800' height='600' fill='url(#g)'/></svg>`
    );
</script>

<div style="max-width: 360px">
  <Image {src} alt="Gradient placeholder, 4 by 3" width={800} height={600} />
</div>

srcset and sizes

The browser picks the smallest rendition that covers the rendered width.

Two renditions of the same 16 by 9 picture

Code

<script lang="ts">
  import { Image } from '@codeatlasdev/ui';

  const svg = (w: number, h: number, c: string) =>
    "data:image/svg+xml;utf8," +
    encodeURIComponent(`<svg xmlns='http://www.w3.org/2000/svg' width='${w}' height='${h}'><rect width='${w}' height='${h}' fill='${c}'/></svg>`);
  const small = svg(400, 225, '#2b5fd9');
  const large = svg(800, 450, '#1a7a50');
</script>

<div style="max-width: 420px">
  <Image
    src={large}
    srcset={`${small} 400w, ${large} 800w`}
    sizes="(min-width: 768px) 420px, 100vw"
    alt="Two renditions of the same 16 by 9 picture"
    width={800}
    height={450}
  />
</div>

For AVIF and WebP generation at build time see Performance.

Alt text

alt is required. An image that carries no meaning passes decorative instead of alt=""; it renders alt="" with aria-hidden="true". In development the component warns when alt="" is passed without decorative, when width or height is missing, and when decorative is combined with a non-empty alt.

Props

Prop	Type	Default	Description
`src`	`string`	–	Image URL.
`alt`	`string`	–	Text alternative. Required; use `decorative` for decoration.
`width`	`number`	–	Intrinsic width in pixels. Required, with `height` it reserves the space.
`height`	`number`	–	Intrinsic height in pixels. Required.
`decorative`	`boolean`	`false`	Renders `alt=""` and `aria-hidden="true"`.
`priority`	`boolean`	`false`	Eager load, `fetchpriority="high"` and a preload link in `<head>`. One per page, for the LCP image.
`loading`	`'lazy' \| 'eager'`	`'lazy' ('eager' with priority)`	Overrides the default.
`decoding`	`'async' \| 'sync' \| 'auto'`	`'async'`	Decode hint.
`class`	`string`	`''`	Extra class names.

Other <img> attributes are forwarded as they are. srcset and sizes are the ones you will use most: srcset lists the candidate renditions and sizes tells the browser the rendered width. With priority, both are copied onto the preload link in <head>. fetchpriority is controlled by priority.