QsImage

<qs-image>alpha

An image that loads light and never shifts the layout. width and height reserve its exact space, a placeholder fills it until the file arrives, then the image fades in. Loads lazily and decodes off the main thread by default; srcset and sizes let the browser pick the smallest file that fits. Without src, or if the file fails, the placeholder stays.

Examples

<qs-image
  src="/images/proof-800.jpg"
  srcset="/images/proof-400.jpg 400w, /images/proof-800.jpg 800w, /images/proof-1600.jpg 1600w"
  sizes="(max-width: 720px) 100vw, 640px"
  width="1600" height="1066"
  alt="Print proof: an ink block, a vermilion square and ruled lines on a paper grid"></qs-image>

<qs-image width="16" height="9"></qs-image>  <!-- placeholder only -->

Prop

Prop	Type	Default	Description
src	string	""	Image URL. Leave empty to show the placeholder only.
srcset	string	""	Candidate files with their widths (`/a-400.jpg 400w, /a-800.jpg 800w`), so the browser downloads the smallest one that fits.
sizes	string	""	How wide the image is shown, for `srcset` (`(max-width: 600px) 100vw, 600px`).
alt	string	""	Text alternative. Describe what the image shows; leave empty only when it is purely decorative.
width	string	""	Intrinsic width (or the ratio's first number). Required with `height`: together they reserve the space.
height	string	""	Intrinsic height (or the ratio's second number).
loading	"lazy" | "eager"	"lazy"	`lazy` (default) waits until the image is near the viewport; use `eager` for the main image above the fold.
text	string	—	The text content of the element, captured from light DOM before the first render.

Usage

Use qs-image for content images. It does three things a bare <img> needs you to remember.

No layout shift

width and height reserve the exact space before the file arrives, so text below never jumps (Cumulative Layout Shift). Give the file's real size, or just its ratio (16 and 9). The image then scales to its container's width.

Light by default

• loading="lazy": the file is only fetched when the image comes near the viewport. Use loading="eager" for the main image at the top of the page (your Largest Contentful Paint).
• decoding="async": decoding happens off the main thread.
• srcset + sizes: list the same picture at several widths and say how wide it is shown; the browser downloads the smallest file that is sharp enough. In the example above a phone fetches the 400px file (8 KB) instead of the 1600px one (50 KB).

Export compressed files too: JPEG or WebP at about 70–75% quality for photos, SVG for flat artwork.

Placeholder

Until the file has loaded, the box shows the sunken surface and an image icon; the picture then fades in over --duration-enter. With no src the placeholder stays, which is useful for wireframes and empty states. If the file fails, the placeholder stays too, and the alt text is still read by screen readers.

Do and don't

• Do describe what the image shows in alt, as you would to someone on the phone.
• Do leave alt empty only for purely decorative images; screen readers then skip them.
• Don't omit width and height; without them the page jumps when the image loads.
• Don't lazy-load the first big image on the page.

Accessibility

• Renders a native <img> with your alt; the placeholder icon is decorative (aria-hidden).
• The fade only changes opacity, so it stays under reduced motion; there is no movement.