Incorrect description of UnresolvedImageTransform in getImage()

[decipher-cs]

📚 Subject area/topic

Image service, getImage

📋 Page(s) affected (or suggested, for new content)

https://docs.astro.build/en/reference/modules/astro-assets/#getimage

📋 Description of content that is out-of-date or incorrect

According to the docs

This [getImage] takes an options object with the same properties as the Image component (except alt) and returns a GetImageResult object.

But hat's not the case. getImage() also doesn't accept layout property.

🖥️ Reproduction in StackBlitz (if reporting incorrect content or code samples)

No response

[sarah11918]

Hi, thanks for this! We did have to do some docs updating and moving things around when Responsive Images were no longer an experimental feature, and it looks like we didn't double check that this older existing text was still the case!

I'll ask @Princesseuh or @ascorbic to help us figure out whether in fact the layout property is also unavailable, whether it's the only other one, and if so, how we should best mention that in docs!

(Will also note, we are on a docs freeze for v5 docs, so if a change is needed, let's please think of it in terms of what the v6 astro:assets docs currently look like. If something needs updating, it's fine to make a PR to the v6 branch to correct it, but at this late stage of the game, I would not update our main docs for this right now.)

[kailauber]

Confirming from source on main (packages/astro/src/assets/types.ts, lines 70–94 and 107–232):

• getImage() accepts UnresolvedImageTransform, which extends ImageTransform — not ImageSharedProps.
• The <Image /> component (LocalImageProps / RemoteImageProps) extends ImageSharedProps.

Properties on ImageSharedProps that are not on ImageTransform, and therefore unavailable to getImage():

• alt (already noted in the docs)
• layout (the OP's finding — confirmed)
• priority
• widths / densities (these live in the discriminated union with layout)

Suggested wording for the affected sentence (line 649 of astro-assets.mdx):

This takes an options object with the same properties as the ImageTransform type, plus an additional inferSize property and a different src type, and returns a GetImageResult object. Note that alt, layout, priority, widths, and densities are not accepted — those are properties of the <Image /> component only.

Happy to open a PR against the v6 branch once content lands there (currently it only has redirects).

[kailauber]

Correction to my previous analysis — I checked the actual getImage() implementation in packages/astro/src/assets/internal.ts and was wrong on several points:

1. widths and densities ARE on ImageTransform (explicitly typed at types.ts:85-86). Both are read by the image service. My earlier statement that they were Image-only was incorrect.

2. layout IS handled by getImage() at runtime:

   // internal.ts:141
   const layout = options.layout ?? imageConfig.layout ?? 'none';

   When non-'none', it triggers widths generation, sets sizes, and writes data-astro-image.

3. priority IS handled by getImage() at runtime:

   // internal.ts:143-153
   if (resolvedOptions.priority) {
     resolvedOptions.loading ??= 'eager';
     resolvedOptions.decoding ??= 'sync';
     resolvedOptions.fetchpriority ??= 'high';
   }

4. Only alt has no runtime effect on getImage() — it's purely a <Image />-render-time concern.

The user's confusion likely comes from TypeScript autocomplete: ImageTransform does not list layout or priority as named properties (they're only accepted via the [key: string]: any index signature), so IDEs don't suggest them. But they do work at runtime.

So the docs sentence as written ("except alt") is actually accurate for runtime behaviour. What it's missing is:

• a) The unique inferSize option that UnresolvedImageTransform adds on top of ImageTransform, and
• b) Optionally, a note that layout/priority work at runtime but aren't surfaced in the TypeScript signature.

Happy to open a PR adding the inferSize mention and a clarifying note about layout/priority typing if that direction sounds right to you @sarah11918 / @Princesseuh / @ascorbic.

[decipher-cs]

@kailauber can't help but wonder, is that AI?