Image Dimensions

Created May 28, 2026Updated Jun 11, 2026Takeshi Takatsudo

Injects width/height attributes on images from disk metadata at build time.

The imageDimensions feature reads image file headers at build time and injects width and height attributes onto local <img> elements, preventing Cumulative Layout Shift (CLS) by letting the browser reserve space before the image loads.

Functional since zfb next.38

Through zfb 0.1.0-next.35 this feature was a no-op for public-directory absolute paths — an image such as ![alt](/img/x.png) was emitted with no width/height injected. As of zfb 0.1.0-next.38 it works: dimensions are injected for public-directory images on this corpus, and a missing file produces a cannot stat build warning.

Configuration

It is an object-typed feature, so it must be given an options object ({} or fields):

zfb.config.ts

export default defineConfig({
  markdown: {
    features: {
      imageDimensions: {},
    },
  },
});

Behavior

For each image element, the feature:

Skips elements that already carry a width or height attribute.
Ignores remote URLs (http://, https://, //) and data: URLs.
Resolves the src to an absolute file path on disk.
Reads only the image file header and injects the resolved dimensions.
Emits a build warning if the file is missing or unrecognized.

Supported formats: PNG, JPEG, GIF, WebP, AVIF.

Path resolution

Path form	Resolves against
Absolute (`/img/hero.png`)	the `public` directory
Relative (`./assets/hero.png`)	the markdown file's directory
Remote / `data:`	skipped silently

Options

Option	Default	Description
`skipRemote`	`true`	When `false`, remote images are probed during the build instead of being skipped.

Syntax

A standard markdown image is all that is required — no special syntax:

![Hero image](/img/hero.png)

The output for a 400×300 PNG is:

<img src="/img/hero.png" alt="Hero image" width="400" height="300" />

View source on GitHub